https://openjdk.java.net/ 
/*
 * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package com.sun.xml.internal.ws.api.pipe;

import com.sun.xml.internal.ws.api.BindingID;
import com.sun.xml.internal.ws.api.WSBinding;
import com.sun.xml.internal.ws.api.message.Message;
import com.sun.xml.internal.ws.api.message.Packet;
import com.sun.xml.internal.ws.api.server.EndpointAwareCodec;

import javax.xml.stream.XMLStreamWriter;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.ByteBuffer;
import java.nio.channels.ReadableByteChannel;
import java.nio.channels.WritableByteChannel;


Encodes a Message (its XML infoset and attachments) to a sequence of bytes. 

This interface provides pluggability for different ways of encoding XML infoset,
such as plain XML (plus MIME attachments), XOP, and FastInfoset.

 Transport usually needs a MIME content type of the encoding, so the Codec interface is designed to return this information. However, for some encoding (such as XOP), the encoding may actually change based on the actual content of Message, therefore the codec returns the content type as a result of encoding. 
 Codec does not produce transport-specific information, such as HTTP headers. 
 Codec implementations should be thread-safe; a codec instance could be used concurrently in multiple threads. If a codec have to generate or use a per-request state, the codec implementation must store the state in the Packet instead of using an instance variable of the codec implementation. 
 BindingID determines the Codec. See BindingID.createEncoder(WSBinding). 
Author:Kohsuke Kawaguchi, shih-chang.chen@oracle.com
See Also:
/**
 * Encodes a {@link Message} (its XML infoset and attachments) to a sequence of bytes.
 *
 * <p>
 * This interface provides pluggability for different ways of encoding XML infoset,
 * such as plain XML (plus MIME attachments), XOP, and FastInfoset.
 *
 * <p>
 * Transport usually needs a MIME content type of the encoding, so the {@link Codec}
 * interface is designed to return this information. However, for some encoding
 * (such as XOP), the encoding may actually change based on the actual content of
 * {@link Message}, therefore the codec returns the content type as a result of encoding.
 *
 * <p>
 * {@link Codec} does not produce transport-specific information, such as HTTP headers.
 *
 * <p>
 * {@link Codec} implementations should be thread-safe; a codec instance could be used
 * concurrently in multiple threads. If a codec have to generate or use a per-request
 * state, the codec implementation must store the state in the Packet instead of using an
 * instance variable of the codec implementation.
 *
 * <p>
 * {@link BindingID} determines the {@link Codec}. See {@link BindingID#createEncoder(WSBinding)}.
 *
 * @author Kohsuke Kawaguchi
 * @author shih-chang.chen@oracle.com
 *
 * @see EndpointAwareCodec
 */
public interface Codec {

    
Get the MIME type associated with this Codec.


If available the MIME type will represent the media that the codec
encodes and decodes.
The MIME type returned will be the most general representation independent
of an instance of this MIME type utilized as a MIME content-type.

Returns:
     null if the MIME type can't be determined by the Codec
     implementation. Otherwise the MIME type is returned.
/**
     * Get the MIME type associated with this Codec.
     * <p>
     * If available the MIME type will represent the media that the codec
     * encodes and decodes.
     *
     * The MIME type returned will be the most general representation independent
     * of an instance of this MIME type utilized as a MIME content-type.
     *
     * @return
     *      null if the MIME type can't be determined by the <code>Codec</code>
     *      implementation. Otherwise the MIME type is returned.
     */
    public String getMimeType();

    
If the MIME content-type of the encoding is known statically
then this method returns it.

 Transports often need to write the content type before it writes the message body, and since the encode method returns the content type after the body is written, it requires a buffering. For those Codecs that always use a constant content type, This method allows a transport to streamline the write operation. 
Returns: null if the content-type can't be determined in short of encodin the packet. Otherwise content type for this Packet, such as "application/xml".
/**
     * If the MIME content-type of the encoding is known statically
     * then this method returns it.
     *
     * <p>
     * Transports often need to write the content type before it writes
     * the message body, and since the encode method returns the content type
     * after the body is written, it requires a buffering.
     *
     * For those {@link Codec}s that always use a constant content type,
     * This method allows a transport to streamline the write operation.
     *
     * @return
     *      null if the content-type can't be determined in short of
     *      encodin the packet. Otherwise content type for this {@link Packet},
     *      such as "application/xml".
     */
    ContentType getStaticContentType(Packet packet);

    
Encodes an XML infoset portion of the Message (from <soap:Envelope> to </soap:Envelope>). 
 Internally, this method is most likely invoke Message.writeTo(XMLStreamWriter) to turn the message into infoset. 
Params:
  • packet – 
  • out – 
     Must not be null. The caller is responsible for closing the stream,
     not the callee.
Throws:
Returns:
     The MIME content type of the encoded message (such as "application/xml").
     This information is often ncessary by transport.
/**
     * Encodes an XML infoset portion of the {@link Message}
     * (from &lt;soap:Envelope> to &lt;/soap:Envelope>).
     *
     * <p>
     * Internally, this method is most likely invoke {@link Message#writeTo(XMLStreamWriter)}
     * to turn the message into infoset.
     *
     * @param packet
     * @param out
     *      Must not be null. The caller is responsible for closing the stream,
     *      not the callee.
     *
     * @return
     *      The MIME content type of the encoded message (such as "application/xml").
     *      This information is often ncessary by transport.
     *
     * @throws IOException
     *      if a {@link OutputStream} throws {@link IOException}.
     */
    ContentType encode( Packet packet, OutputStream out ) throws IOException;

    
The version of encode(Packet, OutputStream) that writes to NIO ByteBuffer. 
 TODO: for the convenience of implementation, write an adapter that wraps WritableByteChannel to OutputStream. 
/**
     * The version of {@link #encode(Packet,OutputStream)}
     * that writes to NIO {@link ByteBuffer}.
     *
     * <p>
     * TODO: for the convenience of implementation, write
     * an adapter that wraps {@link WritableByteChannel} to {@link OutputStream}.
     */
    ContentType encode( Packet packet, WritableByteChannel buffer );

    /*
     * The following methods need to be documented and implemented.
     *
     * Such methods will be used by a client side
     * transport pipe that implements the ClientEdgePipe.
     *
    String encode( InputStreamMessage message, OutputStream out ) throws IOException;
    String encode( InputStreamMessage message, WritableByteChannel buffer );
    */

    
Creates a copy of this Codec. 
 Since Codec instance is not re-entrant, the caller who needs to encode two Messages simultaneously will want to have two Codec instances. That's what this method produces. 
Implentation Note


 Note that this method might be invoked by one thread while another thread is executing one of the encode methods. 

This should be OK because you'll be only copying things that
are thread-safe, and creating new ones for thread-unsafe resources,
but please let us know if this contract is difficult.

Returns: always non-null valid Codec that performs the encoding work in the same way --- that is, if you copy an FI codec, you'll get another FI codec. 
 Once copied, two Codecs may be invoked from two threads concurrently; therefore, they must not share any state that requires isolation (such as temporary buffer.) 
 If the Codec implementation is already re-entrant and multi-thread safe to begin with, then this method may simply return this.
/**
     * Creates a copy of this {@link Codec}.
     *
     * <p>
     * Since {@link Codec} instance is not re-entrant, the caller
     * who needs to encode two {@link Message}s simultaneously will
     * want to have two {@link Codec} instances. That's what this
     * method produces.
     *
     * <h3>Implentation Note</h3>
     * <p>
     * Note that this method might be invoked by one thread while
     * another thread is executing one of the {@link #encode} methods.
     * <!-- or otherwise you'd always have to maintain one idle copy -->
     * <!-- just so that you can make copies from -->
     * This should be OK because you'll be only copying things that
     * are thread-safe, and creating new ones for thread-unsafe resources,
     * but please let us know if this contract is difficult.
     *
     * @return
     *      always non-null valid {@link Codec} that performs
     *      the encoding work in the same way --- that is, if you
     *      copy an FI codec, you'll get another FI codec.
     *
     *      <p>
     *      Once copied, two {@link Codec}s may be invoked from
     *      two threads concurrently; therefore, they must not share
     *      any state that requires isolation (such as temporary buffer.)
     *
     *      <p>
     *      If the {@link Codec} implementation is already
     *      re-entrant and multi-thread safe to begin with,
     *      then this method may simply return {@code this}.
     */
    Codec copy();

    
Reads bytes from InputStream and constructs a Message. 
 The design encourages lazy decoding of a Message, where a Message is returned even before the whole message is parsed, and additional parsing is done as the Message body is read along. A Codec is most likely have its own implementation of Message for this purpose. 
Params:
  • in –  the data to be read into a Message. The transport would have read any transport-specific header before it passes an InputStream, and InputStream is expected to be read until EOS. Never null. 
     Some transports, such as SMTP, may 'encode' data into another format (such as uuencode, base64, etc.) It is the caller's responsibility to 'decode' these transport-level encoding before it passes data into Codec.
  • contentType –  The MIME content type (like "application/xml") of this byte stream. Thie text includes all the sub-headers of the content-type header. Therefore, in more complex case, this could be something like multipart/related; boundary="--=_outer_boundary"; type="multipart/alternative". This parameter must not be null.
  • response –  The parsed Message will be set to this Packet. Codec may add additional properties to this Packet. On a successful method completion, a Packet must contain a Message.
Throws:
/**
     * Reads bytes from {@link InputStream} and constructs a {@link Message}.
     *
     * <p>
     * The design encourages lazy decoding of a {@link Message}, where
     * a {@link Message} is returned even before the whole message is parsed,
     * and additional parsing is done as the {@link Message} body is read along.
     * A {@link Codec} is most likely have its own implementation of {@link Message}
     * for this purpose.
     *
     * @param in
     *      the data to be read into a {@link Message}. The transport would have
     *      read any transport-specific header before it passes an {@link InputStream},
     *      and {@link InputStream} is expected to be read until EOS. Never null.
     *
     *      <p>
     *      Some transports, such as SMTP, may 'encode' data into another format
     *      (such as uuencode, base64, etc.) It is the caller's responsibility to
     *      'decode' these transport-level encoding before it passes data into
     *      {@link Codec}.
     *
     * @param contentType
     *      The MIME content type (like "application/xml") of this byte stream.
     *      Thie text includes all the sub-headers of the content-type header. Therefore,
     *      in more complex case, this could be something like
     *      {@code multipart/related; boundary="--=_outer_boundary"; type="multipart/alternative"}.
     *      This parameter must not be null.
     *
     * @param response
     *      The parsed {@link Message} will be set to this {@link Packet}.
     *      {@link Codec} may add additional properties to this {@link Packet}.
     *      On a successful method completion, a {@link Packet} must contain a
     *      {@link Message}.
     *
     * @throws IOException
     *      if {@link InputStream} throws an exception.
     */
    void decode( InputStream in, String contentType, Packet response ) throws IOException;

    
See Also:
  • decode(InputStream, String, Packet)
/**
     *
     * @see #decode(InputStream, String, Packet)
     */
    void decode( ReadableByteChannel in, String contentType, Packet response );

    /*
     * The following methods need to be documented and implemented.
     *
     * Such methods will be used by a server side
     * transport pipe that can support the invocation of methods on a
     * ServerEdgePipe.
     *
    XMLStreamReaderMessage decode( InputStream in, String contentType ) throws IOException;
    XMLStreamReaderMessage decode( ReadableByteChannel in, String contentType );
    */
}