javax.servlet.sip
Interface SipServletMessage

All Known Subinterfaces:

SipServletRequest, SipServletResponse

public interface SipServletMessage

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 socalled "system" headers. These are header fields that the servlet container manages: From, To, Call-ID, CSeq, Via, Route (except through pushRoute), Record-Route. Contact is a system header field in messages other than REGISTER requests and responses, as well as 3xx and 485 responses. Additionally, for containers implementing the reliable provisional responses extension, RAck and RSeq are considered system headers also.

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.

Method Summary

void	addAcceptLanguage(java.util.Locale locale) Adds an acceptable Locale of this user agent.
void	addAddressHeader(java.lang.String name, Address addr, boolean first) Adds the specified Address as a new value of the named header field.
void	addHeader(java.lang.String name, java.lang.String value) Adds a header with the given name and value.
java.util.Locale	getAcceptLanguage() Returns the preferred Locale that the UA originating this message will accept content in, based on the Accept-Language header.
java.util.Iterator	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.
Address	getAddressHeader(java.lang.String name) Returns the value of the specified header as a Address object.
java.util.ListIterator	getAddressHeaders(java.lang.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.
java.lang.Object	getAttribute(java.lang.String name) Returns the value of the named attribute as an Object, or null if no attribute of the given name exists.
java.util.Enumeration	getAttributeNames() Returns an Enumeration containing the names of the attributes available to this message object.
java.lang.String	getCallId() Returns the value of the Call-ID header in this SipServletMessage.
java.lang.String	getCharacterEncoding() Returns the name of the charset used for the MIME body sent in this message.
java.lang.Object	getContent() Returns the content as a Java object.
java.util.Locale	getContentLanguage() Returns the locale of this message.
int	getContentLength() Returns the length in number of bytes of the content part of this message.
java.lang.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.
java.lang.String	getHeader(java.lang.String name) Returns the value of the specified request header as a String.
java.util.Iterator	getHeaderNames() Returns an Iterator over all the header names this request contains.
java.util.ListIterator	getHeaders(java.lang.String name) Returns all the values of the specified request header as an Iterator over a number of String objects.
java.lang.String	getLocalAddr() Returns the domain name or IP address of the interface this message was received on.
int	getLocalPort() Returns the local port this message was received on.
java.lang.String	getMethod() Returns the SIP method of this message.
java.lang.String	getProtocol() Returns the name and version of the protocol of this message.
byte[]	getRawContent() Returns message content as a byte array.
java.lang.String	getRemoteAddr() Returns the IP address of the sender of this message.
int	getRemotePort() Returns the port number of the sender of this message.
java.lang.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.
Address	getTo() Returns the value of the To header.
java.lang.String	getTransport() Returns the name of the protocol with which this message was received, e.g.
java.security.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.
boolean	isSecure() Returns a boolean indicating whether this message was received over a secure channel, such as TLS.
boolean	isUserInRole(java.lang.String role) Returns a boolean indicating whether the authenticated user is included in the specified logical "role".
void	removeHeader(java.lang.String name) Removes the specified header.
void	send() Sends this SipServletMessage.
void	setAcceptLanguage(java.util.Locale locale) Sets the preferred Locale that this user agent will accept content, reason phrases, warnings, etc.
void	setAddressHeader(java.lang.String name, Address addr) Sets the header with the specified name to have the value specified by the address argument.
void	setAttribute(java.lang.String name, java.lang.Object o) Stores an attribute in this message.
void	setCharacterEncoding(java.lang.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(java.lang.Object content, java.lang.String contentType) Sets the content of this message to the specified Object.
void	setContentLanguage(java.util.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(java.lang.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(java.lang.String name, java.lang.String value) Sets a header with the given name and value.

Method Detail

getFrom

public Address getFrom()

Returns the value of the From header.

Returns:

internal representation of the From header

getTo

public Address getTo()

Returns the value of the To header.

Returns:

internal representation of the To header

getMethod

public java.lang.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

public java.lang.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

public java.lang.String getHeader(java.lang.String name)

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

Parameters:

name - a String specifying the header name

Returns:

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

getHeaders

public java.util.ListIterator getHeaders(java.lang.String name)

Returns all the values of the specified request header as an Iterator over a number of String objects.

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 request did not include any headers of the specified name, this method returns an empty Iterator. The header name is case insensitive.

Parameters:

name - a String specifying the header name

Returns:

a ListIterator over the String values of the specified header field

getHeaderNames

public java.util.Iterator getHeaderNames()

Returns an Iterator over all the header names this request contains. If the request has no headers, this method returns an empty Iterator.

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 request; if the request has no header fields, an empty enumeration; if the servlet container does not allow servlets to use this method, null

setHeader

public void setHeader(java.lang.String name,
                      java.lang.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.

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

value - the header value

Throws:

java.lang.IllegalArgumentException - if the specified header field is a system header

addHeader

public void addHeader(java.lang.String name,
                      java.lang.String value)

Adds a header with the given name and value. This method allows headers to have multiple values.

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

value - the additional header value

Throws:

java.lang.IllegalArgumentException - if the specified header field is a system header

removeHeader

public void removeHeader(java.lang.String name)

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

Parameters:

name - a String specifying the header name

Throws:

java.lang.IllegalArgumentException - if the specified header field is a system header

getAddressHeader

public Address getAddressHeader(java.lang.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.

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

Returns:

value of the header as an Address

Throws:

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

getAddressHeaders

public java.util.ListIterator getAddressHeaders(java.lang.String name)
                                         throws ServletParseException

Returns a ListIterator over all Address header field values for the specified 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.

Attempts to modify the specified header field through the returned list iterator must fail with an IllegalStateException 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.

Parameters:

name - a case insensitive String specifying the name of the header field

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

setAddressHeader

public void setAddressHeader(java.lang.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.

Parameters:

name - the name of the header to set

addr - the assigned address value

Throws:

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

addAddressHeader

public void addAddressHeader(java.lang.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.

Parameters:

name - the 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:

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

getCallId

public java.lang.String getCallId()

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

Returns:

the Call-ID value of this SipServletMessage

getExpires

public 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

public 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

public java.lang.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

public void setCharacterEncoding(java.lang.String enc)
                          throws java.io.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:

java.io.UnsupportedEncodingException - if this is not a valid encoding

getContentLength

public 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 request body

getContentType

public java.lang.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

public byte[] getRawContent()
                     throws java.io.IOException

Returns message content as a byte array.

Returns:

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

Throws:

java.io.IOException - if an IOException occurred

getContent

public java.lang.Object getContent()
                            throws java.io.IOException,
                                   java.io.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:

java.io.IOException - if an IOException occurred

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

setContent

public void setContent(java.lang.Object content,
                       java.lang.String contentType)
                throws java.io.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 requried 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:

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

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

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

setContentLength

public 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:

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

setContentType

public void setContentType(java.lang.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

getAttribute

public java.lang.Object getAttribute(java.lang.String name)

Returns the value of the named attribute as an Object, or null if no attribute of the given name exists.

Attributes can be set two ways. The servlet container may set attributes to make available custom information about a request or a response. For example, for requests made using HTTPS, the attribute javax.servlet.request.X509Certificate can be used to retrieve information on the certificate of the client. Attributes can also be set programatically using setAttribute(String, Object). This allows information to be embedded into a request or response before a RequestDispatcher call.

Attribute names should follow the same conventions as package names. Names beginning with javax.servlet.sip. are reserved for definition by the SIP Servlet API.

Parameters:

name - a String specifying the name of the attribute

Returns:

an Object containing the value of the attribute, or null if the attribute does not exist

getAttributeNames

public java.util.Enumeration getAttributeNames()

Returns an Enumeration containing the names of the attributes available to this message object. This method returns an empty Enumeration if the request has no attributes available to it.

Returns:

an Enumeration of strings containing the names of the request's attributes

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.Object o)

Stores an attribute in this message. Attributes are reset between messages. This method is most often used in conjunction with RequestDispatcher.

Attribute names should follow the same conventions as package names. Names beginning with javax.servlet.sip.* are reserved for definition by the SIP Servlet API.

Parameters:

name - a String specifying the name of the attribute

o - the Object to be stored

getSession

public 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

public 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

public 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

public 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

public java.util.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 the default locale for the server.

Returns:

the preferred Locale for the sending user agent

getAcceptLanguages

public java.util.Iterator 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 Iterator containing one Locale, the default locale for the server.

Returns:

an Iterator over preferred locales for the UA originating this message

setAcceptLanguage

public void setAcceptLanguage(java.util.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

public void addAcceptLanguage(java.util.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

public void setContentLanguage(java.util.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

public java.util.Locale getContentLanguage()

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

Returns:

Locale of this message

send

public void send()
          throws java.io.IOException

Sends this SipServletMessage.

Throws:

java.io.IOException - if a transport error occurs when trying to send this request

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

isSecure

public 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

public 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 response received by a servlet acting as a UAC
• This message is a response which has already been forwarded upstream

Returns:

true if this message is committed, false otherwise

getRemoteUser

public java.lang.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 making this request, or null if the user has not been authenticated

isUserInRole

public boolean isUserInRole(java.lang.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

public java.security.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

getLocalAddr

public java.lang.String getLocalAddr()

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

Returns:

name of local interface this message was received on, or null if it was locally generated.

getLocalPort

public int getLocalPort()

Returns the local port this message was received on.

Returns:

local port on which this message was received, or -1 if it was locally generated.

getRemoteAddr

public java.lang.String getRemoteAddr()

Returns the IP address of the sender of this message.

Returns:

a String containing the IP address of the sender of this message, or null if it was locally generated

getRemotePort

public int getRemotePort()

Returns the port number of the sender of this message.

Returns:

the port number of the sender of this message, or -1 if it was locally generated.

getTransport

public java.lang.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 it was locally generated.