com.sun.xml.ws.encoding
Class StreamSOAPCodec

java.lang.Object
  extended by com.sun.xml.ws.encoding.StreamSOAPCodec
All Implemented Interfaces:
Codec, StreamSOAPCodec, RootOnlyCodec
Direct Known Subclasses:
StreamSOAP11Codec, StreamSOAP12Codec

public abstract class StreamSOAPCodec
extends Object
implements StreamSOAPCodec, RootOnlyCodec

A stream SOAP codec.


Constructor Summary
StreamSOAPCodec(SOAPVersion soapVersion)
           
 
Method Summary
 StreamSOAPCodec copy()
          Creates a copy of this Codec.
static StreamSOAPCodec create(SOAPVersion version)
          Creates a new StreamSOAPCodec instance.
protected abstract  StreamHeader createHeader(javax.xml.stream.XMLStreamReader reader, com.sun.xml.stream.buffer.XMLStreamBuffer mark)
           
 void decode(InputStream in, String contentType, Packet packet)
          Reads bytes from InputStream and constructs a Message.
 void decode(InputStream in, String contentType, Packet packet, AttachmentSet att)
          Reads root part bytes from InputStream and constructs a Message along with the given attachments.
 void decode(ReadableByteChannel in, String contentType, Packet packet)
           
 void decode(ReadableByteChannel in, String contentType, Packet response, AttachmentSet att)
           
 Message decode(javax.xml.stream.XMLStreamReader reader)
          Decodes a message from XMLStreamReader that points to the beginning of a SOAP infoset.
 Message decode(javax.xml.stream.XMLStreamReader reader, AttachmentSet attachmentSet)
          Decodes a message from XMLStreamReader that points to the beginning of a SOAP infoset.
 ContentType encode(Packet packet, OutputStream out)
          Encodes an XML infoset portion of the Message (from <soap:Envelope> to </soap:Envelope>).
 ContentType encode(Packet packet, WritableByteChannel buffer)
          The version of Codec.encode(Packet,OutputStream) that writes to NIO ByteBuffer.
protected abstract  ContentType getContentType(String soapAction)
           
protected abstract  List<String> getExpectedContentTypes()
           
 ContentType getStaticContentType(Packet packet)
          If the MIME content-type of the encoding is known statically then this method returns it.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.sun.xml.ws.api.pipe.Codec
getMimeType
 

Constructor Detail

StreamSOAPCodec

StreamSOAPCodec(SOAPVersion soapVersion)
Method Detail

getStaticContentType

public ContentType getStaticContentType(Packet packet)
Description copied from interface: Codec
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.

Specified by:
getStaticContentType in interface Codec
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".

encode

public ContentType encode(Packet packet,
                          OutputStream out)
Description copied from interface: Codec
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.

Specified by:
encode in interface Codec
out - Must not be null. The caller is responsible for closing the stream, not the callee.
Returns:
The MIME content type of the encoded message (such as "application/xml"). This information is often ncessary by transport.

getContentType

protected abstract ContentType getContentType(String soapAction)

encode

public ContentType encode(Packet packet,
                          WritableByteChannel buffer)
Description copied from interface: Codec
The version of Codec.encode(Packet,OutputStream) that writes to NIO ByteBuffer.

TODO: for the convenience of implementation, write an adapter that wraps WritableByteChannel to OutputStream.

Specified by:
encode in interface Codec

getExpectedContentTypes

protected abstract List<String> getExpectedContentTypes()

decode

public void decode(InputStream in,
                   String contentType,
                   Packet packet)
            throws IOException
Description copied from interface: Codec
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.

Specified by:
decode in interface Codec
Parameters:
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.
packet - 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:
IOException - if InputStream throws an exception.

decode

@NotNull
public final Message decode(@NotNull
                                    javax.xml.stream.XMLStreamReader reader)
Decodes a message from XMLStreamReader that points to the beginning of a SOAP infoset.

Specified by:
decode in interface StreamSOAPCodec
Parameters:
reader - can point to the start document or the start element.
Returns:
a Message for SOAP envelope

decode

public final Message decode(javax.xml.stream.XMLStreamReader reader,
                            @NotNull
                            AttachmentSet attachmentSet)
Decodes a message from XMLStreamReader that points to the beginning of a SOAP infoset.

Parameters:
reader - can point to the start document or the start element.
attachmentSet - StreamSOAPCodec can take attachments parsed outside, so that this codec can be used as a part of a biggre codec (like MIME multipart codec.)

decode

public void decode(ReadableByteChannel in,
                   String contentType,
                   Packet packet)
Specified by:
decode in interface Codec
See Also:
Codec.decode(InputStream, String, Packet)

copy

public final StreamSOAPCodec copy()
Description copied from interface: Codec
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 Codec.encode(com.sun.xml.ws.api.message.Packet, java.io.OutputStream) 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.

Specified by:
copy in interface Codec
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.


createHeader

protected abstract StreamHeader createHeader(javax.xml.stream.XMLStreamReader reader,
                                             com.sun.xml.stream.buffer.XMLStreamBuffer mark)

decode

public void decode(InputStream in,
                   String contentType,
                   Packet packet,
                   AttachmentSet att)
            throws IOException
Description copied from interface: RootOnlyCodec
Reads root part bytes from InputStream and constructs a Message along with the given attachments.

Specified by:
decode in interface RootOnlyCodec
Parameters:
in - root part's data
contentType - root part's MIME content type (like "application/xml")
packet - the new created Message is set in this packet
att - attachments
Throws:
IOException - if InputStream throws an exception.

decode

public void decode(ReadableByteChannel in,
                   String contentType,
                   Packet response,
                   AttachmentSet att)
Specified by:
decode in interface RootOnlyCodec
See Also:
RootOnlyCodec.decode(InputStream, String, Packet, AttachmentSet)

create

public static StreamSOAPCodec create(SOAPVersion version)
Creates a new StreamSOAPCodec instance.