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.interfaces.Attachment

FILE_ATTACHMENT, MEMORY_ATTACHMENT, OUTPUTSTREAM_ATTACHMENT, STREAM_ATTACHMENT

Constructor Summary

Constructors

Constructor and Description
AttachmentStub(java.lang.String contentId) Constructor for an AttachmentStub with given contentId.

Method Summary

Modifier and Type	Method and Description
boolean	canDetermineSize() Use this method to check if this attachment is able to determine its size.
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	getAbsoluteFilename() Returns the path to the file encapsulated by this attachment.
byte[]	getBytes() Returns the raw data from this attachment as array of bytes.
java.lang.String	getContentId() Return the content ID of this attachment.
ContentType	getContentType() The content type for this attachment.
java.io.InputStream	getInputStream() Returns the input stream which contains the data.
long	getTimeToWait()
int	getType() Returns this attachment's type.
java.lang.String	getUniqueId()
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	setTimeToWait(long timeToWait)
void	setUniqueId(java.lang.String connectionId)
long	size() Returns the size of this attachment in bytes.

Methods inherited from class java.lang.Object

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

Constructor Detail

AttachmentStub

public AttachmentStub(java.lang.String contentId)

Constructor for an AttachmentStub with given contentId.

Parameters:

contentId -

Method Detail

getUniqueId

public java.lang.String getUniqueId()

setUniqueId

public void setUniqueId(java.lang.String connectionId)

getTimeToWait

public long getTimeToWait()

setTimeToWait

public void setTimeToWait(long timeToWait)

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

getContentType

public ContentType getContentType()
                           throws AttachmentException

Description copied from interface: Attachment

The content type for this attachment.

Specified by:

getContentType in interface Attachment

Returns:

the content type

Throws:

AttachmentException

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

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

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 IncomingAttachment.getBytes() or IncomingAttachment.getInputStream()). Also, usage/availability of some operations like IncomingFileAttachment.save(String), IncomingFileAttachment.move(String) and IncomingFileAttachment.getAbsoluteFilename() 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

See Also:

Attachment.STREAM_ATTACHMENT, Attachment.FILE_ATTACHMENT, Attachment.MEMORY_ATTACHMENT, Attachment.OUTPUTSTREAM_ATTACHMENT

isAvailable

public boolean isAvailable()

Description copied from interface: IncomingAttachment

Returns true if this attachment is ready to be processed.

Because the JMEDS 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 ParameterValue.get(String). 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)

canDetermineSize

public boolean canDetermineSize()

Description copied from interface: Attachment

Use this method to check if this attachment is able to determine its size.

Some types of attachment (e.g. InputStreamAttachment) may not be aware of their actual size; in such cases, this method will return false.

Specified by:

canDetermineSize in interface Attachment

Returns:

true if size can be determined

size

public long size()
          throws AttachmentException

Description copied from interface: Attachment

Returns the size of this attachment in bytes.

Some types of attachment (e.g. InputStreamAttachment) may not be aware of their actual size; in such cases, this method will return -1.

Specified by:

size in interface Attachment

Returns:

the size of this attachment's raw data

Throws:

AttachmentException

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)

getAbsoluteFilename

public java.lang.String getAbsoluteFilename()
                                     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:

getAbsoluteFilename 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