Attachment (JDPWS 0.11.2-SNAPSHOT API)

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, IncomingAttachment.getInputStream(), allows the reading of a stream-based representation of the attachment's bytes, whereas the second one, IncomingAttachment.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 JMEDS 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, MEMORY_ATTACHMENT and OUTPUTSTREAM_ATTACHMENT), some methods like IncomingAttachment.getInputStream(), IncomingAttachment.getBytes() and size() may behave differently. Additionally, other methods like IncomingFileAttachment.save(String), IncomingFileAttachment.move(String) or IncomingFileAttachment.getAbsoluteFilename() may not work at all.

Field Summary

Fields
Modifier and Type	Field and Description
`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

All Methods Instance Methods Abstract Methods
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`	`getContentId()` Return the content ID of this attachment.
`ContentType`	`getContentType()` The content type for this attachment.
`int`	`getType()` Returns this attachment's type.
`long`	`size()` Returns the size of this attachment in bytes.

- Field Detail
  - STREAM_ATTACHMENT
```
static final int STREAM_ATTACHMENT
```
    This attachment will behave like a InputStreamAttachment. Moreover, it will not support the IncomingFileAttachment.save(String), IncomingFileAttachment.move(String) and IncomingFileAttachment.getAbsoluteFilename() 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 IncomingFileAttachment.save(String), IncomingFileAttachment.move(String) and IncomingFileAttachment.getAbsoluteFilename() 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 IncomingFileAttachment.save(String) , IncomingFileAttachment.move(String) and IncomingFileAttachment.getAbsoluteFilename() 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 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.
    
    Returns:
    
    the type of this attachment instance
    
    Throws:
    
    AttachmentException
    
    See Also:
    
    STREAM_ATTACHMENT, FILE_ATTACHMENT, MEMORY_ATTACHMENT, OUTPUTSTREAM_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
  - 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!
  - getContentType
```
ContentType getContentType()
                    throws AttachmentException
```
    The content type for this attachment.
    
    Returns:
    
    the content type
    
    Throws:
    
    AttachmentException
    
    AttachmentException - if attachment processing is not supported within the current runtime or obtaining the attachment failed for any reason
  - canDetermineSize
```
boolean canDetermineSize()
```
    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.
    
    Returns:
    
    true if size can be determined
  - size
```
long size()
   throws AttachmentException
```
    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.
    
    Returns:
    
    the size of this attachment's raw data
    
    Throws:
    
    AttachmentException

Interface Attachment

Field Summary

Method Summary

Field Detail

STREAM_ATTACHMENT

MEMORY_ATTACHMENT

FILE_ATTACHMENT

OUTPUTSTREAM_ATTACHMENT

Method Detail

getType

getContentId

dispose

getContentType

canDetermineSize

size