Module com.sun.xml.ws

Package com.sun.xml.ws.encoding

Class MimeCodec

java.lang.Object

com.sun.xml.ws.encoding.MimeCodec

All Implemented Interfaces:

Codec

Direct Known Subclasses:

MtomCodec, SOAPBindingCodec, SwACodec, XMLHTTPBindingCodec

public abstract class MimeCodec
extends Object
implements Codec

Codecs that uses the MIME multipart as the underlying format.

When the runtime needs to dynamically choose a Codec, and when there are more than one Codecs that use MIME multipart, it is often impossible to determine the right Codec unless you parse the multipart message to some extent.

By having all such Codecs extending from this class, the "sniffer" can decode a multipart message partially, and then pass the partial parse result to the ultimately-responsible Codec. This improves the performance.

Author:

Kohsuke Kawaguchi

Field Summary

Fields

Modifier and Type	Field	Description
protected final WSFeatureList	features
protected Codec	mimeRootCodec
static final String	MULTIPART_RELATED_MIME_TYPE
protected final SOAPVersion	version

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	MimeCodec(SOAPVersion version, WSFeatureList f)
protected	MimeCodec(MimeCodec that)	Copy constructor.

Method Summary

Modifier and Type	Method	Description
abstract MimeCodec	copy()	Creates a copy of this Codec.
protected abstract void	decode(MimeMultipartParser mpp, Packet packet)	Parses a Packet from a MimeMultipartParser.
void	decode(InputStream in, String contentType, Packet packet)	Reads bytes from InputStream and constructs a Message.
void	decode(ReadableByteChannel in, String contentType, Packet packet)
ContentType	encode(Packet packet, OutputStream out)	Encodes an XML infoset portion of the Message (from <soap:Envelope> to </soap:Envelope>).
protected Codec	getMimeRootCodec(Packet packet)
String	getMimeType()	Get the MIME type associated with this Codec.
ContentType	getStaticContentType(Packet packet)	If the MIME content-type of the encoding is known statically then this method returns it.
static void	writeAsAscii(String s, OutputStream out)	Writes a string as ASCII string.
static void	writeln(OutputStream out)
static void	writeln(String s, OutputStream out)

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

encode

Field Details

MULTIPART_RELATED_MIME_TYPE

public static final String MULTIPART_RELATED_MIME_TYPE

See Also:

• Constant Field Values

mimeRootCodec

protected Codec mimeRootCodec

version

protected final SOAPVersion version

features

protected final WSFeatureList features

Constructor Details

MimeCodec

protected MimeCodec(SOAPVersion version,
 WSFeatureList f)

MimeCodec

protected MimeCodec(MimeCodec that)

Copy constructor.

Method Details

getMimeType

public String getMimeType()

Description copied from 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.

Specified by:

getMimeType in interface Codec

Returns:

null if the MIME type can't be determined by the Codec implementation. Otherwise the MIME type is returned.

getMimeRootCodec

protected Codec getMimeRootCodec(Packet packet)

encode

public ContentType encode(Packet packet,
 OutputStream out)
                   throws IOException

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.

Throws:

IOException - if a OutputStream throws IOException.

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".

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

public void decode(ReadableByteChannel in,
 String contentType,
 Packet packet)

Specified by:

decode in interface Codec

See Also:

• Codec.decode(InputStream, String, Packet)

decode

protected abstract void decode(MimeMultipartParser mpp,
 Packet packet)
                        throws IOException

Parses a Packet from a MimeMultipartParser.

Throws:

IOException

copy

public abstract MimeCodec 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.

writeln

public static void writeln(String s,
 OutputStream out)
                    throws IOException

Throws:

IOException

writeAsAscii

public static void writeAsAscii(String s,
 OutputStream out)
                         throws IOException

Writes a string as ASCII string.

Throws:

IOException

writeln

public static void writeln(OutputStream out)
                    throws IOException

Throws:

IOException