javax.sip.message
Interface Message

All Superinterfaces:

java.lang.Cloneable, java.io.Serializable

All Known Subinterfaces:

Request, Response

public interface Message
extends java.lang.Cloneable, java.io.Serializable

A SIP message is either a request from a client to a server, or a response from a server to a client. Both Request and Response messages use the basic format of RFC 2822, even though the syntax differs in character set and syntax specifics. (SIP allows header fields that would not be valid RFC 2822 header fields, for example.) Both types of messages consist of a method name, address and protocol version, one or more header fields which describe the routing of the message, and an optional message-body. The message-body contains a session description in a format such as Session Description Protocol see JSR 141.

This interface contains common elements of both Request and Response such as:

• Generic accessor functions to headers.
• Convenience accessor to the expiration value of the message.
• Convenience header accessor methods for the body content type, language, disposition and length.
• Accessor methods to the body content itself.

Although the SIP Protocol allows headers of a given kind to be interspaced with headers of different kinds, an implementation of this specification is required to organize headers so that headers that can appear multiple times in a SIP Message (such as the Via header) are grouped together and can be retrieved collectively and iterated over. Although an implementation may use short forms internally, the specification refers to all headers by their long form names.

Author:

BEA Systems, NIST

See Also:

Request, Response, Header

Method Summary

void	addFirst(Header header) Adds the new Header to the head of the existing list of Headers contained in this Message.
void	addHeader(Header header) Adds the new Header to the existing list of Headers contained in this Message.
void	addLast(Header header) Adds the new Header to the end of existing list of Headers contained in this Message.
java.lang.Object	clone() Creates and returns a deep copy of the Message.
boolean	equals(java.lang.Object object) Compare this SIP Message for equality with another.
java.lang.Object	getContent() Gets the body content of the Message as an Object.
ContentDispositionHeader	getContentDisposition() Gets the ContentDispositionHeader of this Message.
ContentEncodingHeader	getContentEncoding() Gets the ContentEncodingHeader of this Message.
ContentLanguageHeader	getContentLanguage() Gets the ContentLanguageHeader of this Message.
ContentLengthHeader	getContentLength() Gets the ContentLengthHeader of the body content of this Message.
ExpiresHeader	getExpires() Gets the ExpiresHeader of this Message.
Header	getHeader(java.lang.String headerName) Gets the Header of the specified name in this Message.
java.util.ListIterator	getHeaderNames() Gets a ListIterator over the set of all all the header names in this Message.
java.util.ListIterator	getHeaders(java.lang.String headerName) Gets a ListIterator over all the Headers of the newly specified name in this Message.
byte[]	getRawContent() Gets the body content of the Message as a byte array.
java.lang.String	getSIPVersion() Gets the protocol version of SIP being used by this Message.
java.util.ListIterator	getUnrecognizedHeaders() Returns a ListIterator over all the UnrecognizedHeaders in this Message.
int	hashCode() Gets a integer hashcode representation of the Header.
void	removeContent() Removes the body content from this Message and all associated entity headers, if a body exists, this method returns sliently if no body exists.
void	removeFirst(java.lang.String headerName) Removes the first header from a list of headers.
void	removeHeader(java.lang.String headerName) Removes the Header of the supplied name from the list of headers in this Message.
void	removeLast(java.lang.String headerName) Removes the last header from a list of headers.
void	setContent(java.lang.Object content, ContentTypeHeader contentTypeHeader) Sets the body of this Message, with the ContentType defined by the new ContentTypeHeader object and the string value of the content.
void	setContentDisposition(ContentDispositionHeader contentDisposition) Sets the ContentDispositionHeader of this Message.
void	setContentEncoding(ContentEncodingHeader contentEncoding) Sets the ContentEncodingHeader of this Message.
void	setContentLanguage(ContentLanguageHeader contentLanguage) Sets the ContentLanguageHeader of this Message.
void	setContentLength(ContentLengthHeader contentLength) Set the ContentLengthHeader of this Message.
void	setExpires(ExpiresHeader expires) Sets the ExpiresHeader of this Message.
void	setHeader(Header header) Sets the new Header to replace existings Header of that type in the message.
void	setSIPVersion(java.lang.String version) Sets the protocol version of SIP being used by this Message.
java.lang.String	toString() Gets string representation of Message

Method Detail

addHeader

void addHeader(Header header)

Adds the new Header to the existing list of Headers contained in this Message. The Header is added to the end of the List and will appear in that order in the SIP Message.

Required Headers that are singletons should not be added to the message as they already exist in the message and therefore should be changed using the setHeader(Header) method.

This method should be used to support the special case of adding required ViaHeaders to a message. When adding a ViaHeader using this method the implementation will add the ViaHeader to the top of the ViaHeader list, and not the end like all other Headers.

Parameters:

header - the new Header to be added to the existing Headers List.

addLast

void addLast(Header header)
             throws SipException,
                    java.lang.NullPointerException

Adds the new Header to the end of existing list of Headers contained in this Message. The Header is added to the end of the List and will appear in that order in the SIP Message.

Required Headers that are singletons should not be added to the message as they already exist in the message and therefore should be changed using the setHeader(Header) method. This does the same thing as addHeader in all cases including the Via header. Add a header explicitly to the end of a list of headers.

Parameters:

header - -- the new Header to be added to the end of the existing list of headers

Throws:

java.lang.NullPointerException - -- if the argument is null.

SipException - -- if the header is a singleton and an instance of the header already exists.

Since:

v1.2

addFirst

void addFirst(Header header)
              throws SipException,
                     java.lang.NullPointerException

Adds the new Header to the head of the existing list of Headers contained in this Message. The Header is added to the head of the List and will appear in that order in the SIP Message.

Required Headers that are singletons should not be added to the message as they already exist in the message and therefore should be changed using the setHeader(Header) method.

Parameters:

header - the new Header to be added to the existing Headers List.

Throws:

SipException - -- if the header to be added is a singleton and an instance of the header already exists.

java.lang.NullPointerException - -- if the argument is null.

Since:

v1.2

removeFirst

void removeFirst(java.lang.String headerName)
                 throws java.lang.NullPointerException

Removes the first header from a list of headers. If there's only one header of this kind, then it is removed from the message.

Parameters:

headerName - the name of the header to be removed.

Throws:

java.lang.NullPointerException - -- if the arg is null

Since:

v1.2

removeLast

void removeLast(java.lang.String headerName)
                throws java.lang.NullPointerException

Removes the last header from a list of headers. If there's only one header of this kind, then it is removed from the message.

Parameters:

headerName - the name of the header to be removed.

Throws:

java.lang.NullPointerException

Since:

v1.2

removeHeader

void removeHeader(java.lang.String headerName)

Removes the Header of the supplied name from the list of headers in this Message. If multiple headers exist then they are all removed from the header list. If no headers exist then this method returns silently. This method should not be used to remove required Headers, required Headers should be replaced using the setHeader(Header).

Parameters:

headerName - the new string value name of the Header to be removed.

getHeaderNames

java.util.ListIterator getHeaderNames()

Gets a ListIterator over the set of all all the header names in this Message. Note that the order of the Header Names in the ListIterator is same as the order in which they appear in the SIP Message.

Returns:

the ListIterator over the set of all the Header Names in the Message.

getHeaders

java.util.ListIterator getHeaders(java.lang.String headerName)

Gets a ListIterator over all the Headers of the newly specified name in this Message. Note that order of the Headers in ListIterator is the same as the order in which they appear in the SIP Message.

Parameters:

headerName - the new string name of Header types requested.

Returns:

the ListIterator over all the Headers of the specified name in the Message, this method returns an empty ListIterator if no Headers exist of this header type.

getHeader

Header getHeader(java.lang.String headerName)

Gets the Header of the specified name in this Message. If multiple Headers of this header name exist in the message, the first header in the message is returned.

Parameters:

headerName - the new string name of Header type requested.

Returns:

the Header of the specified name in the Message, this method returns null if the Header does not exist.

getUnrecognizedHeaders

java.util.ListIterator getUnrecognizedHeaders()

Returns a ListIterator over all the UnrecognizedHeaders in this Message. Note the order of the UnrecognizedHeaders in the ListIterator is the same as order in which they appeared in the SIP Message. UnrecognizedHeaders are headers that the underlying implementation does not recognize. If the message is missing a required header (From, To, Call-ID, CSeq, Via) the entire message willl be dropped by the underlying implementation and the header will not be included in the list. Headers that are part of the supported set of headers but are not properly formatted will be included in this list. Note that Headers that are not part of the supported set of headers are retrieved as Extension Headers. These must have a name:value format else they will be rejected by the underling implementation and included in this list. A Proxy should not delete UnrecognizedHeaders and should add these Headers to the end of the header list of the Message that is being forwarded. A User Agent may display these unrecognized headers to the user.

Returns:

the ListIterator over all the UnrecognizedHeaders in the Message represented as Strings, this method returns an empty ListIterator if no UnrecognizedHeaders exist.

setHeader

void setHeader(Header header)

Sets the new Header to replace existings Header of that type in the message. If the SIP message contains more than one Header of the new Header type it should replace the first occurance of this Header and removes all other Headers of this type. If no Header of this type exists this header is added to the end of the SIP Message. This method should be used to change required Headers and overwrite optional Headers.

Parameters:

header - the new Header to replace any existing Headers of that type.

setContentLength

void setContentLength(ContentLengthHeader contentLength)

Set the ContentLengthHeader of this Message. The actual content length for the outgoing message will be computed from the content assigned. If the content is speficied as an object it will be converted to a String before the message is sent out and the content length computed from the length of the string. If the message content is specified in bytes, the length of the byte array specified will be used to determine the content length header, that is in both cases, the length of the content overrides any value specified in the content-length header.

Parameters:

contentLength - the new ContentLengthHeader object containing the content length value of this Message.

getContentLength

ContentLengthHeader getContentLength()

Gets the ContentLengthHeader of the body content of this Message. This is the same as this.getHeader(Content-Length);

Returns:

the ContentLengthHeader of the message body.

setContentLanguage

void setContentLanguage(ContentLanguageHeader contentLanguage)

Sets the ContentLanguageHeader of this Message. This overrides the ContentLanguageHeader set using the setHeaders method. If no ContentLanguageHeader exists in this message this ContentLanguageHeader is added to the end of the Header List.

Parameters:

contentLanguage - the new ContentLanguageHeader object containing the content language value of this Message.

getContentLanguage

ContentLanguageHeader getContentLanguage()

Gets the ContentLanguageHeader of this Message. This is the same as this.getHeader(Content-Langauge);

Returns:

the ContentLanguageHeader of the message body.

setContentEncoding

void setContentEncoding(ContentEncodingHeader contentEncoding)

Sets the ContentEncodingHeader of this Message. This overrides the ContentEncodingHeader set using the setHeaders method. If no ContentEncodingHeader exists in this message this ContentEncodingHeader is added to the end of the Header List.

Parameters:

contentEncoding - the new ContentEncodingHeader object containing the content encoding values of this Message.

getContentEncoding

ContentEncodingHeader getContentEncoding()

Gets the ContentEncodingHeader of this Message. This is the same as this.getHeader(Content-Encoding);

Returns:

the ContentEncodingHeader of the message body.

setContentDisposition

void setContentDisposition(ContentDispositionHeader contentDisposition)

Sets the ContentDispositionHeader of this Message. This overrides the ContentDispositionHeader set using the setHeaders method. If no ContentDispositionHeader exists in this message this ContentDispositionHeader is added to the end of the Header List.

Parameters:

contentDisposition - the new ContentDispositionHeader object containing the content disposition value of this Message.

getContentDisposition

ContentDispositionHeader getContentDisposition()

Gets the ContentDispositionHeader of this Message. This is the same as this.getHeader(Content-Disposition);

Returns:

the ContentDispositionHeader of the message body.

setContent

void setContent(java.lang.Object content,
                ContentTypeHeader contentTypeHeader)
                throws java.text.ParseException

Sets the body of this Message, with the ContentType defined by the new ContentTypeHeader object and the string value of the content.

Parameters:

content - the new Object value of the content of the Message.

contentTypeHeader - the new ContentTypeHeader object that defines the content type value.

Throws:

java.text.ParseException - which signals that an error has been reached unexpectedly while parsing the body.

getRawContent

byte[] getRawContent()

Gets the body content of the Message as a byte array.

Returns:

the body content of the Message as a byte array, this method returns null if a body does not exist.

getContent

java.lang.Object getContent()

Gets the body content of the Message as an Object.

Returns:

the body content of the Message as an Object, this method returns null if a body does not exist.

removeContent

void removeContent()

Removes the body content from this Message and all associated entity headers, if a body exists, this method returns sliently if no body exists.

setExpires

void setExpires(ExpiresHeader expires)

Sets the ExpiresHeader of this Message. This overrides the ExpiresHeader set using the setHeaders method. If no ExpiresHeader exists in this message this ExpiresHeader is added to the end of the Header List.

Parameters:

expires - the new ExpiresHeader object containing the expires values of this Message.

getExpires

ExpiresHeader getExpires()

Gets the ExpiresHeader of this Message. This is the same as this.getHeader(Expires);

Returns:

the ExpiresHeader of the message body.

setSIPVersion

void setSIPVersion(java.lang.String version)
                   throws java.text.ParseException

Sets the protocol version of SIP being used by this Message.

Parameters:

version - the new String object containing the version of the SIP Protocol of this Message.

Throws:

java.text.ParseException - which signals that an error has been reached unexpectedly while parsing the version argument.

getSIPVersion

java.lang.String getSIPVersion()

Gets the protocol version of SIP being used by this Message.

Returns:

the protocol version of the SIP protocol of this message.

clone

java.lang.Object clone()

Creates and returns a deep copy of the Message. This methods must ensure a deep copy of the message, so that it can be modified without effecting the original message. This provides useful functionality for proxying Requests and Responses, for example:

• Recieve a message.
• Create a deep clone of the message.
• Modify necessary headers.
• Proxy the message using the send methods on the SipProvider.

The message contents are cloned as follows:

• If the content is of type byte[] a new byte[] array is allocated and the original contents are copied over to the cloned Message.
• If the content is of type String then a new String equal to the old String is allocated and assigned to the cloned Message.
• If the content is of type Object and it has a public clone method then it is invoked and the resultant Object is used in the new cloned Message.

Returns:

a deep copy of Message

equals

boolean equals(java.lang.Object object)

Compare this SIP Message for equality with another. Implementations need only compare Request/Response line, From, To, CallID, MaxForwards, CSeq and Via headers for message equality.

Overrides:

equals in class java.lang.Object

Parameters:

object - the object to compare this Message with.

Returns:

true if obj is an instance of this class representing the same SIP Message as this (on the basis of comparing the headers above), false otherwise.

hashCode

int hashCode()

Gets a integer hashcode representation of the Header. This method overrides the hashcode method in java.lang.Object. Only the Request/Response line and the required headers should be used to generate the unique hashcode of a message.

Overrides:

hashCode in class java.lang.Object

Returns:

integer representation of the Message hashcode

Since:

v1.2

toString

java.lang.String toString()

Gets string representation of Message

Overrides:

toString in class java.lang.Object

Returns:

string representation of Message