javax.servlet.sip

Interface SipServletMessage

All Superinterfaces:

AttributeStore, Cloneable

All Known Subinterfaces:

SipServletRequest, SipServletResponse

public interface SipServletMessage
extends Cloneable, AttributeStore

Defines common aspects of SIP requests and responses.

The Servlet API is defined with an implicit assumption that servlets receives requests from clients, inspects various aspects of the corresponding ServletRequest object, and generates a response by setting various attributes of a ServletResponse object. This model fits HTTP well, because HTTP servlets always execute origin servers; they execute only to process incoming requests and never initiates HTTP requests of their own.

SIP services, on the other hand, does need to be able to initiate requests of their own. This implies that SIP request and response classes are more symmetric, that is, requests must be writable as well as readable, and likewise, responses must be readable as well as writable.

The SipServletMessage interface defines a number of methods which are common to SipServletRequest and SipServletResponse, for example setters and getters for message headers and content.

System Headers

Applications must not add, delete, or modify so-called "system" headers. These are header fields that the servlet container manages: From, To, Call-ID, CSeq, Via, Route (except through pushRoute), Record-Route, Path. Contact is a system header field in messages other than REGISTER requests and responses, 3xx and 485 responses, and 200/OPTIONS responses. Additionally, for containers implementing the reliable provisional responses extension, RAck and RSeq are considered system headers also. Note that From and To are system header fields only with respect to their tags (i.e., tag parameters on these headers are not allowed to be modified but modifications are allowed to the other parts).

Implicit Transaction State

SipServletMessage objects always implicitly belong to a SIP transaction, and the transaction state machine (as defined by the SIP specification) constrains what messages can legally be sent at various points of processing. If a servlet attempts to send a message which would violate the SIP specification (for example, the transaction state machine), the container throws an IllegalStateException.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	SipServletMessage.HeaderForm Type header forms.

Method Summary

Methods

Modifier and Type	Method and Description
void	addAcceptLanguage(Locale locale) Adds an acceptable Locale of this user agent.
void	addAddressHeader(String name, Address addr, boolean first) Adds the specified Address as a new value of the named header field.
void	addHeader(String name, String value) Adds a header with the given name and value.
void	addParameterableHeader(String name, Parameterable param, boolean first) Adds the specified Parameterable as a new value of the named header field.
Locale	getAcceptLanguage() Returns the preferred Locale that the UA originating this message will accept content in, based on the Accept-Language header.
Iterator<Locale>	getAcceptLanguages() Returns an Iterator over Locale objects indicating, in decreasing order starting with the preferred locale, the locales that are acceptable to the sending UA based on the Accept-Language header.
Set<Locale>	getAcceptLanguageSet() Returns a Set of Locale objects indicating, in decreasing order starting with the preferred locale, the locales that are acceptable to the sending UA based on the Accept-Language header.
Address	getAddressHeader(String name) Returns the value of the specified header as a Address object.
List<Address>	getAddressHeaderList(String name) Returns a List of all Address header field values for the specified header.
ListIterator<Address>	getAddressHeaders(String name) Returns a ListIterator over all Address header field values for the specified header.
SipApplicationSession	getApplicationSession() Returns the application session to which this message belongs.
SipApplicationSession	getApplicationSession(boolean create) Returns the app session to which this message belongs.
Enumeration<String>	getAttributeNames() Deprecated. As of release 2.0, replaced by AttributeStore.getAttributeNameSet()
String	getCallId() Returns the value of the Call-ID header in this SipServletMessage.
String	getCharacterEncoding() Returns the name of the charset used for the MIME body sent in this message.
Object	getContent() Returns the content as a Java object.
Locale	getContentLanguage() Returns the locale of this message.
int	getContentLength() Returns the length in number of bytes of the content part of this message.
String	getContentType() Returns the value of the Content-Type header field.
int	getExpires() Returns the value of the Expires header.
Address	getFrom() Returns the value of the From header.
String	getHeader(String name) Returns the value of the specified header as a String.
SipServletMessage.HeaderForm	getHeaderForm()
List<String>	getHeaderList(String name) Returns all the values of the specified header as a List of String objects.
List<String>	getHeaderNameList() Returns an immutable List of all the header names this message contains in the long format.
Iterator<String>	getHeaderNames() Returns an Iterator over all the header names this message contains in the long format.
ListIterator<String>	getHeaders(String name) Returns all the values of the specified header as a ListIterator over a number of String objects.
String	getInitialRemoteAddr() Returns the IP address of the upstream/downstream hop from which this message was initially received by the container. Unlike getRemoteAddr(), this method returns the same value regardless of which application invokes it in the same application composition chain of a specific application router.
int	getInitialRemotePort() Returns the port number of the upstream/downstream hop from which this message initially received by the container.
String	getInitialTransport() Returns the name of the protocol with which this message was initially received by the container, e.g.
String	getLocalAddr() Returns the IP address of the interface this message was received on.
int	getLocalPort() Returns the local port this message was received on.
SipWebSocketContext	getLocalSipWebSocketContext() Returns the instance of SipWebSocketContext associated with the SIP WebSocket connection on which this message has arrived or sent.
String	getMethod() Returns the SIP method of this message.
Parameterable	getParameterableHeader(String name) Returns the value of the specified header field as a Parameterable object.
List<? extends Parameterable>	getParameterableHeaderList(String name) Returns a List of all Parameterable header field values for the specified header name.
ListIterator<? extends Parameterable>	getParameterableHeaders(String name) Returns a ListIterator over all Parameterable header field values for the specified header name.
String	getProtocol() Returns the name and version of the protocol of this message.
byte[]	getRawContent() Returns message content as a byte array.
String	getRemoteAddr() Returns the IP address of the next upstream/downstream hop from which this message was received.
int	getRemotePort() Returns the port number of the next upstream/downstream hop from which this message was received.
String	getRemoteUser() Returns the login of the user sending this message, if the user has been authenticated, or null if the user has not been authenticated.
SipSession	getSession() Returns the SipSession to which this message belongs.
SipSession	getSession(boolean create) Returns the SipSession to which this message belongs.
SessionKeepAlive.Preference	getSessionKeepAlivePreference() Return the session keep alive preference as in the SIP message.
Address	getTo() Returns the value of the To header.
String	getTransport() Returns the name of the protocol with which this message was received, e.g.
Principal	getUserPrincipal() Returns a java.security.Principal object containing the name of the authenticated user agent sending this message.
boolean	isCommitted() Returns true if this message is committed, that is, if one of the following conditions is true: This message is an incoming request for which a final response has already been generated This message is an outgoing request which has already been sent This message is an incoming non-reliable provisional response received by a servlet acting as a UAC This message is an incoming reliable provisional response for which PRACK has already been generated.
boolean	isInternallyRouted() This method returns true if the message was sent by a local application.
boolean	isSecure() Returns a boolean indicating whether this message was received over a secure channel, such as TLS.
boolean	isUserInRole(String role) Returns a boolean indicating whether the authenticated user is included in the specified logical "role".
void	pushLocalPath() Adds a Path header for this servlet container to this message.
void	pushPath(Address uri) Adds a Path header field value to this message.
void	removeHeader(String name) Removes the specified header.
void	send() Sends this SipServletMessage.
void	setAcceptLanguage(Locale locale) Sets the preferred Locale that this user agent will accept content, reason phrases, warnings, etc.
void	setAddressHeader(String name, Address addr) Sets the header with the specified name to have the value specified by the address argument.
void	setCharacterEncoding(String enc) Overrides the name of the character encoding that will be used to convert the body of this message from bytes to characters or vice versa.
void	setContent(Object content, String contentType) Sets the content of this message to the specified Object.
void	setContentLanguage(Locale locale) Sets the locale of this message, setting the headers (Content-Language and the Content-Type's charset) as appropriate.
void	setContentLength(int len) Sets the value of the Content-Length header.
void	setContentType(String type) Sets the content type of the response being sent to the client.
void	setExpires(int seconds) Sets the value of the Expires header in this message.
void	setHeader(String name, String value) Sets a header with the given name and value.
void	setHeaderForm(SipServletMessage.HeaderForm form) Indicates which of the compact or long form should the headers in this message have.
void	setParameterableHeader(String name, Parameterable param) Sets the header with the specified name to have the value specified by the address argument.

Methods inherited from interface javax.servlet.sip.AttributeStore

clearAttributes, getAttribute, getAttributeNameSet, removeAttribute, setAttribute

Method Detail

getFrom

Address getFrom()

Returns the value of the From header.

Returns:

internal representation of the From header

getTo

Address getTo()

Returns the value of the To header.

Returns:

internal representation of the To header

getMethod

String getMethod()

Returns the SIP method of this message. This is a token consisting of all upper-case letters, for example "INVITE". For requests, the SIP method is in the request line while for responses it may be extracted from the CSeq header.

Returns:

the SIP method of this SipServletMessage

getProtocol

String getProtocol()

Returns the name and version of the protocol of this message. This is in the form <protocol> "/" <major-version-number> "." <minor-version-number>, for example "SIP/2.0".

For this version of the SIP Servlet API this is always "SIP/2.0".

Returns:

a String containing the protocol name and version number

getHeader

String getHeader(String name)

Returns the value of the specified header as a String. If the message did not include a header of the specified name, this method returns null. If the message included a header of the specified name with no value, this method returns an empty String. If multiple headers exist, the first one is returned. The header name is case insensitive.

Either the long or compact name can be used to access the header field, as both are treated as equivalent. The list of assigned compact form is available in the IANA registry at http://www.iana.org/assignments/sip-parameters

For example,

   getHeader("Content-Type");
   getHeader("c");
 

will both return the same value.

Parameters:

name - a String specifying the header name, either the long or compact form

Returns:

a String containing the value of the requested header, or null if the message does not have a header of that name

Throws:

NullPointerException - if the name is null.

getHeaders

ListIterator<String> getHeaders(String name)

Returns all the values of the specified header as a ListIterator over a number of String objects. The values returned by the Iterator follow the order in which they appear in the message header.

Either the long or compact name can be used to access the header field, as both are treated as equivalent. The list of assigned compact form is available in the IANA registry at http://www.iana.org/assignments/sip-parameters

Some headers, such as Accept-Language can be sent by clients as several headers each with a different value rather than sending the header as a comma separated list.

If the message did not include any headers of the specified name, this method returns an empty Iterator. If the message included headers of the specified name with no values, this method returns an Iterator over empty Strings. The header name is case insensitive.

Note: This is a fail-fast iterator and can throw ConcurrentModificationException if the underlying implementation does not allow modification after the iterator is created.

Attempts to modify the specified header field through the returned list iterator must fail with an IllegalArgumentException if the header field is a system header.

Parameters:

name - a String specifying the header name, either the long or compact form

Returns:

a ListIterator over the String values of the specified header field

Throws:

NullPointerException - if the name is null.

getHeaderList

List<String> getHeaderList(String name)

Returns all the values of the specified header as a List of String objects. The List follow the order in which they appear in the message header.

Either the long or compact name can be used to access the header field, as both are treated as equivalent. The list of assigned compact form is available in the IANA registry at http://www.iana.org/assignments/sip-parameters

Some headers, such as Accept-Language can be sent by clients as several headers each with a different value rather than sending the header as a comma separated list.

If the message did not include any headers of the specified name, this method returns null. If the message included headers of the specified name with no values, this method returns a an empty List. The header name is case insensitive.

Attempts to modify the specified header field through the returned list must fail with an IllegalArgumentException if the header field is a system header.

Parameters:

name - a String specifying the header name, either the long or compact form

Returns:

a List of the String values of the specified header field

Throws:

NullPointerException - if the name is null.

Since:

2.0

getHeaderNames

Iterator<String> getHeaderNames()

Returns an Iterator over all the header names this message contains in the long format. If the message has no headers, this method returns an empty Iterator.

Note: This is a fail-fast iterator and can throw ConcurrentModificationException if the underlying implementation does not allow modification after the iterator is created.

Some servlet containers do not allow servlets to access headers using this method, in which case this method returns null.

Returns:

an Iterator over the names of all header fields present within this message; if the message has no header fields, an empty enumeration; if the servlet container does not allow servlets to use this method, null

getHeaderNameList

List<String> getHeaderNameList()

Returns an immutable List of all the header names this message contains in the long format. If the message has no headers, this method returns an empty List.

Returns:

an List of the names of all header fields present within this message.

Since:

2.0

setHeader

void setHeader(String name,
             String value)

Sets a header with the given name and value. If the header had already been set, the new value overwrites the previous one. If there are multiple headers with the same name, they all are replaced by this header name, value pair.

Either the long or compact name can be used to access the header field, as both are treated as equivalent. The applications choice of long or compact form shall take effect only of the HeaderForm parameter is set to SipServletMessage.HeaderForm.DEFAULT.

Note: applications should never attempt to set the From, To, Call-ID, CSeq, Via, Record-Route, and Route headers. Also, setting of the Contact header is subject to the constraints mentioned in the introduction.

Parameters:

name - a String specifying the header name, either the long or compact form

value - the header value

Throws:

IllegalArgumentException - if the specified header field is a system header

NullPointerException - if the name or value is null

addHeader

void addHeader(String name,
             String value)

Adds a header with the given name and value. This method allows headers to have multiple values. The container MAY check that the specified header field can legally appear in this message.

Either the long or compact name can be used to access the header field, as both are treated as equivalent. The list of assigned compact form is available in the IANA registry at http://www.iana.org/assignments/sip-parameters

Note: applications should never attempt to set the From, To, Call-ID, CSeq, Via, Record-Route, and Route headers. Also, setting of the Contact header is subject to the constraints mentioned in the introduction.

Parameters:

name - a String specifying the header name, either the long or compact form

value - the additional header value

Throws:

IllegalArgumentException - if the specified header field is a system header or if it cannot legally appear in this message

removeHeader

void removeHeader(String name)

Removes the specified header. If multiple headers exists with the given name, they're all removed.

Either the long or compact name can be used to access the header field, as both are treated as equivalent.

Parameters:

name - a String specifying the header name, either the long or compact form

Throws:

IllegalArgumentException - if the specified header field is a system header

getAddressHeader

Address getAddressHeader(String name)
                         throws ServletParseException

Returns the value of the specified header as a Address object.

This method can be used with headers which are defined to contain one or more entries matching (name-addr | addr-spec) *(SEMI generic-param) as defined in RFC 3261. This includes, for example, Contact and Route.

Either the long or compact name can be used to access the header field, as both are treated as equivalent.

If there is more than one header field value the first is returned.

Parameters:

name - a case insensitive String specifying the name of the header, either the long or compact form

Returns:

value of the header as an Address

Throws:

ServletParseException - if the specified header field cannot be parsed as a SIP address object

NullPointerException - if the name is null.

getAddressHeaders

ListIterator<Address> getAddressHeaders(String name)
                                        throws ServletParseException

Returns a ListIterator over all Address header field values for the specified header. The values returned by the Iterator follow the order in which they appear in the message header.

This method can be used with headers which are defined to contain one or more entries matching (name-addr | addr-spec) *(SEMI generic-param) as defined in RFC 3261. This includes, for example, Contact and Route.

Either the long or compact name can be used to access the header field, as both are treated as equivalent.

If the message did not include any headers of the specified name, this method returns an empty Iterator. If the message included headers of the specified name with no values, this method returns an Iterator over empty Strings.

Attempts to modify the specified header field through the returned list iterator must fail with an IllegalArgumentException if the header field is a system header. For non-system headers the argument to the add and set methods of the iterator returned by getAddressHeaders must be Address objects.

Note: This is a fail-fast iterator and can throw ConcurrentModificationException if the underlying implementation does not allow modification after the iterator is created.

Parameters:

name - a case insensitive String specifying the name of the header field, either the long or compact form

Returns:

a ListIterator over the Address values of the specified header field

Throws:

ServletParseException - if the specified header field cannot be parsed as a SIP address object

NullPointerException - if the name is null.

getAddressHeaderList

List<Address> getAddressHeaderList(String name)
                                   throws ServletParseException

Returns a List of all Address header field values for the specified header. The values returned in the List follow the order in which they appear in the message header.

This method can be used with headers which are defined to contain one or more entries matching (name-addr | addr-spec) *(SEMI generic-param) as defined in RFC 3261. This includes, for example, Contact and Route.

Either the long or compact name can be used to access the header field, as both are treated as equivalent.

If the message did not include any headers of the specified name, this method returns null. If the message included headers of the specified name with no values, this method returns an empty List.

Attempts to modify the specified header field through the returned list must fail with an IllegalArgumentException if the header field is a system header.

Parameters:

name - a case insensitive String specifying the name of the header field, either the long or compact form

Returns:

a List of the Address values of the specified header field

Throws:

ServletParseException - if the specified header field cannot be parsed as a SIP address object

NullPointerException - if the name is null.

Since:

2.0

setAddressHeader

void setAddressHeader(String name,
                    Address addr)

Sets the header with the specified name to have the value specified by the address argument.

This method can be used with headers which are defined to contain one or more entries matching (name-addr | addr-spec) *(SEMI generic-param) as defined in RFC 3261. This includes, for example, Contact and Route.

Either the long or compact name can be used to access the header field, as both are treated as equivalent.

Parameters:

name - the long or compact name of the header to set

addr - the assigned address value

Throws:

IllegalArgumentException - if the specified header isn't defined to hold address values or if the specified header field is a system header

addAddressHeader

void addAddressHeader(String name,
                    Address addr,
                    boolean first)

Adds the specified Address as a new value of the named header field. The address is added as the last header field value.

This method can be used with headers which are defined to contain one or more entries matching (name-addr | addr-spec) *(SEMI generic-param) as defined in RFC 3261. This includes, for example, Contact and Route.

Either the long or compact name can be used to access the header field, as both are treated as equivalent.

Parameters:

name - the long or compact name of the header to set

addr - the additional address value

first - if true, the address is added as the first value of the specified header field, otherwise it will be the last

Throws:

IllegalArgumentException - if the specified header isn't defined to hold address values or if the specified header field is a system header

getParameterableHeader

Parameterable getParameterableHeader(String name)
                                     throws ServletParseException

Returns the value of the specified header field as a Parameterable object.

This method can be used with headers which are defined to contain one or more entries matching field-value *(;parameter-name=parameter-value) as defined in RFC 3261. This includes, for example, Event and Via.

Either the long or compact name can be used to access the header field, as both are treated as equivalent.

If there is more than one header field value the first is returned.

Parameters:

name - a case insensitive String specifying the name of the header, either the long or compact form

Returns:

value of the header as a Parameterable

Throws:

ServletParseException - if the specified header field cannot be parsed as a SIP parameterable object

NullPointerException - if the name is null.

Since:

1.1

getParameterableHeaders

ListIterator<? extends Parameterable> getParameterableHeaders(String name)
                                                              throws ServletParseException

Returns a ListIterator over all Parameterable header field values for the specified header name. The values returned by the Iterator follow the order in which they appear in the message header.

This method can be used with headers which are defined to contain one or more entries matching field-value *(;parameter-name=parameter-value) as defined in RFC 3261. This includes, for example, Event and Via.

Either the long or compact name can be used to access the header field, as both are treated as equivalent.

If the message did not include any headers of the specified name, this method returns an empty Iterator. If the message included headers of the specified name with no values, this method returns an Iterator over empty Strings.

Attempts to modify the specified header field through the returned list iterator must fail with an IllegalArgumentException if the header field is a system header.

Note: This is a fail-fast iterator and can throw ConcurrentModificationException if the underlying implementation does not allow modification after the iterator is created.

Parameters:

name - a case insensitive String specifying the name of the header field, either the long or compact form

Returns:

a ListIterator over the Parameterable values of the specified header field

Throws:

ServletParseException - if the specified header field cannot be parsed as a SIP parameterable object

NullPointerException - if the name is null.

Since:

1.1

getParameterableHeaderList

List<? extends Parameterable> getParameterableHeaderList(String name)
                                                         throws ServletParseException

Returns a List of all Parameterable header field values for the specified header name. The values returned in the List follow the order in which they appear in the message header.

This method can be used with headers which are defined to contain one or more entries matching field-value *(;parameter-name=parameter-value) as defined in RFC 3261. This includes, for example, Event and Via.

Either the long or compact name can be used to access the header field, as both are treated as equivalent.

If the message did not include any headers of the specified name, this method returns null. If the message included headers of the specified name with no values, this method returns an empty List.

Attempts to modify the specified header field through the returned list must fail with an IllegalArgumentException if the header field is a system header.

Parameters:

name - a case insensitive String specifying the name of the header field, either the long or compact form

Returns:

a List of the Parameterable values of the specified header field

Throws:

ServletParseException - if the specified header field cannot be parsed as a SIP parameterable object

NullPointerException - if the name is null.

Since:

2.0

setParameterableHeader

void setParameterableHeader(String name,
                          Parameterable param)

Sets the header with the specified name to have the value specified by the address argument.

This method can be used with headers which are defined to contain one or more entries matching field-value *(;parameter-name=parameter-value) as defined in RFC 3261. This includes, for example, Event and Via.

Either the long or compact name can be used to access the header field, as both are treated as equivalent.

Parameters:

name - the long or compact name of the header to set

param - the assigned Parameterable value

Throws:

IllegalArgumentException - if the specified header isn't defined to hold Parameterable values or if the specified header field is a system header

Since:

1.1

addParameterableHeader

void addParameterableHeader(String name,
                          Parameterable param,
                          boolean first)

Adds the specified Parameterable as a new value of the named header field. The parameterable is added as the last header field value.

This method can be used with headers which are defined to contain one or more entries matching field-value *(;parameter-name=parameter-value) as defined in RFC 3261. This includes, for example, Event and Via.

Either the long or compact name can be used to access the header field, as both are treated as equivalent.

Parameters:

name - the long or compact name of the header to set

param - the additional parameterable value

first - if true, the parameterable is added as the first value of the specified header field, otherwise it will be the last

Throws:

IllegalArgumentException - if the specified header isn't defined to hold Parameterable values or if the specified header field is a system header

Since:

1.1

getCallId

String getCallId()

Returns the value of the Call-ID header in this SipServletMessage.

Returns:

the Call-ID value of this SipServletMessage

getExpires

int getExpires()

Returns the value of the Expires header. The Expires header field gives the relative time after which the message (or content) expires. The unit of measure is seconds.

Returns:

value of Expires header, or -1 if the header does not exist

setExpires

void setExpires(int seconds)

Sets the value of the Expires header in this message. This method is equivalent to:

   setHeader("Expires", String.valueOf(seconds));
 

Parameters:

seconds - the value of the Expires header measured in seconds

getCharacterEncoding

String getCharacterEncoding()

Returns the name of the charset used for the MIME body sent in this message. This method returns null if the message does not specify a character encoding.

The message character encoding is used when converting between bytes and characters. If the character encoding hasn't been set explicitly UTF-8 will be used for this purpose.

For more information about character encodings and MIME see RFC 2045 (http://www.ietf.org/rfc/rfc2045.txt).

Returns:

a String specifying the name of the charset, for example, UTF-8

setCharacterEncoding

void setCharacterEncoding(String enc)
                          throws UnsupportedEncodingException

Overrides the name of the character encoding that will be used to convert the body of this message from bytes to characters or vice versa.

Explicitly setting a message's character encoding potentially affects the behavior of subsequent calls to getContent() and setContent(java.lang.Object, java.lang.String). This method must be called prior to calling either of those methods.

Parameters:

enc - name of the chararacter encoding

Throws:

UnsupportedEncodingException - if this is not a valid encoding

getContentLength

int getContentLength()

Returns the length in number of bytes of the content part of this message. This directly reflects the value of the Content-Length header field.

Returns:

an integer containing the length of the message body

getContentType

String getContentType()

Returns the value of the Content-Type header field.

Returns:

a String containing the name of the MIME type of this message, or null if the body is empty

getRawContent

byte[] getRawContent()
                     throws IOException

Returns message content as a byte array. The reference is returned if the application wants to re-use the content for another message it should make a copy.

Returns:

message content as a raw byte array, or null if no content is set

Throws:

IOException - if an IOException occurred

getContent

Object getContent()
                  throws IOException,
                         UnsupportedEncodingException

Returns the content as a Java object. The actual type of the returned object depends on the MIME type of the content itself (the Content-Type). Containers are required to return a String object for MIME type text/plain as for other text/* MIME types for which the container doesn't have specific knowledge.

It is encouraged that the object returned for "multipart" MIME content is a javax.mail.Multipart object. A byte array is returned for content-types that are unknown to the container.

The message's character encoding is used when the MIME type indicates that the content consists of character data.

Note: This method, together with setContent, is modelled over similar methods in the JavaMail API. Whereas the JavaMail API mandates the use of the Java Activation Framework (JAF) as the underlying data handling system, the SIP servlet API doesn't currently require JAF.

Returns:

an object representing the parsed content, or a byte[] object containing the raw content if the MIME type isn't known to the platform

Throws:

IOException - if an IOException occurred

UnsupportedEncodingException - if the content is textual in character but this message's character encoding is not supported by the platform

setContent

void setContent(Object content,
              String contentType)
                throws UnsupportedEncodingException

Sets the content of this message to the specified Object.

This method only works if the implementation "knows about" the specified object and MIME type. Containers are required to handle byte[] content with any MIME type.

Furthermore, containers are required to handle String content when used with a text/* content type. When invoked with non-String objects and a text/* content type, containers may invoke toString() on the content Object in order to obtain the body's character data. It is also recommended that implementations know how to handle javax.mail.Multipart content when used together with "multipart" MIME types.

When converting String content, this method may use the the message's character encoding (as set by setCharacterEncoding(java.lang.String), setContentType(java.lang.String) or setContentLanguage(java.util.Locale)) to map the String to a byte array.

Note: This method, together with getContent(), is modelled over a similar method in the JavaMail API. Whereas the JavaMail API mandates the use of the Java Activation Framework (JAF) as the underlying data handling system, the SIP servlet API doesn't currently require JAF.

Parameters:

content - an object representing the message content

contentType - MIME type of the object

Throws:

UnsupportedEncodingException - if the content is textual in nature and this message's character encoding is unsupported by the server

IllegalArgumentException - if the platform doesn't know how to serrialize content of the specified MIME type

IllegalStateException - if the message has already been sent or if it's read-only

setContentLength

void setContentLength(int len)

Sets the value of the Content-Length header.

Applications are discouraged from setting the Content-Length directly using this method; they should instead use the setContent methods which guarantees that the Content-Length is computed and set correctly.

Parameters:

len - an integer specifying the length of the content being sent to the peer; sets the Content-Length header

Throws:

IllegalStateException - if this is an incoming message or if it has already been sent

setContentType

void setContentType(String type)

Sets the content type of the response being sent to the client. The content type may include the type of character encoding used, for example, text/html; charset=UTF-8. This will cause the message's current character encoding to be set.

If obtaining a PrintWriter or calling setContent, this method should be called first.

Parameters:

type - a String specifying the MIME type of the content

getAttributeNames

@Deprecated
Enumeration<String> getAttributeNames()

Deprecated. As of release 2.0, replaced by AttributeStore.getAttributeNameSet()

getSession

SipSession getSession()

Returns the SipSession to which this message belongs. If the session didn't already exist it is created. This method is equivalent to calling getSession(true).

Returns:

the SipSession to which this SipServletMessage belongs

getSession

SipSession getSession(boolean create)

Returns the SipSession to which this message belongs.

Parameters:

create - indicates whether the session is created if it doesn't already exist

Returns:

the SipSession to which this SipServletMessage belongs, or null if one hasn't been created and create is false

getApplicationSession

SipApplicationSession getApplicationSession()

Returns the application session to which this message belongs. If the session doesn't already exist it is created.

Returns:

the application session to which this SipServletMessage belongs

getApplicationSession

SipApplicationSession getApplicationSession(boolean create)

Returns the app session to which this message belongs.

Parameters:

create - if true the session is created if it didn't already exist, otherwise null is returned

getAcceptLanguage

Locale getAcceptLanguage()

Returns the preferred Locale that the UA originating this message will accept content in, based on the Accept-Language header. If this message doesn't contain an Accept-Language header, this method returns null. Note that this behavior is different from v1.0 where the default locale for the server would have been returned.

Returns:

the preferred Locale for the sending user agent

getAcceptLanguages

Iterator<Locale> getAcceptLanguages()

Returns an Iterator over Locale objects indicating, in decreasing order starting with the preferred locale, the locales that are acceptable to the sending UA based on the Accept-Language header. If this message doesn't provide an Accept-Language header, this method returns an empty Iterator. Note that this behavior is different from v1.0 where an Iterator containing the default locale for the server would have been returned.

Returns:

an Iterator over preferred locales for the UA originating this message

getAcceptLanguageSet

Set<Locale> getAcceptLanguageSet()

Returns a Set of Locale objects indicating, in decreasing order starting with the preferred locale, the locales that are acceptable to the sending UA based on the Accept-Language header. If this message doesn't provide an Accept-Language header, this method returns an empty Set.

Returns:

a Set of preferred locales for the UA originating this message

Since:

2.0

setAcceptLanguage

void setAcceptLanguage(Locale locale)

Sets the preferred Locale that this user agent will accept content, reason phrases, warnings, etc. in. The language identified by the Locale will be listed in an Accept-Language header.

A null argument is valid and removes and existing Accept-Language headers.

Parameters:

locale - the preferred locale of this user agent

addAcceptLanguage

void addAcceptLanguage(Locale locale)

Adds an acceptable Locale of this user agent. The language identified by the Locale will be listed in an Accept-Language header with a lower q-value than any existing Accept-Language value, meaning the locale is less preferred than those already identified in this message.

Parameters:

locale - a locale acceptable to this user agent

setContentLanguage

void setContentLanguage(Locale locale)

Sets the locale of this message, setting the headers (Content-Language and the Content-Type's charset) as appropriate. This method should be called before a call to setContent.

Parameters:

locale - the locale of this message

getContentLanguage

Locale getContentLanguage()

Returns the locale of this message. This method returns the Locale identified by the Content-Language header of the message, or null if the Content-Language header is not present.

Returns:

Locale of this message, or null if none.

pushPath

void pushPath(Address uri)

Adds a Path header field value to this message. The new value is added ahead of any existing Path header fields. If this request does not already contain a Path header, one is added with the value specified in the argument. This method allows a UAC or a proxy to add Path on a REGISTER Request.

Parameters:

uri - The address that is added as a Route header value

Throws:

IllegalStateException - if invoked on non-REGISTER Request, non-REGISTER response or non-200 class REGISTER response.

Since:

2.0

pushLocalPath

void pushLocalPath()

Adds a Path header for this servlet container to this message. The new value is added ahead of any existing Path header fields. If this request does not already contain a Path header, one is added with the value specified in the argument. This method allows a UAC or a proxy to add Path on a REGISTER Request.

Throws:

IllegalStateException - if invoked on non-REGISTER Request, non-REGISTER response or non-200 class REGISTER response.

Since:

2.0

send

void send()
          throws IOException

Sends this SipServletMessage.

Throws:

IOException - if a transport error occurs when trying to send this message

IllegalStateException - if this message cannot legally be sent in the current state of the underlying SIP transaction

isSecure

boolean isSecure()

Returns a boolean indicating whether this message was received over a secure channel, such as TLS.

Returns:

a boolean indicating if this message was received over a secure channel

isCommitted

boolean isCommitted()

Returns true if this message is committed, that is, if one of the following conditions is true:

• This message is an incoming request for which a final response has already been generated
• This message is an outgoing request which has already been sent
• This message is an incoming non-reliable provisional response received by a servlet acting as a UAC
• This message is an incoming reliable provisional response for which PRACK has already been generated. (Note that this scenario applies to containers that support the 100rel extension.)
• This message is an incoming final response received by a servlet acting as a UAC for a Non INVITE transaction
• This message is a response which has been forwarded upstream
• This message is an incoming final response to an INVITE transaction and an ACK has been generated
• This message is an outgoing request, the client transaction has timed out and no response was received from the UAS and the container generates a 408 response locally

Returns:

true if this message is committed, false otherwise

getRemoteUser

String getRemoteUser()

Returns the login of the user sending this message, if the user has been authenticated, or null if the user has not been authenticated.

Returns:

a String specifying the login of the user sending this message, or null if the user has not been authenticated

isUserInRole

boolean isUserInRole(String role)

Returns a boolean indicating whether the authenticated user is included in the specified logical "role". Roles and role membership can be defined using deployment descriptors. If the user has not been authenticated, the method returns false.

Parameters:

role - a String specifying the name of the role

Returns:

a boolean indicating whether the user sending this message belongs to a given role; false if the user has not been authenticated

getUserPrincipal

Principal getUserPrincipal()

Returns a java.security.Principal object containing the name of the authenticated user agent sending this message. If the user agent has not been authenticated, the method returns null.

Returns:

a java.security.Principal representing the sending user, or null if the user has not been authenticated

getSessionKeepAlivePreference

SessionKeepAlive.Preference getSessionKeepAlivePreference()

Return the session keep alive preference as in the SIP message.

Returns:

Preference object.

Since:

2.0

See Also:

SessionKeepAlive.Preference

getLocalAddr

String getLocalAddr()

Returns the IP address of the interface this message was received on.

Returns:

IP address of the local interface this message was received on, or null if the message is a locally generated one such as application created outgoing messages and container generated responses.

getLocalPort

int getLocalPort()

Returns the local port this message was received on.

Returns:

local port on which this message was received, or -1 if the message is a locally generated one such as application created outgoing messages and container generated responses.

getRemoteAddr

String getRemoteAddr()

Returns the IP address of the next upstream/downstream hop from which this message was received. Applications can determine the actual IP address of the UA that originated the message from the message Via header fields.
If the message was internally routed (from one application to the next within the same container), then this method returns the address of the container's SIP interface.

Returns:

a String containing the IP address of the sender of this message, or null if the message is a locally generated one such as application created outgoing messages and container generated responses.

getRemotePort

int getRemotePort()

Returns the port number of the next upstream/downstream hop from which this message was received.
If the message was internally routed (from one application to the next within the same container), then this method returns a valid port number chosen by the container or the host TCP/IP stack.

Returns:

the port number of the sender of this message, or -1 if the message is a locally generated one such as application created outgoing messages and container generated responses.

getTransport

String getTransport()

Returns the name of the protocol with which this message was received, e.g. "UDP", "TCP", "TLS", or "SCTP".

Returns:

name of the protocol this message was received with, or null if the message is a locally generated one such as application created outgoing messages and container generated responses.

getInitialRemoteAddr

String getInitialRemoteAddr()

Returns the IP address of the upstream/downstream hop from which this message was initially received by the container.
Unlike getRemoteAddr(), this method returns the same value regardless of which application invokes it in the same application composition chain of a specific application router.

Returns:

a String containing the IP address of the sender of this message, or null if the message is a locally generated one such as application created outgoing messages and container generated responses.

Since:

1.1

getInitialRemotePort

int getInitialRemotePort()

Returns the port number of the upstream/downstream hop from which this message initially received by the container.
Unlike getRemotePort(), this method returns the same value regardless of which application invokes it in the same application composition chain of a specific application router.

Returns:

the port number of the sender of this message, or -1 if the message is a locally generated one such as application created outgoing messages and container generated responses.

Since:

1.1

getInitialTransport

String getInitialTransport()

Returns the name of the protocol with which this message was initially received by the container, e.g. "UDP", "TCP", "TLS", or "SCTP".

Returns:

name of the protocol this message was initially received with, or null if the message is a locally generated one such as application created outgoing messages and container generated responses.

Since:

1.1

getLocalSipWebSocketContext

SipWebSocketContext getLocalSipWebSocketContext()

Returns the instance of SipWebSocketContext associated with the SIP WebSocket connection on which this message has arrived or sent. In this version of SIP servlet specification, the SIP WebSocket connection is always established from the websocket client to the SIP container.

Returns:

instance of SipWebSocketContext.

Since:

2.0

See Also:

SipWebSocketContext

isInternallyRouted

boolean isInternallyRouted()

This method returns true if the message was sent by a local application.

Returns:

True if this was sent by a local application false otherwise.

Since:

2.0

setHeaderForm

void setHeaderForm(SipServletMessage.HeaderForm form)

Indicates which of the compact or long form should the headers in this message have. If compact is selected then all the headers that have compact names should be represented with them, regardless of how they were added to the message. When long is selected then all headers change to their long form. Instead if the applications wish to mix the compact and long form then they must not invoke the setUseCompactForm method or set it to use SipServletMessage.HeaderForm.DEFAULT and instead set the non-system headers directly using the compact or long form setHeader(String, String). eg.

 SipServletMessage message;
 .....
 message.setHeader("s", "Meeting at 5pm");   // Subject header compact form
 message.setHeader("Allow-Events", "telephone-event"); // Long form
 .....
 

For applications to set each header individually the value of the HeaderForm MUST be SipServletMessage.HeaderForm.DEFAULT The list of assigned compact form is available in the IANA registry at http://www.iana.org/assignments/sip-parameters

Parameters:

form - form desired by the application

Since:

1.1

getHeaderForm

SipServletMessage.HeaderForm getHeaderForm()

Returns:

the current header form that is on the message. The default is SipServletMessage.HeaderForm.DEFAULT

Since:

1.1