org.ws4d.java.attachment
Class AttachmentStub

java.lang.Object
  org.ws4d.java.attachment.AttachmentStub

All Implemented Interfaces:

Attachment, IncomingAttachment, IncomingFileAttachment

public class AttachmentStub
extends java.lang.Object
implements IncomingFileAttachment

Field Summary

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

FILE_ATTACHMENT, MEMORY_ATTACHMENT, OUTPUTSTREAM_ATTACHMENT, STREAM_ATTACHMENT

Constructor Summary

AttachmentStub(java.lang.String contentId)

Method Summary

void	dispose() Disposes of the attachment and - if possible - frees any resources such as volatile and/or non volatile memory it uses.
ContextID	getAttachmentScope()
byte[]	getBytes() Returns the raw data from this attachment as array of bytes.
java.lang.String	getContentId() Return the content ID of this attachment.
InternetMediaType	getContentType() The content type (MIME) for this attachment.
java.lang.String	getFilePath() Returns the path to the file encapsulated by this attachment.
java.io.InputStream	getInputStream() Returns the input stream which contains the data.
java.lang.String	getTransferEncoding() The encoding for this attachment.
int	getType() Returns this attachment's type.
boolean	isAvailable() Returns true if this attachment is ready to be processed.
boolean	isLocal() Returns true, if this attachment was created locally.
boolean	move(java.lang.String newFilePath) This method moves the file containing the attachment's raw data to the given target file path (e.g.
void	save(java.lang.String targetFilePath) Copies the attachment's raw data to the target file path (e.g.
void	serialize(java.io.OutputStream out)
void	setAttachmentScope(ContextID attachmentScope)
long	size() Returns the size of the attachment in bytes.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AttachmentStub

public AttachmentStub(java.lang.String contentId)

Parameters:

contentId -

Method Detail

getAttachmentScope

public ContextID getAttachmentScope()

setAttachmentScope

public void setAttachmentScope(ContextID attachmentScope)

dispose

public void dispose()

Description copied from interface: Attachment

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!

Specified by:

dispose in interface Attachment

getBytes

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

Description copied from interface: IncomingAttachment

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().

Specified by:

getBytes in interface IncomingAttachment

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(), IncomingAttachment.getInputStream()

getContentId

public java.lang.String getContentId()

Description copied from interface: Attachment

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.

Specified by:

getContentId in interface Attachment

Returns:

this attachment's content ID

getContentType

public InternetMediaType getContentType()
                                 throws AttachmentException

Description copied from interface: Attachment

The content type (MIME) for this attachment.

Specified by:

getContentType in interface 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

getInputStream

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

Description copied from interface: IncomingAttachment

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().

Specified by:

getInputStream in interface IncomingAttachment

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(), IncomingAttachment.size(), IncomingAttachment.getBytes()

getTransferEncoding

public java.lang.String getTransferEncoding()
                                     throws AttachmentException

Description copied from interface: Attachment

The encoding for this attachment.

Specified by:

getTransferEncoding in interface Attachment

Returns:

the encoding

Throws:

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

getType

public int getType()
            throws AttachmentException

Description copied from interface: Attachment

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.

Specified by:

getType in interface Attachment

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:

Attachment.STREAM_ATTACHMENT, Attachment.FILE_ATTACHMENT, Attachment.MEMORY_ATTACHMENT

isAvailable

public boolean isAvailable()

Description copied from interface: IncomingAttachment

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

Specified by:

isAvailable in interface IncomingAttachment

Returns:

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

size

public long size()
          throws AttachmentException

Description copied from interface: IncomingAttachment

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()).

Specified by:

size in interface IncomingAttachment

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(), IncomingAttachment.getInputStream()

isLocal

public boolean isLocal()

Description copied from interface: IncomingFileAttachment

Returns true, if this attachment was created locally. This is synonymous to the sender/originator of this attachment instance residing within the same Java virtual machine as its receiver.

This method is especially important for attachments of type Attachment.FILE_ATTACHMENT, as - if it returns true - this denotes that the file the attachment points to is the original one. That is, when attempting to IncomingFileAttachment.move(String) a file attachment, this allows to distinguish whether the original file would be moved to a new location or whether simply the attachment file will be moved out of the local attachment store (used for caching incoming attachments) to a place outside of it.

Specified by:

isLocal in interface IncomingFileAttachment

Returns:

true only if this attachment was originally created locally (within the same JVM)

getFilePath

public java.lang.String getFilePath()
                             throws AttachmentException

Description copied from interface: IncomingFileAttachment

Returns the path to the file encapsulated by this attachment. This method is only legal for attachments of type Attachment.FILE_ATTACHMENT. For any other types, it will throw an AttachmentException.

Specified by:

getFilePath in interface IncomingFileAttachment

Returns:

the path to the file containing the attachments raw data

Throws:

AttachmentException

save

public void save(java.lang.String targetFilePath)
          throws AttachmentException,
                 java.io.IOException

Description copied from interface: IncomingFileAttachment

Copies the attachment's raw data to the target file path (e.g. "C:/folder/file.gif"). This method can only be used for attachments of type Attachment.FILE_ATTACHMENT. In any other cases it will throw an AttachmentException.

Specified by:

save in interface IncomingFileAttachment

Parameters:

targetFilePath - the new path within the local file system to store the file to

Throws:

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

java.io.IOException - in case writing to the local file system failed for any reason

move

public boolean move(java.lang.String newFilePath)
             throws AttachmentException

Description copied from interface: IncomingFileAttachment

This method moves the file containing the attachment's raw data to the given target file path (e.g. "C:/folder/file.gif"). It can only be used for attachments of type Attachment.FILE_ATTACHMENT. In any other cases it will throw an AttachmentException.

Specified by:

move in interface IncomingFileAttachment

Parameters:

newFilePath - the new path within the local file system to move the file to

Returns:

true, if the file was moved/renamed successfully, false otherwise

Throws:

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

serialize

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

Specified by:

serialize in interface Attachment

Throws:

java.io.IOException

AttachmentException