SipServletMessage

The shared functions between SIP requests and responses are represented by the SipServletMessage interface. It offers the fundamental techniques for working with SIP communications, such as obtaining and altering headers and content. This interface extends the java.lang.Cloneable interface and enables the duplication of SIP messages as needed.
The unique needs of SIP communication, which are very different from those of the HTTP model, are met by the SipServletMessage interface. SIP services frequently have to start requests themselves, as contrast to HTTP servlets, which function only as origin servers handling client requests. Because SIP communication is bidirectional, the request and response classes must be more symmetrically designed to be both readable and writable. As a result, the SipServletMessage interface defines a common set of actions, like handling headers and content, that are applicable to both SipServletRequest and SipServletResponse.
Notes:

• Certain SIP headers, such as From, To, Call-ID, and CSeq, are managed by the servlet container and cannot be modified directly.
• Adding or modifying the Contact header is restricted and subject to specific rules based on the type of message (e.g., allowed in REGISTER requests but restricted in others).
• Reliable provisional response headers (RAck and RSeq) are also system headers in implementations supporting this extension.
• SIP headers can appear in both long (e.g., Via, From, To) and compact forms (e.g., v, f, t). For more details, see the official IANA SIP Parameters registry.

Nested class:

SipServletMessage.HeaderForm
The class specifies the types of header formats (COMPACT and NORMAL) used in SIP messages. It allows control over how SIP headers are represented and processed. For more details, refer to the Description.

Methods:

Header Management

addHeader
void addHeader(java.lang.String name,
               java.lang.String value)
The method adds a new header with the specified name and value to the SIP message. This method allows multiple values for headers by appending the new value to an existing header of the same name. The SIP container may validate whether the header can legally appear in the message. This method accepts both the long and compact forms of SIP header names. For example, Contact and its compact equivalent m can be used interchangeably (See the IANA SIP Parameters Registry for the full list).
Parameters:
name: The name of the header, either in its long or compact form.
value: The value to add to the specified header.
Exceptions:
java.lang.IllegalArgumentException is thrown if:

• The header is a system header (e.g., From, To, Call-ID, CSeq, Via, Record-Route, Route).
• The header is not allowed in this type of SIP message.

addAddressHeader
void addAddressHeader(java.lang.String name,
                      Address addr,
                      boolean first)
The method adds an Address value to a specified header field in the SIP message. This method allows for adding multiple address entries to headers that support them, such as Contact and Route. The new Address can be added either as the first or the last value of the header.
This method supports both long and compact header names, treating them as equivalent (e.g., Contact and its compact form m).
Parameters:
name: The long or compact name of the header field to which the address will be added.
addr: The Address object to add as a new value to the specified header field.
first: If true, the address is added as the first value of the header field. If false, the address is added as the last value.
Exceptions:
java.lang.IllegalArgumentException is thrown if the specified header is not designed to hold address values or the specified header is a system header, such as From, To, Call-ID, or CSeq.

addParameterableHeader
void addParameterableHeader(java.lang.String name,
                            Parameterable param,
                            boolean first)
The method adds a Parameterable object as a new value to the specified header field in the SIP message. This method is used for headers that allow parameterized values, such as Event and Via. The new value can be added either as the first or the last value of the specified header field.
This method supports both long and compact header names, treating them as equivalent.
Parameters:
name: The long or compact name of the header field to which the Parameterable will be added.
param: The Parameterable object to add as a new value to the specified header field.
first: A boolean value. If true, the Parameterable value is added as the first value of the header field. If false, the Parameterable value is added as the last value.
Exceptions:
java.lang.IllegalArgumentException is thrown if the header is not designed to hold Parameterable values or the header is a system header, such as From, To, Call-ID, or CSeq.

setHeader
void setHeader(java.lang.String name,
               java.lang.String value)
The method sets the specified header in the SIP message with the given name and value. If a header with the same name already exists, this method replaces all existing values with the new name-value pair. It ensures that only one instance of the header is present in the message after the call.
This method accepts both the long and compact forms of SIP header names. However, the format of the header (long or compact) is applied only when the HeaderForm parameter is set to SipServletMessage.HeaderForm.DEFAULT.
Parameters:
name: The name of the header field, specified either in its long or compact form.
value: The value to set for the specified header.
Exceptions:
java.lang.IllegalArgumentException is thrown if the specified header is a system header.
java.lang.NullPointerException is thrown if either the name or value is null.

setAddressHeader
void setAddressHeader(java.lang.String name,
                      Address addr)
The method sets a SIP header to the specified Address value. This method is used for headers that can contain address values, such as Contact and Route. If the header already exists, its previous value is replaced with the new Address.
This method supports both long and compact forms of SIP header names, treating them as equivalent.
Parameters:
name: The name of the header field, specified in either long or compact form.
addr: The Address object to assign as the value of the header.
Exceptions:
java.lang.IllegalArgumentException is thrown if the specified header is not designed to hold address values, or the specified header is a system header.

setParameterableHeader
void setParameterableHeader(java.lang.String name,
                            Parameterable param)
The method sets the specified SIP header to the given Parameterable value. It is used for headers that support parameterized values, such as Event and Via. This method replaces any existing value of the specified header with the provided Parameterable.
This method accepts both long and compact forms of SIP header names.
Parameters:
name: The name of the header field, specified in either long or compact form.
param: The Parameterable object to assign as the value of the header.
Exceptions:
java.lang.IllegalArgumentException is thrown if the specified header is not designed to hold Parameterable values or the specified header is a system header.

setHeaderForm
void setHeaderForm(SipServletMessage.HeaderForm form)
The method configures the SIP message to represent its headers either in compact form or long form. The selected format applies to all headers in the message, ensuring consistency. If DEFAULT is selected, headers can mix both compact and long forms, depending on how they are added individually.
This method is useful for controlling the header representation when interoperability with other SIP entities is a concern.
To individually control the format of each header (by specifying its compact or long name) during header addition, use HeaderForm.DEFAULT.
Parameters:
form: The desired header format, which can be one of:

• HeaderForm.COMPACT: Use compact names for headers (e.g., m for Contact, v for Via).
• HeaderForm.LONG: Use long names for headers (e.g., Contact, Via).
• HeaderForm.DEFAULT: Allows a mix of compact and long names based on how headers are added. 

removeHeader
void removeHeader(java.lang.String name)
The method removes all instances of the specified header from the SIP message. It applies to headers that are not considered system headers, allowing applications to modify message content dynamically by eliminating unnecessary or unwanted headers.
This method supports both long and compact forms of SIP header names.
Parameters:
name: The name of the header to remove, specified in either its long or compact form.
Exceptions:
java.lang.IllegalArgumentException is thrown if the specified header is a system header.

getHeader
java.lang.String getHeader(java.lang.String name)
The method retrieves the value of the specified SIP header as a string. It returns the value of the first instance of the header if multiple instances exist. The method treats header names case-insensitively and supports both long and compact forms of header names.
Parameters:
name: The name of the header to retrieve, specified in either its long or compact form.
Returns:
The value of the specified header as a string. Returns null if the message does not include a header with the specified name. Returns an empty string if the header exists but has no value.
Exceptions:
java.lang.NullPointerException is thrown if the provided name is null.

getHeaders
java.util.ListIterator<java.lang.String> getHeaders(java.lang.String name)
The method retrieves all values of the specified SIP header as a ListIterator of String objects. The values in the ListIterator are returned in the order they appear in the SIP message. This method allows access to multiple headers with the same name, which is common for headers like Accept-Language or Contact.
Both long and compact header names are supported, and header names are case-insensitive.
Parameters:
name: The name of the header to retrieve, specified in either its long or compact form.
Returns:
A ListIterator containing the values of the specified header. Returns an empty iterator if the header is not present in the SIP message. Returns an iterator over empty strings if the header exists but has no values.
Exceptions:
java.lang.NullPointerException is thrown if the name parameter is null.

getHeaderNames
java.util.Iterator<java.lang.String> getHeaderNames()
The method returns an Iterator over the names of all header fields present in the SIP message. This method provides a convenient way to enumerate all headers in the message, whether they are standard or custom headers. If the message has no headers, the method returns an empty iterator. However, some servlet containers may restrict access to headers using this method. In such cases, the method returns null.
Returns:
An iterator containing all header names present in the message. Returns an empty iterator if the message has no headers. Returns null if the servlet container restricts access to header names.
Exceptions:
ConcurrentModificationException is thrown if the underlying data structure is modified after the iterator is created, as this is a fail-fast iterator.

getHeaderForm
SipServletMessage.HeaderForm getHeaderForm()
The method retrieves the current header form of the SIP message. The header form determines whether headers in the message are represented in compact form, long form, or a default mixed form. By default, the header form is SipServletMessage.HeaderForm.DEFAULT.
Returns:
The current header form of the SIP message, which can be one of:

• HeaderForm.COMPACT: Headers are represented in compact form (e.g., m for Contact).
• HeaderForm.LONG: Headers are represented in long form (e.g., Contact).
• HeaderForm.DEFAULT: Allows a mix of compact and long forms based on how headers are added.

getAddressHeader
Address getAddressHeader(java.lang.String name)
                         throws ServletParseException
The method retrieves the value of the specified SIP header as an Address object. This method is used for headers that contain address information, such as Contact and Route. If the header contains multiple values, this method returns the first value. Supports both long and compact forms of SIP header names.
Parameters:
name: A case-insensitive string specifying the name of the header, in either its long or compact form.
Returns:
The value of the specified header as an Address object. Returns the first value if the header contains multiple entries.
Exceptions:
ServletParseException is thrown if the specified header cannot be parsed as a valid SIP address object.
NullPointerException is thrown if the name parameter is null.

getAddressHeaders
java.util.ListIterator<Address> getAddressHeaders(java.lang.String name)
                                                  throws ServletParseException
The method returns a ListIterator over all Address header field values for the specified header. The iterator returns values in the order they appear in the SIP message. The method supports headers containing address values, such as Contact and Route, in both long and compact forms. This method handles cases where no headers are present, returning an empty iterator, or where headers exist with no values, returning an iterator over empty strings. The iterator is fail-fast and prevents modifications to system headers. For non-system headers, the iterator allows adding or setting Address objects.
Parameters:
name: A case-insensitive string specifying the name of the header field, in either long or compact form.
Returns:
A ListIterator containing all Address values for the specified header.
Exceptions:
ServletParseException is thrown if the header field cannot be parsed as a valid SIP address object.
NullPointerException is thrown if the name parameter is null.

getParameterableHeader
Parameterable getParameterableHeader(java.lang.String name)
                                     throws ServletParseException
The method retrieves the value of a specified SIP header as a Parameterable object. This is useful for headers that contain parameterized values, such as Event and Via, which conform to the format field-value *(;parameter-name=parameter-value) as defined in RFC 3261.
If the header contains multiple values, the method returns the first value. The method supports both long and compact forms of SIP header names.
Parameters:
name: A case-insensitive string specifying the name of the header, either in its long or compact form.
Returns:
The parsed value of the specified header as a Parameterable object.
Exceptions:
ServletParseException is thrown if the specified header field cannot be parsed into a valid SIP Parameterable object.
NullPointerException is thrown if the name parameter is null.

getParameterableHeaders
java.util.ListIterator<? extends Parameterable> getParameterableHeaders(java.lang.String name)
                                                                        throws ServletParseException
The method retrieves all values of a specified SIP header as a ListIterator of Parameterable objects. The iterator returns the header values in the order they appear in the SIP message. This method is useful for headers that support parameterized values, such as Event and Via, which conform to the format field-value *(;parameter-name=parameter-value) as defined in RFC 3261.
If no headers with the specified name are present, the method returns an empty iterator. If headers exist but have no values, it returns an iterator over empty strings.
The iterator prevents modification of system headers and enforces that any additions or updates involve Parameterable objects for non-system headers.
Parameters:
name: A case-insensitive string specifying the name of the header field, either in its long or compact form.
Returns:
A ListIterator containing the Parameterable values of the specified header field.
Exceptions:
ServletParseException is thrown if the specified header field cannot be parsed into valid SIP Parameterable objects.
NullPointerException is thrown if the name parameter is null.

Content Management

getContent
java.lang.Object getContent()
                            throws java.io.IOException,
                                   java.io.UnsupportedEncodingException
The getContent method retrieves the content of the SIP message as a Java object. The type of the returned object depends on the MIME type of the message's content (Content-Type header):

• Textual MIME types (e.g., text/plain): Returns a String object.
• Multipart MIME types (e.g., multipart/*): Encouraged to return a javax.mail.Multipart object.
• Unknown MIME types: Returns a byte[] object containing the raw content.

If the content includes character data, the message's character encoding is used for interpretation. This method is modeled after the JavaMail API's getContent, but the SIP servlet API does not require the use of the Java Activation Framework (JAF).
Returns:
The parsed content of the SIP message:

• String for textual MIME types.
• javax.mail.Multipart for multipart MIME types (if supported).
• byte[] for unknown MIME types.

Exceptions:
java.io.IOException is thrown if an I/O error occurs while retrieving the content.
java.io.UnsupportedEncodingException is thrown if the content is textual and the message's character encoding is unsupported by the platform.

getContentType
java.lang.String getContentType()
The method retrieves the value of the Content-Type header field of the SIP message. This value represents the MIME type of the message content, indicating how the content should be interpreted.
Returns:
The MIME type of the message (e.g., text/plain, application/sdp). Returns null if the message body is empty and there is no Content-Type header.

getCharacterEncoding
java.lang.String getCharacterEncoding()
The method retrieves the character encoding used for the MIME body of the SIP message. This encoding is used for converting between bytes and characters. If no character encoding is explicitly specified in the message, the default encoding UTF-8 is used. If the message does not specify a character encoding, the method returns null.
Returns:
The name of the charset used for the MIME body (e.g., UTF-8, ISO-8859-1). Returns null if the message does not specify a character encoding.

getContentLanguage
java.util.Locale getContentLanguage()
The method retrieves the locale of the SIP message, as specified by the Content-Language header. This locale indicates the natural language of the message content.
If the Content-Language header is not present in the message, the method returns null.
Returns:
The Locale object representing the language of the message content. Returns null if the Content-Language header is not present.

getContentLength
int getContentLength()
The method retrieves the length of the SIP message body in bytes. This value is directly derived from the Content-Length header of the message.
Returns:
The length of the message body in bytes.

getRawContent
byte[] getRawContent()
                     throws java.io.IOException
The method retrieves the raw content of the SIP message as a byte array. This method provides direct access to the content in its unprocessed form. If the content is not set, the method returns null.
To avoid unintended modifications, applications should create a copy of the returned byte array before reusing it for another message.
Returns:
The raw message content as a byte array. Returns null if no content is set.
Exception:
java.io.IOException is thrown if an I/O error occurs while retrieving the content.

setContent
void setContent(java.lang.Object content,
                java.lang.String contentType)
                throws java.io.UnsupportedEncodingException
The method sets the content of the SIP message to the specified object with the given MIME type (Content-Type). The behavior of this method depends on the type of the content object and the associated contentType:

• byte[] Content: Containers must handle this for any MIME type.
• String Content: Containers must handle this for text/* MIME types, using the message's character encoding if applicable.
• Other Objects: Containers may handle javax.mail.Multipart for multipart MIME types or invoke toString() for non-String objects with text/* MIME types.

This method works only if the container recognizes the combination of the object type and the MIME type. The message's character encoding is used when converting textual content to bytes.
Parameters:
content: The content object to set for the message (e.g., byte[], String, or javax.mail.Multipart).
contentType: The MIME type of the content (e.g., text/plain, application/sdp).
Exceptions:
java.io.UnsupportedEncodingException is thrown if the content is textual, and the message's character encoding is unsupported by the server.
java.lang.IllegalArgumentException is thrown if the container does not know how to serialize the provided content for the specified MIME type.
java.lang.IllegalStateException is thrown if the message has already been sent or is in a read-only state.

setContentType
void setContentType(java.lang.String type)
The method sets the Content-Type header for the SIP message. This specifies the MIME type of the message body and may include the character encoding used (e.g., text/html; charset=UTF-8). Setting the content type also updates the message's character encoding. To ensure proper behavior, this method should be called before obtaining a PrintWriter or invoking setContent.
Parameters:
type: The MIME type of the content (e.g., text/plain, application/sdp, or text/html; charset=UTF-8).

setCharacterEncoding
void setCharacterEncoding(java.lang.String enc)
                          throws java.io.UnsupportedEncodingException
The method sets the character encoding for the SIP message. This encoding is used to convert the message body between bytes and characters. Setting the encoding may impact the behavior of subsequent calls to getContent() and setContent(java.lang.Object, java.lang.String). To ensure proper functionality, this method must be called before invoking getContent() or setContent().
Parameters:
enc: The name of the character encoding to be used (e.g., UTF-8, ISO-8859-1).
Exceptions:
java.io.UnsupportedEncodingException is thrown if the specified encoding is not valid or unsupported by the platform.

setContentLanguage
void setContentLanguage(java.util.Locale locale)
The method sets the locale of the SIP message, updating the Content-Language header and the charset parameter in the Content-Type header, if applicable. This indicates the natural language and character set of the message content. This method should be invoked before calling setContent to ensure the headers are correctly configured.
Parameters:
locale: The locale of the message (e.g., Locale.ENGLISH, Locale.FRENCH).

setContentLength
void setContentLength(int len)
The method sets the value of the Content-Length header for the SIP message. This header indicates the length of the message body in bytes. Applications are discouraged from using this method directly. Instead, they should use the setContent methods, which automatically compute and set the Content-Length header correctly.
Parameters:
len: The length of the content in bytes, to be set in the Content-Length header.
Exceptions:
java.lang.IllegalStateException is thrown if the method is called on an incoming message or a message that has already been sent.

Session and Application Context Management

getApplicationSession
SipApplicationSession getApplicationSession(boolean create)getApplicationSession(boolean create)
The method retrieves the SipApplicationSession associated with the SIP message. This session represents the context within which the message is processed. If no session exists and the create parameter is true, a new session is created. If create is false and no session exists, the method returns null.
Parameters:
create: If true, creates a new session if none exists; if false, returns null if no session exists.
Returns:
The application session associated with the message. Returns null if no session exists and create is false.

getSession
SipSession getSession()
The method retrieves the SipSession associated with the SIP message. If the session does not already exist, it is created. This method is equivalent to calling getSession(true).
Returns:
The session associated with the SIP message. If no session exists, a new one is created.

getSession
SipSession getSession(boolean create)
The method retrieves the SipSession associated with the SIP message. If no session exists, the create parameter determines whether a new session is created or null is returned.
Parameters:
create: If true, creates a new session if none exists; if false, returns null if no session exists.
Returns:
The session associated with the SIP message. Returns null if no session exists and create is false.

Attributes Management

getAttribute
java.lang.Object getAttribute(java.lang.String name)
The method retrieves the value of a named attribute associated with the SIP message. Attributes can be set either by the servlet container to provide additional information (e.g., HTTPS certificate details) or programmatically using setAttribute. If no attribute with the specified name exists, the method returns null.
Attributes should follow package naming conventions. Names beginning with javax.servlet.sip.* are reserved for use by the SIP Servlet API.
Parameters:
name: The name of the attribute to retrieve.
Returns:
The value of the attribute as an Object, or null if the attribute does not exist.
Exceptions:
java.lang.NullPointerException is thrown if the name parameter is null.

getAttributeNames
java.util.Enumeration<java.lang.String> getAttributeNames()
The method retrieves an Enumeration of all attribute names available in the SIP message. If no attributes are associated with the message, the method returns an empty Enumeration.
Returns:
An Enumeration of strings representing the names of the attributes in the message. Returns an empty Enumeration if no attributes are available.

setAttribute
void setAttribute(java.lang.String name,
                  java.lang.Object o)
The method stores an attribute in the SIP message, associating the specified name with the provided object. Attributes are reset between messages and do not persist. This method is commonly used to embed information in a message for later retrieval, often in conjunction with a RequestDispatcher.
Attribute names should adhere to package naming conventions. Names beginning with javax.servlet.sip.* are reserved for use by the SIP Servlet API.
Parameters:
name: The name of the attribute to store.
o: The object to associate with the specified attribute name.
Exception:
java.lang.NullPointerException is thrown if either the name or o parameter is null.

removeAttribute
void removeAttribute(java.lang.String name)
The method removes the attribute with the specified name from the SIP message. If the attribute does not exist, no action is taken.
Attribute names should conform to package naming conventions, and names starting with javax.servlet.sip.* are reserved for SIP Servlet API use.
Parameters:
name: The name of the attribute to be removed.
Exception:
java.lang.NullPointerException is thrown if the name parameter is null.

Message Properties and Identification

getCallId
java.lang.String getCallId()
The method retrieves the value of the Call-ID header from the SIP message. The Call-ID identifies the SIP dialog or transaction associated with the message.
Returns:
The value of the Call-ID header in the SIP message.

getMethod
java.lang.String getMethod()
The method retrieves the SIP method associated with the message. For requests, the method is extracted from the request line, while for responses, it is determined from the CSeq header. SIP methods are represented as uppercase tokens (INVITE, BYE).
Returns:
The SIP method of the SipServletMessage (e.g., INVITE, ACK, BYE).

getProtocol
java.lang.String getProtocol()
The method retrieves the name and version of the protocol used in the SIP message. The format of the returned string is <protocol>/<major-version-number>.<minor-version-number> (e.g., SIP/2.0). 
Returns:
A string representing the protocol name and version.

getExpires
int getExpires()
The method retrieves the value of the Expires header from the SIP message. The Expires header indicates the relative time (in seconds) after which the message or its content expires.
Returns:
The value of the Expires header in seconds. Returns -1 if the Expires header does not exist.

setExpires
void setExpires(int seconds)
The method sets the value of the Expires header in the SIP message. The value represents the relative time, in seconds, after which the message or its content expires. This method is equivalent to calling setHeader("Expires", String.valueOf(seconds)).
Parameters:
seconds: The value of the Expires header in seconds.

getFrom
Address getFrom()
The method retrieves the value of the From header from the SIP message. This header specifies the logical identity of the sender of the message.
Returns:
The internal representation of the From header.

getTo
Address getTo()
The method retrieves the value of the To header from the SIP message. This header specifies the intended recipient of the message.
Returns:
The internal representation of the To header.

Network and Transport Information

getRemoteAddr
java.lang.String getRemoteAddr()
The method retrieves the IP address of the next upstream or downstream hop from which the SIP message was received. For messages routed internally within the same container, it returns the address of the container's SIP interface. If the message was locally generated, the method returns null.
Returns:
The IP address of the sender of the message. Returns null if the message was locally generated.

getRemotePort
int getRemotePort()
The method retrieves the port number of the next upstream or downstream hop from which the SIP message was received. For messages routed internally within the same container, it returns a valid port number chosen by the container or the host TCP/IP stack. If the message was locally generated, the method returns -1.
Returns:
The port number of the sender of the message. Returns -1 if the message was locally generated.

getInitialRemoteAddr
java.lang.String getInitialRemoteAddr()
The method retrieves the IP address of the upstream or downstream hop from which the SIP message was initially received by the container. Unlike getRemoteAddr(), this method returns the same value for all applications in the same application composition chain, as determined by the application router.
Returns:
The IP address of the sender from which the message was initially received. Returns null if the message was locally generated.

getInitialRemotePort
int getInitialRemotePort()
The method retrieves the port number of the upstream or downstream hop from which the SIP message was initially received by the container. Unlike getRemotePort(), this method returns the same value for all applications in the same application composition chain, as determined by the application router.
Returns:
The port number of the sender from which the message was initially received. Returns -1 if the message was locally generated.

getInitialTransport
java.lang.String getInitialTransport()
The method retrieves the name of the transport protocol (e.g., "UDP", "TCP", "TLS", or "SCTP") used to initially receive the SIP message by the container. This value is consistent across all applications in the same application composition chain.
Returns:
The name of the transport protocol with which the message was initially received. Returns null if the message was locally generated.

getLocalAddr
java.lang.String getLocalAddr()
The method retrieves the IP address of the local interface on which the SIP message was received.
Returns:
The IP address of the local interface where the message was received. Returns null if the message was locally generated.

getLocalPort
int getLocalPort()
The method retrieves the local port number on which the SIP message was received.
Returns:
The local port number where the message was received. Returns -1 if the message was locally generated.

getTransport
java.lang.String getTransport()
The method retrieves the name of the transport protocol (e.g., "UDP", "TCP", "TLS", or "SCTP") used to receive the SIP message.
Returns:
The name of the transport protocol with which the message was received. Returns null, if the message was locally generated.

Security and Role Management

getRemoteUser
java.lang.String getRemoteUser()
The method retrieves the login of the user who sent the SIP message, if the user has been authenticated. If the user is not authenticated, the method returns null.
Returns:
The login of the user sending the message. Returns null if the user has not been authenticated.

getUserPrincipal
java.security.Principal getUserPrincipal()
The method retrieves a java.security.Principal object representing the authenticated user agent that sent the SIP message. If the user agent is not authenticated, the method returns null.
Returns:
A Principal object representing the name of the authenticated user. Returns null if the user has not been authenticated.

Role Management

isUserInRole
boolean isUserInRole(java.lang.String role)
The method checks whether the authenticated user sending the SIP message belongs to the specified logical "role". Roles and role memberships are defined in the deployment descriptor. If the user has not been authenticated, the method returns false.
Parameters:
role: The name of the role to check.
Returns:
true, if the authenticated user belongs to the specified role. false, if the user does not belong to the role or has not been authenticated.

isSecure
boolean isSecure()
The isSecure method checks whether the SIP message was received over a secure channel, such as TLS.
Returns:
true, if the message was received over a secure channel, false otherwise.

Language Preferences

addAcceptLanguage
void addAcceptLanguage(java.util.Locale locale)
The method adds a locale to the Accept-Language header of the SIP message. The specified locale is considered acceptable to the user agent, but it will have a lower priority (q-value) compared to any locales already listed in the Accept-Language header.
Parameters:
locale: A locale acceptable to the user agent.

getAcceptLanguage
java.util.Locale getAcceptLanguage()
The method retrieves the preferred Locale specified in the Accept-Language header of the SIP message. This Locale represents the language that the originating user agent (UA) prefers for the message content. If the Accept-Language header is not present, the method returns null.
Returns:
The preferred Locale for the sending user agent. Returns null if the Accept-Language header is not included in the message.
Note:
Unlike version 1.0 of the API, this method now returns null instead of the server's default locale when the Accept-Language header is absent.

getAcceptLanguages
java.util.Iterator<java.util.Locale> getAcceptLanguages()
The method retrieves an Iterator over Locale objects that represent the languages acceptable to the user agent (UA) sending the SIP message. The locales are listed in decreasing order of preference, as specified in the Accept-Language header. If the Accept-Language header is not present, the method returns an empty Iterator. The first locale in the iterator has the highest preference.
Returns:
An Iterator containing the preferred locales of the originating user agent. Returns an empty Iterator if the Accept-Language header is not provided.
Note:
In version 1.0 of the API, the method would return an Iterator containing the server's default locale if the Accept-Language header was absent. In the current version, it returns an empty Iterator instead.

setAcceptLanguage
void setAcceptLanguage(java.util.Locale locale)
The method sets the preferred Locale for the SIP message's user agent. This preference specifies the language the UA will accept for content, reason phrases, warnings, etc., and it is included in the Accept-Language header. Passing a null value removes any existing Accept-Language headers from the message.
Parameters:
locale: The preferred Locale for the user agent. A null value removes existing Accept-Language headers.

Sending and Transaction Control

send
void send()
          throws java.io.IOException
The method transmits the SipServletMessage. It ensures the message is sent over the appropriate transport channel as part of the underlying SIP transaction.
Exceptions:
java.io.IOException is thrown if a transport error occurs while attempting to send the message.
java.lang.IllegalStateException is thrown if the message cannot be sent due to the current state of the underlying SIP transaction.

isCommitted
boolean isCommitted()
The method checks if the SipServletMessage has been committed. A message is considered committed if it meets any of the following conditions:

• Incoming Request: A final response has already been generated.
• Outgoing Request: The request has already been sent.
• Incoming Non-Reliable Provisional Response: Received by a servlet acting as a UAC (User Agent Client).
• Incoming Reliable Provisional Response: For which PRACK has already been generated (applies to containers supporting the 100rel extension).
• Incoming Final Response (Non-INVITE): Received by a servlet acting as a UAC for a Non-INVITE transaction.
• Outgoing Response: The response has been forwarded upstream.
• Incoming Final Response to INVITE: An ACK has already been generated.
• Outgoing Request Timeout: The client transaction has timed out, no response was received, and the container has generated a 408 response locally.

Returns:
true, if the message is committed, false otherwise.