org.ws4d.java.attachment
Interface Attachment

All Known Subinterfaces:

IncomingAttachment, IncomingFileAttachment, OutgoingAttachment, OutgoingOutputStreamAttachment

All Known Implementing Classes:

AbstractAttachment, AttachmentStub

public interface Attachment

Attachment container. Provides access to metadata (content ID, content type, transfer encoding) and raw data of an attachment.

There are two different ways of obtaining raw data from an Attachment. The first one, #getInputStream(), allows the reading of a stream-based representation of the attachment's bytes, whereas the second one, #getBytes(), returns them within a byte array. While in some cases being faster (depending on the actual Attachment implementation), the later approach is subject to certain limitations resulting from the finite amount of memory available within the current runtime.

Most methods of this interface are indicated to throw AttachmentExceptions if obtaining the requested attachment data or property failed for any reason. This could be the result e.g. of a network failure while reading the attachment or an unexpected or erroneous attachment format, or it could mean that attachment support is not available within the current DPWS framework configuration.

The actual type of attachment can be queried by means of method getType(). Depending on the value returned (see STREAM_ATTACHMENT, FILE_ATTACHMENT and MEMORY_ATTACHMENT), some methods like #getInputStream(), #getBytes() and #size() may behave differently. Additionally, other methods like #save(String), #move(String) or #getFilePath() may not work at all.

Field Summary

static int	FILE_ATTACHMENT This attachment will behave like a FileAttachment.
static int	MEMORY_ATTACHMENT This attachment will behave like a MemoryAttachment.
static int	OUTPUTSTREAM_ATTACHMENT Mostly a InputStreamAttachment.
static int	STREAM_ATTACHMENT This attachment will behave like a InputStreamAttachment.

Method Summary

void	dispose() Disposes of the attachment and - if possible - frees any resources such as volatile and/or non volatile memory it uses.
java.lang.String	getContentId() Return the content ID of this attachment.
InternetMediaType	getContentType() The content type (MIME) for this attachment.
java.lang.String	getTransferEncoding() The encoding for this attachment.
int	getType() Returns this attachment's type.
void	serialize(java.io.OutputStream out)

Field Detail

STREAM_ATTACHMENT

static final int STREAM_ATTACHMENT

This attachment will behave like a InputStreamAttachment. Moreover, it will not support the #save(String), #move(String) and #getFilePath() operations. Note that checking that an attachment is of this type is not sufficient in order to safely cast it to a InputStreamAttachment. Use an instanceof expression instead.

See Also:

Constant Field Values

MEMORY_ATTACHMENT

static final int MEMORY_ATTACHMENT

This attachment will behave like a MemoryAttachment. Moreover, it will not support the #save(String), #move(String) and #getFilePath() operations. Note that checking that an attachment is of this type is not sufficient to safely cast it to a MemoryAttachment. Use an instanceof expression instead.

See Also:

Constant Field Values

FILE_ATTACHMENT

static final int FILE_ATTACHMENT

This attachment will behave like a FileAttachment. Moreover, it will support the #save(String), #move(String) and #getFilePath() operations. Note that checking that an attachment is of this type is not sufficient to safely cast it to a FileAttachment. Use an instanceof expression instead.

See Also:

Constant Field Values

OUTPUTSTREAM_ATTACHMENT

static final int OUTPUTSTREAM_ATTACHMENT

Mostly a InputStreamAttachment. The difference between the default InputStreamAttachment is, that this one does not accept a input stream but provides an output stream.

See Also:

Constant Field Values

Method Detail

getType

int getType()
            throws AttachmentException

Returns this attachment's type.

The value returned distinguishes between different implementations and thereby different storage models for the attachment's raw data, such as in-memory, on file system or as (opaque) input stream. It further determines which ways of obtaining the raw data are suitable/possible for this instance (e.g. by means of #getBytes() or #getInputStream()). Also, usage/availability of some operations like #save(String), #move(String) and #getFilePath() depends on the type of attachment. On some types, these operations will not be supported at all and will always throw an AttachmentException.

Returns:

the type of this attachment instance

Throws:

AttachmentException - if attachment processing is not supported within the current runtime or obtaining the attachment failed for any reason

See Also:

STREAM_ATTACHMENT, FILE_ATTACHMENT, MEMORY_ATTACHMENT

getContentId

java.lang.String getContentId()

Return the content ID of this attachment. The content ID is used to distinguish the attachment within a MIME package and to enable linking to it from within ParameterValue instances.

Returns:

this attachment's content ID

getTransferEncoding

java.lang.String getTransferEncoding()
                                     throws AttachmentException

The encoding for this attachment.

Returns:

the encoding

Throws:

AttachmentException - if attachment processing is not supported within the current runtime or obtaining the attachment failed for any reason

getContentType

InternetMediaType getContentType()
                                 throws AttachmentException

The content type (MIME) for this attachment.

Returns:

the content type

Throws:

AttachmentException - if attachment processing is not supported within the current runtime or obtaining the attachment failed for any reason

dispose

void dispose()

Disposes of the attachment and - if possible - frees any resources such as volatile and/or non volatile memory it uses. After calling this method, access to this attachment's metadata and raw data will no longer be possible!

serialize

void serialize(java.io.OutputStream out)
               throws java.io.IOException,
                      AttachmentException

Throws:

java.io.IOException

AttachmentException