javax.wireless.messaging
Interface MultipartMessage

All Superinterfaces:

Message

public interface MultipartMessage

extends Message

An interface representing a multipart message. This is a subinterface of Message which contains methods to add and get MessageParts. The interface also allows to specify the subject of the message. The basic methods for manipulating the address portion of the message are inherited from Message. Additional this interface defines methods for adding and removing addresses to/from the "to", "cc" or "bcc" fields. Furthermore it offers methods to get and set special header fields of the message. The contents of the MultipartMessage are assembled during the invocation of the MessageConnection.send() method. The contents of each MessagePart are copied before the send message returns. Changes to the MessagePart contents after send must not appear in the transmitted message.

Since:

WMA 2.0

Method Summary

boolean	addAddress(java.lang.String type, java.lang.String address) Adds an address to the multipart message.
void	addMessagePart(MessagePart part) Attaches a MessagePart to the multipart message
java.lang.String	getAddress() Returns the "from" address associated with this message, e.g. address of the sender.
java.lang.String[]	getAddresses(java.lang.String type) Gets the addresses of the multipart message of the specified type.
java.lang.String	getHeader(java.lang.String headerField) Gets the content of the specific header field of the multipart message.
MessagePart	getMessagePart(java.lang.String contentID) This method returns a MessagePart from the message that matches the content-id passed as a parameter
MessagePart[]	getMessageParts() Returns an array of all MessageParts of this message
java.lang.String	getStartContentId() Returns the contentId of the start MessagePart.
java.lang.String	getSubject() Gets the subject of the multipart message.
boolean	removeAddress(java.lang.String type, java.lang.String address) Removes an address from the multipart message.
void	removeAddresses() Removes all addresses of types "to", "cc", and bcc" from the multipart message.
void	removeAddresses(java.lang.String type) Removes all addresses of the specified type from the multipart message.
boolean	removeMessagePart(MessagePart part) Removes a MessagePart from the multipart message
boolean	removeMessagePartId(java.lang.String contentID) Removes a MessagePart with the specific contentID from the multipart message
boolean	removeMessagePartLocation(java.lang.String contentLocation) Removes MessagePart s with the specific content location from the multipart message.
void	setAddress(java.lang.String addr) Sets the "to" address associated with this message.
void	setHeader(java.lang.String headerField, java.lang.String headerValue) Sets the specific header of the multipart message.
void	setStartContentId(java.lang.String contentId) Sets the Content-ID of the start MessagePart of a multipart related message.
void	setSubject(java.lang.String subject) Sets the Subject of the multipart message.

Methods inherited from interface javax.wireless.messaging.Message

getTimestamp

Method Detail

addMessagePart

public void addMessagePart(MessagePart part)
                    throws SizeExceededException

Attaches a MessagePart to the multipart message

Parameters:

part - MessagePart to add

Throws:

java.lang.IllegalArgumentException - if the Content-ID of the MessagePart conflicts with a Content-ID of an MessagePart already contained in this MultipartMessage. The Content-IDs must be unique within a MultipartMessage.

java.lang.NullPointerException - if the parameter is null

SizeExceededException - if it's not possible to attach the MessagePart.

removeMessagePartId

public boolean removeMessagePartId(java.lang.String contentID)

Removes a MessagePart with the specific contentID from the multipart message

Parameters:

contentID - identifiers which MessagePart must be deleted.

Returns:

true, if it was possible to remove the MessagePart, else false

Throws:

java.lang.NullPointerException - if the parameter is null

removeMessagePart

public boolean removeMessagePart(MessagePart part)

Removes a MessagePart from the multipart message

Parameters:

part - MessagePart to delete

Returns:

true, if it was possible to remove the MessagePart, else false

Throws:

java.lang.NullPointerException - if the parameter is null

removeMessagePartLocation

public boolean removeMessagePartLocation(java.lang.String contentLocation)

Removes MessagePart s with the specific content location from the multipart message. All MessageParts with the specified contentLocation are removed

Parameters:

contentLocation - content location (file name) of the MessagePart

Returns:

true, if it was possible to remove the MessagePart, else false

Throws:

java.lang.NullPointerException - if the parameter is null

getMessagePart

public MessagePart getMessagePart(java.lang.String contentID)

This method returns a MessagePart from the message that matches the content-id passed as a parameter

Parameters:

contentID - the content-id for the MessagePart to be returned

Returns:

MessagePart that matches the provided content-id or null if there is no MessagePart in this message with the provided content-id

Throws:

java.lang.NullPointerException - if the parameter is null

getStartContentId

public java.lang.String getStartContentId()

Returns the contentId of the start MessagePart. The start MessagePart is set in setStartContentId(String)

Returns:

the content-id of the start MessagePart or null if the start MessagePart is not set.

See Also:

setStartContentId(String)

getMessageParts

public MessagePart[] getMessageParts()

Returns an array of all MessageParts of this message

Returns:

array of MessageParts, or null, if no MessageParts are available

setStartContentId

public void setStartContentId(java.lang.String contentId)

Sets the Content-ID of the start MessagePart of a multipart related message. The Content-ID may be set to null. The StartContentId is set for the MessagePart that is used to reference the other MessageParts of the MultipartMessage for presentation or processing purposes.

Parameters:

contentId - as a String

Throws:

java.lang.IllegalArgumentException - if contentId is none of the added MessageParts objects matches the contentId

See Also:

getStartContentId()

getSubject

public java.lang.String getSubject()

Gets the subject of the multipart message.

Returns:

the message subject as a String or null if this value is not present.

getHeader

public java.lang.String getHeader(java.lang.String headerField)

Gets the content of the specific header field of the multipart message.

Parameters:

headerField - the name of the header field as a String

Returns:

the content of the specified header field as a String or null if the specified header field is not present.

Throws:

java.lang.SecurityException - if the access to specified header field is restricted

java.lang.IllegalArgumentException - if headerField is unknown

See Also:

"Appendix D for known headerFields"

setSubject

public void setSubject(java.lang.String subject)

Sets the Subject of the multipart message. This value can be null.

Parameters:

subject - the message subject as a String

See Also:

getSubject()

setHeader

public void setHeader(java.lang.String headerField,
                      java.lang.String headerValue)

Sets the specific header of the multipart message. The header value can be null.

Parameters:

headerField - the name of the header field as a String

headerValue - the value of the header as a String

Throws:

java.lang.IllegalArgumentException - if headerField is unknown, or if headerValue is not correct (depends on headerField!)

java.lang.NullPointerException - if headerField is null

java.lang.SecurityException - if the access to specified header field is restricted

See Also:

getHeader(String), "Appendix D"

addAddress

public boolean addAddress(java.lang.String type,
                          java.lang.String address)

Adds an address to the multipart message.

Parameters:

type - the address type ("to", "cc" or "bcc") as a String. Each message can have none or multiple "to", "cc" and "bcc" addresses. Each address is added separately. The type is not case sensitive. The implementation of MessageConnection.send() makes sure that the "from" address is set correctly.

address - the address as a String

Returns:

true if it was possible to add the address, else false

Throws:

java.lang.IllegalArgumentException - if type is none of "to", "cc", or "bcc" or if address is not valid.

See Also:

setAddress(String address)

removeAddresses

public void removeAddresses()

Removes all addresses of types "to", "cc", and bcc" from the multipart message.

See Also:

setAddress(String), addAddress(String, String)

removeAddresses

public void removeAddresses(java.lang.String type)

Removes all addresses of the specified type from the multipart message.

Parameters:

type - the address type ("to", "cc", or "bcc") as a String.

Throws:

java.lang.NullPointerException - if type is null

java.lang.IllegalArgumentException - if type is none of "to", "cc", or "bcc"

removeAddress

public boolean removeAddress(java.lang.String type,
                             java.lang.String address)

Removes an address from the multipart message.

Parameters:

type - the address type ("to", "cc", or "bcc") as a String.

address - the address as a String

Returns:

true if it was possible to delete the address, else false

Throws:

java.lang.NullPointerException - if type is null

java.lang.IllegalArgumentException - if type is none of "to", "cc", or "bcc"

getAddresses

public java.lang.String[] getAddresses(java.lang.String type)

Gets the addresses of the multipart message of the specified type. (e.g. "to", "cc", "bcc" or "from") as String. The method is not case sensitive.

Returns:

the addresses as a String array or null if the address of the specified type is not present.

getAddress

public java.lang.String getAddress()

Returns the "from" address associated with this message, e.g. address of the sender. If message is a newly created message, e.g. not a received one, then the first "to" address is returned.

Returns null, if the "from" or "to" addresses for the message, dependent on the case, are not set.

Note: This design allows sending responses to a received message easily by reusing the same Message object and just replacing the payload. The address field can normally be kept untouched (unless the used messaging protocol requires some special handling of the address).

Specified by:

getAddress in interface Message

Returns:

the "from" or "to" address of this message, or null if the address that is expected as a result of the method is not set

See Also:

setAddress(String)

setAddress

public void setAddress(java.lang.String addr)

Sets the "to" address associated with this message. It works the same way as addAddress ("to", addr) The address may be set to null.

Specified by:

setAddress in interface Message

Parameters:

addr - address for the message

Throws:

java.lang.IllegalArgumentException - if address is not valid.

See Also:

getAddress(), addAddress(String, String)