| javax.sip.message.Message
| Message | | public interface Message extends Cloneable,Serializable(Code) | | 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.
See Also: Request
See Also: Response
See Also: Header
author:
BEA Systems, NIST
version:
1.2 |
| addFirst | | public void addFirst(Header header) throws SipException, NullPointerException(Code) | | 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
Message.setHeader(Header) method.
throws:
SipException - -- if the header to be added is a singleton and an instance of the headeralready exists.
throws:
NullPointerException - -- if the argument is null.
Parameters:
header - the new Header to be added to the existing Headers List.
since:
v1.2 |
| addHeader | | public void addHeader(Header header)(Code) | | 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
Message.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 | | public void addLast(Header header) throws SipException, NullPointerException(Code) | | 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
Message.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 existinglist of headers
throws:
NullPointerException - -- if the argument is null.
throws:
SipException - -- if the header is a singleton and an instance of the headeralready exists.
since:
v1.2 |
| clone | | public Object clone()(Code) | | 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.
a deep copy of Message |
| equals | | public boolean equals(Object object)(Code) | | 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.
Parameters:
object - the object to compare this Message with. 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. |
| getContent | | public Object getContent()(Code) | | Gets the body content of the Message as an Object.
the body content of the Message as an Object, this method returns null if a body does not exist. |
| getContentDisposition | | public ContentDispositionHeader getContentDisposition()(Code) | | Gets the ContentDispositionHeader of this Message. This is the same as
this.getHeader(Content-Disposition);
the ContentDispositionHeader of the message body. |
| getContentEncoding | | public ContentEncodingHeader getContentEncoding()(Code) | | Gets the ContentEncodingHeader of this Message. This is the same as
this.getHeader(Content-Encoding);
the ContentEncodingHeader of the message body. |
| getContentLanguage | | public ContentLanguageHeader getContentLanguage()(Code) | | Gets the ContentLanguageHeader of this Message. This is the same as
this.getHeader(Content-Langauge);
the ContentLanguageHeader of the message body. |
| getContentLength | | public ContentLengthHeader getContentLength()(Code) | | Gets the ContentLengthHeader of the body content of this Message. This is
the same as this.getHeader(Content-Length);
the ContentLengthHeader of the message body. |
| getExpires | | public ExpiresHeader getExpires()(Code) | | Gets the ExpiresHeader of this Message. This is the same as
this.getHeader(Expires);
the ExpiresHeader of the message body. |
| getHeader | | public Header getHeader(String headerName)(Code) | | 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. the Header of the specified name in the Message, this method returns null if the Header does not exist. |
| getHeaderNames | | public ListIterator getHeaderNames()(Code) | | 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.
the ListIterator over the set of all the Header Names in the Message. |
| getHeaders | | public ListIterator getHeaders(String headerName)(Code) | | 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. 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. |
| getRawContent | | public byte[] getRawContent()(Code) | | Gets the body content of the Message as a byte array.
the body content of the Message as a byte array, this method returns null if a body does not exist. |
| getSIPVersion | | public String getSIPVersion()(Code) | | Gets the protocol version of SIP being used by this Message.
the protocol version of the SIP protocol of this message. |
| getUnrecognizedHeaders | | public ListIterator getUnrecognizedHeaders()(Code) | | 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.
the ListIterator over all the UnrecognizedHeaders in the Message represented as Strings, this method returns an empty ListIterator if no UnrecognizedHeaders exist. |
| hashCode | | public int hashCode()(Code) | | 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.
integer representation of the Message hashcode
since:
v1.2 |
| removeContent | | public void removeContent()(Code) | | Removes the body content from this Message and all associated entity
headers, if a body exists, this method returns sliently if no body exists.
|
| removeFirst | | public void removeFirst(String headerName) throws NullPointerException(Code) | | 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.
throws:
NullPointerException - -- if the arg is null
Parameters:
headerName - the name of the header to be removed.
since:
v1.2 |
| removeHeader | | public void removeHeader(String headerName)(Code) | | 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
Message.setHeader(Header) .
Parameters:
headerName - the new string value name of the Header to be removed. |
| removeLast | | public void removeLast(String headerName) throws NullPointerException(Code) | | 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.
since:
v1.2 |
| setContent | | public void setContent(Object content, ContentTypeHeader contentTypeHeader) throws ParseException(Code) | | 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.
Parameters:
contentTypeHeader - the new ContentTypeHeader object that definesthe content type value.
throws:
ParseException - which signals that an error has been reachedunexpectedly while parsing the body. |
| setContentDisposition | | public void setContentDisposition(ContentDispositionHeader contentDisposition)(Code) | | 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. |
| setContentEncoding | | public void setContentEncoding(ContentEncodingHeader contentEncoding)(Code) | | 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. |
| setContentLanguage | | public void setContentLanguage(ContentLanguageHeader contentLanguage)(Code) | | 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. |
| setContentLength | | public void setContentLength(ContentLengthHeader contentLength)(Code) | | 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. |
| setExpires | | public void setExpires(ExpiresHeader expires)(Code) | | 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. |
| setHeader | | public void setHeader(Header header)(Code) | | 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. |
| setSIPVersion | | public void setSIPVersion(String version) throws ParseException(Code) | | 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:
ParseException - which signals that an error has been reachedunexpectedly while parsing the version argument. |
| toString | | public String toString()(Code) | | Gets string representation of Message
string representation of Message |
|
|