|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
A
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
.
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 |
public SipAddress getFrom()
public SipAddress getTo()
public java.util.List getContacts()
List
of Contact
objects, or null if
this message contains no Contact headerpublic void setContacts(java.util.List contacts)
contacts
- a List
of Contact
objectsjava.lang.IllegalArgumentException
- if the contacts list contains
a non-Contact
object.public java.lang.String getMethod()
SipServletMessage
public java.lang.String getProtocol()
For this version of the SIP Servlet API this is always "SIP/2.0".
String
containing the protocol name and
version numberpublic java.lang.String getHeader(java.lang.String name)
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.name
- a String
specifying the header nameString
containing the value of the
requested header, or null if the request does not have a
header of that namepublic 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.
name
- a String
specifying the header nameIterator
over the String
header names of this messagepublic java.util.Iterator getHeaderNames()
Some servlet containers do not allow do not allow servlets to access headers using this method, in which case this method returns null.
public void setHeader(java.lang.String name, java.lang.String value)
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
.
name
- a String
specifying the header namevalue
- the header valuepublic void addHeader(java.lang.String name, java.lang.String value)
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
.
name
- a String
specifying the header namevalue
- the additional header valuepublic void removeHeader(java.lang.String name)
name
- a String
specifying the header namepublic int getExpires()
public void setExpires(int seconds)
setHeader("Expires", String.valueOf(seconds));
seconds
- the value of the Expires header measured in secondspublic int getMaxForwards()
public void setMaxForwards(int n)
This method is equivalent to:
setHeader("Max-Forwards", String.valueOf(n));
n
- new value of the Max-Forwards headerjava.lang.IllegalArgumentException
- if the argument is not in the range
0 to 255public 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.
String
specifying the name of the charset,
for example, ISO-8859-1public int getContentLength()
public java.lang.String getContentType()
String
containing the name of the
MIME type of this message, or null if the body is emptypublic java.lang.Object getContent() throws java.io.IOException
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.
InputStream
if the MIME type isn't known to
the platformjava.io.IOException
- if an IOException
occurredpublic byte[] getRawContent() throws java.io.IOException
java.io.IOException
- if an IOException occurredpublic void setContent(java.lang.Object obj, java.lang.String type)
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.
obj
- an object representing the message contenttype
- MIME type of the objectjava.lang.IllegalArgumentException
- if the platform doesn't know how to
serrialize content of the specified MIME typejava.lang.IllegalStateException
- if the message has already been sent
or if it's read-onlypublic javax.servlet.ServletInputStream getInputStream() throws java.io.IOException
ServletInputStream
object containing the
body of the requestjava.lang.IllegalStateException
- if this message is committedjava.io.IOException
- if an input or output exception occurred,
specifically if an open input or output stream currently
exists for this messagepublic javax.servlet.ServletOutputStream getOutputStream() throws java.io.IOException
ServletOutputStream
suitable for writing
binary data in the response. The servlet container does not encode
the binary data.java.lang.IllegalStateException
- if this is an incoming message or if
it has already been sentjava.io.IOException
- if an input or output exception occurred,
specifically if an open input or output stream currently
exists for this messagepublic void setContentLength(int len)
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.
len
- an integer specifying the length of the content being
sent to the peer; sets the Content-Length headerjava.lang.IllegalStateException
- if this is an incoming message or if
it has already been sentpublic void setContentType(java.lang.String type)
If obtaining a PrintWriter, this method should be called first.
type
- a String specifying the MIME type of the contentpublic java.lang.Object getAttribute(java.lang.String name)
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.
name
- a String
specifying the name of the attributeObject
containing the value of the attribute,
or null if the attribute does not existpublic java.util.Enumeration getAttributeNames()
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.Enumeration
of strings containing the names
of the request's attributespublic void setAttribute(java.lang.String name, java.lang.Object o)
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.
name
- a String specifying the name of the attributeo
- the Object to be storedpublic SipSession getSession()
SipSession
to which this message belongs.
If the session didn't already exist it is created. This method is
equivalent to calling getSession(true)
.SipSession
to which this
SipServletMessage
belongspublic SipSession getSession(boolean create)
SipSession
to which this message belongs.create
- indicates whether the session is created if it doesn't
already existSipSession
to which this
SipServletMessage
belongs, or null if one hasn't
been created and create
is falsepublic SipApplicationSession getApplicationSession()
SipServletMessage
belongspublic SipApplicationSession getApplicationSession(boolean create)
create
- if true the session is created if it didn't
already exist, otherwise null is returnedpublic boolean isRequestedSessionIdValid()
public java.util.Locale getAcceptLanguage()
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.Locale
for the sending user agentpublic java.util.Iterator getAcceptLanguages()
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.Enumeration
of preferred locales for the
UA originating this messagepublic void setAcceptLanguage(java.util.Locale locale)
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.
locale
- the preferred locale of this user agentpublic void addAcceptLanguage(java.util.Locale locale)
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.locale
- a locale acceptable to this user agentpublic void setContentLanguage(java.util.Locale locale)
getWriter
. By default, the message
locale is the default locale for the server.locale
- the locale of this messagepublic java.util.Locale getContentLanguage()
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.Locale
of this messagepublic void send()
SipServletMessage
.java.lang.IllegalStateException
- if this message cannot legally be sent
in the current state of the underlying SIP transactionpublic Proxy getProxy() throws TooManyHopsException
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.
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 initiatedSipServletRequest.getProxy(boolean)
public boolean isSecure()
public boolean isCommitted()
public java.lang.String getRemoteUser()
String
specifying the login of the user
making this request, or null if the user has not been
authenticatedpublic boolean isUserInRole(java.lang.String role)
role
- a String
specifying the name of the rolepublic java.security.Principal getUserPrincipal()
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.java.security.Principal
representing the
sending user, or null if the user has not been authenticated
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |