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. This interface defines additional methods for adding and removing addresses to/from the "to", "cc" and "bcc" address lists. 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(Message) 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.

This interface is defined in JSR 205: Wireless Messaging API 2.0, which extends and enhances JSR 120: Wireless Messaging API

Since:

BlackBerry API 4.3.0, WMA 2.0

Method Summary
boolean	addAddress(String type, String address) Adds an address to the multipart message.
void	addMessagePart(MessagePart part) Attaches a MessagePart to the multipart message.
String	getAddress() Returns the "from" address associated with this message.
String[]	getAddresses(String type) Gets the addresses of the multipart message of the specified type.
String	getHeader(String headerField) Gets the content of the specific header field of the multipart message.
MessagePart	getMessagePart(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 MessagePart objects of this message.
String	getStartContentId() Returns the content ID of the start MessagePart.
String	getSubject() Gets the subject of the multipart message.
boolean	removeAddress(String type, 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(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(String contentID) Removes a MessagePart with the specific content ID from the multipart message.
boolean	removeMessagePartLocation(String contentLocation) Removes MessageParts with the specific content location from the multipart message.
void	setAddress(String addr) Sets the "to" address associated with this message.
void	setHeader(String headerField, String headerValue) Sets the specific header of the multipart message.
void	setStartContentId(String contentId) Sets the Content-ID of the start MessagePart of a multipart related message.
void	setSubject(String subject) Sets the Subject of the multipart message.

Methods inherited from interface javax.wireless.messaging.Message

getTimestamp

Method Detail

addAddress

boolean addAddress(String type,
                   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" or "bcc" addresses. Each address is added separately. The type is not case sensitive. The implementation of MessageConnection.send(Message) 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:

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

See Also:

MultipartMessage.setAddress(String), MultipartMessage.getAddresses(String), MultipartMessage.removeAddresses(), MultipartMessage.removeAddress(String, String), MultipartMessage.removeAddresses(String)

Since:

BlackBerry API 4.3.0

addMessagePart

void addMessagePart(MessagePart part)
                    throws SizeExceededException

Attaches a MessagePart to the multipart message.

Parameters:

part - MessagePart to add.

Throws:

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

NullPointerException - if the parameter is null.

SizeExceededException - if it is not possible to attach the MessagePart.

See Also:

MultipartMessage.getMessageParts(), MultipartMessage.getMessagePart(String), MultipartMessage.removeMessagePart(MessagePart), MultipartMessage.removeMessagePartId(String), MultipartMessage.removeMessagePartLocation(String)

Since:

BlackBerry API 4.3.0

getAddress

String getAddress()

Returns the "from" address associated with this message. That is, the 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:

MultipartMessage.setAddress(String)

Since:

BlackBerry API 4.3.0

getAddresses

String[] getAddresses(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.

Parameters:

type - the address type ("to", "cc", "bcc", or "from") as a String. The type is not case sensitive.

Returns:

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

See Also:

MultipartMessage.addAddress(String, String)

Since:

BlackBerry API 4.3.0

getHeader

String getHeader(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:

SecurityException - if the access to specified header field is restricted; See Appendix D of the WMA 2.0 specification for accessible header fields.

IllegalArgumentException - if headerField is unknown.

See Also:

MultipartMessage.setHeader(String, String)

Since:

BlackBerry API 4.3.0

getMessagePart

MessagePart getMessagePart(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:

NullPointerException - if the parameter is null.

See Also:

MultipartMessage.getMessageParts(), MultipartMessage.addMessagePart(MessagePart)

Since:

BlackBerry API 4.3.0

getMessageParts

MessagePart[] getMessageParts()

Returns an array of all MessagePart objects of this message.

Returns:

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

See Also:

MultipartMessage.getMessagePart(String), MultipartMessage.addMessagePart(MessagePart)

Since:

BlackBerry API 4.3.0

getStartContentId

String getStartContentId()

Returns the content ID 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:

MultipartMessage.setStartContentId(String)

Since:

BlackBerry API 4.3.0

getSubject

String getSubject()

Gets the subject of the multipart message.

Returns:

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

See Also:

MultipartMessage.setSubject(String)

Since:

BlackBerry API 4.3.0

removeAddress

boolean removeAddress(String type,
                      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 remove the address, else false.

Throws:

NullPointerException - if type is null.

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

See Also:

MultipartMessage.addAddress(String, String), MultipartMessage.setAddress(String), MultipartMessage.removeAddresses(), MultipartMessage.removeAddresses(String)

Since:

BlackBerry API 4.3.0

removeAddresses

void removeAddresses()

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

See Also:

MultipartMessage.addAddress(String, String), MultipartMessage.setAddress(String), MultipartMessage.removeAddresses(String), MultipartMessage.removeAddress(String, String)

Since:

BlackBerry API 4.3.0

removeAddresses

void removeAddresses(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:

NullPointerException - if type is null

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

See Also:

MultipartMessage.addAddress(String, String), MultipartMessage.setAddress(String), MultipartMessage.removeAddresses(), MultipartMessage.removeAddress(String, String)

Since:

BlackBerry API 4.3.0

removeMessagePart

boolean removeMessagePart(MessagePart part)

Removes a MessagePart from the multipart message.

Parameters:

part - MessagePart to remove.

Returns:

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

Throws:

NullPointerException - if the parameter is null.

See Also:

MultipartMessage.addMessagePart(MessagePart), MultipartMessage.removeMessagePartId(String), MultipartMessage.removeMessagePartLocation(String)

Since:

BlackBerry API 4.3.0

removeMessagePartId

boolean removeMessagePartId(String contentID)

Removes a MessagePart with the specific content ID from the multipart message.

Parameters:

contentID - identifiers which MessagePart must be removed.

Returns:

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

Throws:

NullPointerException - if the parameter is null.

See Also:

MultipartMessage.addMessagePart(MessagePart), MultipartMessage.removeMessagePart(MessagePart), MultipartMessage.removeMessagePartLocation(String)

Since:

BlackBerry API 4.3.0

removeMessagePartLocation

boolean removeMessagePartLocation(String contentLocation)

Removes MessageParts 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 MessageParts to remove.

Returns:

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

Throws:

NullPointerException - if the parameter is null.

See Also:

MultipartMessage.addMessagePart(MessagePart), MultipartMessage.removeMessagePart(MessagePart), MultipartMessage.removeMessagePartId(String)

Since:

BlackBerry API 4.3.0

setAddress

void setAddress(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:

IllegalArgumentException - if address is not valid.

See Also:

MultipartMessage.getAddress(), MultipartMessage.addAddress(String, String)

Since:

BlackBerry API 4.3.0

setHeader

void setHeader(String headerField,
               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:

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

NullPointerException - if headerField is null.

SecurityException - if the access to specified header field is restricted; See Appendix D of the WMA 2.0 specification for accessible header fields.

See Also:

MultipartMessage.getHeader(String)

Since:

BlackBerry API 4.3.0

setStartContentId

void setStartContentId(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 - the start Content ID to set as a String.

Throws:

IllegalArgumentException - if contentId is none of the added MessagePart objects matches the content ID.

See Also:

MultipartMessage.getStartContentId()

Since:

BlackBerry API 4.3.0

setSubject

void setSubject(String subject)

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

Parameters:

subject - the message subject as a String.

See Also:

MultipartMessage.getSubject()

Since:

BlackBerry API 4.3.0