org.ws4d.java.attachment
Interface IncomingAttachment

All Superinterfaces:

Attachment

All Known Subinterfaces:

IncomingFileAttachment

All Known Implementing Classes:

AttachmentStub

public interface IncomingAttachment
extends Attachment

Field Summary

Fields inherited from interface org.ws4d.java.attachment.Attachment

FILE_ATTACHMENT, MEMORY_ATTACHMENT, OUTPUTSTREAM_ATTACHMENT, STREAM_ATTACHMENT

Method Summary

byte[]	getBytes() Returns the raw data from this attachment as array of bytes.
java.io.InputStream	getInputStream() Returns the input stream which contains the data.
boolean	isAvailable() Returns true if this attachment is ready to be processed.
long	size() Returns the size of the attachment in bytes.

Methods inherited from interface org.ws4d.java.attachment.Attachment

dispose, getContentId, getContentType, getTransferEncoding, getType, serialize

Method Detail

getInputStream

java.io.InputStream getInputStream()
                                   throws AttachmentException,
                                          java.io.IOException

Returns the input stream which contains the data.

Depending on the actual attachment implementation, this method may either always return the same java.io.InputStream instance, or it could create a new one on each call. In the first case, it is important to note that reading the attachment data might be possible only once, as the returned stream is not guaranteed to support resetting (see Attachment.getType().

Returns:

an input stream to this attachment's raw data

Throws:

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

java.io.IOException - if reading raw attachment data failed

See Also:

Attachment.getType(), size(), getBytes()

isAvailable

boolean isAvailable()

Returns true if this attachment is ready to be processed.

Because the DPWS framework handles attachments asynchronously, it is possible (and will most likely occur frequently) for an attachement's raw data to still be being transmitted over the network while a caller's business logic (e.g. the Operation.invoke(ParameterValue) method) gets called providing access to the attachment by means of its parameters. Using methods other than Attachment.getContentId() or isAvailable() on this attachment would block the caller until the entire attachment is read out. Thus, this method allows to check whether further examination of this attachment would block it or not.

Returns:

true, if this attachment is already available, false if it is still not received (entirely)

size

long size()
          throws AttachmentException

Returns the size of the attachment in bytes.

Some types of attachment (e.g. InputStreamAttachment) may not be aware of their actual size; in such cases, this method will either return zero or a potentially inaccurate estimate (as provided by java.io.InputStream.available()).

Returns:

the size of this attachment's raw data

Throws:

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

See Also:

Attachment.getType(), getInputStream()

getBytes

byte[] getBytes()
                throws AttachmentException,
                       java.io.IOException

Returns the raw data from this attachment as array of bytes.

WARNING: The result can potentially use a large amount of memory. Furthermore, some environments or some types of attachments (see e.g. InputStreamAttachment or FileAttachment) may not support representing the attachment's raw data as a byte array. In these cases, a call to this method will cause an AttachmentException to get thrown (see Attachment.getType().

Returns:

the attachment data as a byte array

Throws:

AttachmentException - if attachment processing is not supported within the current runtime or obtaining the attachment failed for any reason or in particular, when this attachment type doesn't support byte array access to its raw data

java.io.IOException - if reading raw attachment data failed

See Also:

Attachment.getType(), getInputStream()