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.

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.

A SipServletMessage is committed if one of the following conditions is true:

Containers may throw IllegalStateExceptions when servlets attempt to modify an already committed SipServletMessage.


Method Summary
 void addAcceptLanguage(java.util.Locale locale)
          Adds an acceptable Locale of this user agent.
 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 Enumeration 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.
 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 getCharacterEncoding()
          Returns the name of the charset used for the MIME body sent in this message.
 java.util.List getContacts()
          Returns the value of the Contact headers.
 java.lang.Object getContent()
          Return 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.
 SipAddress 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 enumeration of all the header names this request contains.
 java.util.Iterator getHeaders(java.lang.String name)
          Returns all the values of the specified request header as an Iterator over a number of String objects.
 javax.servlet.ServletInputStream getInputStream()
          Retrieves the body of the request as binary data using a ServletInputStream.
 int getMaxForwards()
          Returns the value of the Max-Forwards header.
 java.lang.String getMethod()
          Returns the SIP method of this message.
 javax.servlet.ServletOutputStream getOutputStream()
          Returns a ServletOutputStream suitable for writing binary data in the response.
 java.lang.String getProtocol()
          Returns the name and version of the protocol of this message.
 Proxy getProxy()
          Returns the Proxy object associated with this request.
 byte[] getRawContent()
          Returns message content as a byte array.
 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.
 SipAddress getTo()
          Returns the value of the To header.
 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, meaning it should not be modified.
 boolean isRequestedSessionIdValid()
          Checks whether the requested session ID is still valid.
 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 setAttribute(java.lang.String name, java.lang.Object o)
          Stores an attribute in this message.
 void setContacts(java.util.List contacts)
          Sets the value of the Contact header.
 void setContent(java.lang.Object obj, java.lang.String type)
          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 (including 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.
 void setMaxForwards(int n)
          Sets the value of the Max-Forwards header.
 

Method Detail

getFrom

public SipAddress getFrom()
Returns the value of the From header.
Returns:
internal representation of the From header

getTo

public SipAddress getTo()
Returns the value of the To header.
Returns:
internal representation of the To header

getContacts

public java.util.List getContacts()
Returns the value of the Contact headers.
Returns:
a List of Contact objects, or null if this message contains no Contact header

setContacts

public void setContacts(java.util.List contacts)
Sets the value of the Contact header.
Parameters:
contacts - a List of Contact objects
Throws:
java.lang.IllegalArgumentException - if the contacts list contains a non-Contact object.

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.Iterator 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:
an Iterator over the String header names of this message

getHeaderNames

public java.util.Iterator getHeaderNames()
Returns an enumeration of 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 do not allow servlets to access headers using this method, in which case this method returns null.

Returns:
an enumeration of all the header names sent with this request; if the request has no headers, 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 under Contact.

Parameters:
name - a String specifying the header name
value - the header value

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 under Contact.

Parameters:
name - a String specifying the header name
value - the additional header value

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

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.
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

getMaxForwards

public int getMaxForwards()
Returns the value of the Max-Forwards header.
Returns:
the value of the Max-Forwards header, or -1 if there is no such header in this message

setMaxForwards

public void setMaxForwards(int n)
Sets the value of the Max-Forwards header. Max-Forwards serves to limit the number of hops a request can make on the way to its destination. It consists of an integer that is decremented by one at each hop.

This method is equivalent to:

   setHeader("Max-Forwards", String.valueOf(n));
 
Parameters:
n - new value of the Max-Forwards header
Throws:
java.lang.IllegalArgumentException - if the argument is not in the range 0 to 255

getCharacterEncoding

public java.lang.String getCharacterEncoding()

Returns the name of the charset used for the MIME body sent in this message.

If no charset has been assigned, it is implicitly set to ISO-8859-1 (Latin-1).

See RFC 2047 (http://ds.internic.net/rfc/rfc2045.txt) for more information about character encoding and MIME.

Returns:
a String specifying the name of the charset, for example, ISO-8859-1

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

getContent

public java.lang.Object getContent()
                            throws java.io.IOException
Return the content as a Java object. The type of the returned object is of course dependent on the content itself. For example, the object returned for "text/plain" content is usually a String object.

It is encouraged that the object returned for "multipart" MIME content is a javax.mail.Multipart object. For content-types that are unknown to the servlet engine, an input stream is returned as the content.

Note: This method, as well as the setContent methods, 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 an InputStream if the MIME type isn't known to the platform
Throws:
java.io.IOException - if an IOException occurred

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

setContent

public void setContent(java.lang.Object obj,
                       java.lang.String type)
Sets the content of this message to the specified Object.

This method only works if the implementation "knows about" the specified object and MIME types. As for getContent() it is strongly recommended that implementations at least know how to handle javax.mail.Multipart and "multipart" MIME types, and String and "text/plain".

Note: This method together with getContent() are 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.

Parameters:
obj - an object representing the message content
type - MIME type of the object
Throws:
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

getInputStream

public javax.servlet.ServletInputStream getInputStream()
                                                throws java.io.IOException
Retrieves the body of the request as binary data using a ServletInputStream.
Returns:
a ServletInputStream object containing the body of the request
Throws:
java.lang.IllegalStateException - if this message is committed
java.io.IOException - if an input or output exception occurred, specifically if an open input or output stream currently exists for this message

getOutputStream

public javax.servlet.ServletOutputStream getOutputStream()
                                                  throws java.io.IOException
Returns a ServletOutputStream suitable for writing binary data in the response. The servlet container does not encode the binary data.
Returns:
a ServletOutputStream for writing binary data
Throws:
java.lang.IllegalStateException - if this is an incoming message or if it has already been sent
java.io.IOException - if an input or output exception occurred, specifically if an open input or output stream currently exists for this message

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=ISO-8859-4.

If obtaining a PrintWriter, 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

isRequestedSessionIdValid

public boolean isRequestedSessionIdValid()
Checks whether the requested session ID is still valid.
Returns:
true if this request has an id for a valid session in the current session context; false otherwise

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 Enumeration 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 Enumeration containing one Locale, the default locale for the server.
Returns:
an Enumeration of 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 (including the Content-Type's charset) as appropriate. This method should be called before a call to getWriter. By default, the message locale is the default locale for the server.
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()
Sends this SipServletMessage.
Throws:
java.lang.IllegalStateException - if this message cannot legally be sent in the current state of the underlying SIP transaction

getProxy

public Proxy getProxy()
               throws TooManyHopsException
Returns the Proxy object associated with this request. A Proxy instance will be created if one doesn't already exist.

Note that the container must return the same Proxy instance whenever a servlet invokes getProxy on messages belonging to the same transaction. In particular, a response to a proxied request is associated with the same Proxy object as is the original request.

This method throws an IllegalStateException if the Proxy object didn't already exist and the transaction underlying this SIP message is in a state which doesn't allow proxying, for example if this is a SipServletRequest for which a final response has already been generated.

Throws:
TooManyHopsException - if invoked on a SipServletRequest which has a Max-Forwards header with value 0.
java.lang.IllegalStateException - if the transaction underlying this message isn't already associated with a Proxy object and its state disallows proxying to be initiated
See Also:
SipServletRequest.getProxy(boolean)

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, meaning it should not be modified.
Returns:
true if this message has been committed.

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