|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface SipSession
Represents point-to-point SIP relationships. It roughly corresponds to a SIP dialog. In particular, for UAs it maintains (or is otherwise associated with) dialog state so as to be able to create subequent requests belonging to that dialog (using createRequest
).
For UACs, SipSession
extend the notion of SIP dialogs to have well-defined state before a dialog has been established and after a final non-2xx terminates an early dialog. This allows UACs to create "subsequent" requests without having an established dialog. The effect is that the subsequent request will have the same Call-ID, From and To headers (with the same From tag and without a To tag), the will exist in the same CSeq space.
All messages are potentially associated with a SipSession
. The SipSession
can be retrieved from the message by calling SipServletMessage.getSession()
.
Nested Class Summary | |
---|---|
static class |
SipSession.State Possible SIP dialog states from SipSession FSM. |
Method Summary | |
---|---|
SipServletRequest |
createRequest(java.lang.String method) Returns a new request object. |
SipApplicationSession |
getApplicationSession() Returns the application session with which this SipSession is associated. |
java.lang.Object |
getAttribute(java.lang.String name) Returns the object bound with the specified name in this session, or null if no object is bound under the name. |
java.util.Enumeration<java.lang.String> |
getAttributeNames() Returns an Enumeration over the String objects containing the names of all the objects bound to this session. |
java.lang.String |
getCallId() Returns the Call-ID for this SipSession . |
long |
getCreationTime() Returns the time when this session was created, measured in milliseconds since midnight January 1, 1970 GMT. |
java.lang.String |
getId() Returns a string containing the unique identifier assigned to this session. |
boolean |
getInvalidateWhenReady() Returns true if the container will notify the application when this SipSession is in the ready-to-invalidate state. |
long |
getLastAccessedTime() Returns the last time the client sent a request associated with this session, as the number of milliseconds since midnight January 1, 1970 GMT. |
Address |
getLocalParty() Returns the Address identifying the local party. |
SipApplicationRoutingRegion |
getRegion() This method allows the application to obtain the region it was invoked in for this SipSession. |
Address |
getRemoteParty() Returns the Address identifying the remote party. |
ServletContext |
getServletContext() Returns the ServletContext to which this session belongs. |
SipSession.State |
getState() Returns the current SIP dialog state, which is one of INITIAL, EARLY, CONFIRMED, or TERMINATED. |
URI |
getSubscriberURI() Returns the URI of the subscriber for which this application is invoked to serve. |
void |
invalidate() Invalidates this session and unbinds any objects bound to it. |
boolean |
isReadyToInvalidate() Returns true if this session is in a ready-to-invalidate state. |
boolean |
isValid() Returns true if this SipSession is valid, false otherwise. |
void |
removeAttribute(java.lang.String name) Removes the object bound with the specified name from this session. |
void |
setAttribute(java.lang.String name, java.lang.Object attribute) Binds an object to this session, using the name specified. |
void |
setHandler(java.lang.String name) Sets the handler for this SipSession . |
void |
setInvalidateWhenReady(boolean invalidateWhenReady) Specifies whether the container should notify the application when the SipSession is in the ready-to-invalidate state as defined above. |
void |
setOutboundInterface(java.net.InetAddress address) In multi-homed environment this method can be used to select the outbound interface to use when sending requests for this SipSession. |
void |
setOutboundInterface(java.net.InetSocketAddress address) In multi-homed environment this method can be used to select the outbound interface and source port number to use when sending requests for this SipSession. |
Method Detail |
---|
long getCreationTime()
java.lang.String getId()
long getLastAccessedTime()
void invalidate()
java.lang.IllegalStateException
- if this method is called on an invalidated sessionboolean isReadyToInvalidate()
SipSession
is in the ready-to-invalidate state under any of the following conditions:
java.lang.IllegalStateException
- if this method is called on an invalidated sessionvoid setInvalidateWhenReady(boolean invalidateWhenReady)
SipSessionListener.sessionReadyToInvalidate
callback.invalidateWhenReady
- if true, the container will observe this session and notify the application when it is in the ready-to-invalidate state. The session is not observed if the flag is false. The default is true for v1.1 applications and false for v1.0 applications.java.lang.IllegalStateException
- if this method is called on an invalidated sessionisReadyToInvalidate()
, SipSessionListener.sessionReadyToInvalidate(SipSessionEvent se)
boolean getInvalidateWhenReady()
SipSession
is in the ready-to-invalidate state.java.lang.IllegalStateException
- if this method is called on an invalidated sessionisReadyToInvalidate()
SipApplicationSession getApplicationSession()
SipSession
is associated. If none exists, then a new one is created and returned after associating it with this SipSession
.SipSession
java.lang.String getCallId()
SipSession
. This is the value of the Call-ID header for all messages belonging to this session.SipSession
Address getLocalParty()
Address
identifying the local party. This is the value of the From header of locally initiated requests in this leg.Address getRemoteParty()
Address
identifying the remote party. This is the value of the To header of locally initiated requests in this leg.SipServletRequest createRequest(java.lang.String method)
Note that this method must not be used to create ACK or CANCEL requests. User agents create ACKs by calling SipServletResponse.createAck()
and CANCELs are created by calling SipServletRequest.createCancel()
.
method
- the SIP method of the new requestjava.lang.IllegalArgumentException
- if method
is not a syntactically valid SIP method or if it's "ACK" or "CANCEL"java.lang.IllegalStateException
- if this SipSession
has been invalidated or if this SipSession
is in the INITIAL state and there is an ongoing transaction or if this SipSession
is in the TERMINATED statevoid setHandler(java.lang.String name) throws ServletException
SipSession
. This method can be used to explicitly specify the name of the servlet which should handle all subsequently received messages for this SipSession
. The servlet must belong to the same application (i.e. same ServletContext
) as the caller.name
- name of the servlet to be invoked for incoming SIP messages belonging to this SipSession
ServletException
- if no servlet with the specified name exists in this applicationjava.lang.IllegalStateException
- if this method is called on an invalidated sessionjava.lang.Object getAttribute(java.lang.String name)
name
- a string specifying the name of the objectjava.lang.IllegalStateException
- if this method is called on an invalidated sessionjava.lang.NullPointerException
- if the name
is null.java.util.Enumeration<java.lang.String> getAttributeNames()
Enumeration
over the String
objects containing the names of all the objects bound to this session.java.lang.IllegalStateException
- if this method is called on an invalidated sessionvoid setAttribute(java.lang.String name, java.lang.Object attribute)
name
- the name to which the object is bound; cannot be nullattribute
- the object to be bound; cannot be nulljava.lang.IllegalStateException
- if this method is called on an invalidated sessionjava.lang.NullPointerException
- on null name
or attribute
.void removeAttribute(java.lang.String name)
name
- the name of the object to remove from this sessionjava.lang.IllegalStateException
- if this method is called on an invalidated sessionSipSession.State getState()
java.lang.IllegalStateException
- if this method is called on an invalidated sessionvoid setOutboundInterface(java.net.InetSocketAddress address)
javax.servlet.sip.outboundInterfaces
.
The port is interpreted as an advice by the app to the container. If the port of the socket address has a non-zero value, the container will make a best-effort attempt to use it as the source port number for UDP packets, or as a source port number for TCP connections it originates. If the port is not available, the container will use its default port allocation scheme.
Invocation of this method also impacts the system headers generated by the container for this SipSession, such as the the Via
and the Contact
headers. The IP address part of the socket address
is used to construct these system headers.
address
- the socket address which represents the outbound interfacejava.lang.IllegalStateException
- if this method is called on an invalidated sessionjava.lang.IllegalArgumentException
- if the address
is not understood by the container as one of its outbound interfacesjava.lang.NullPointerException
- on null address
void setOutboundInterface(java.net.InetAddress address)
javax.servlet.sip.outboundInterfaces
.
Invocation of this method also impacts the system headers generated by the container for this message, such as the the Via
and the Contact
header. The supplied IP address is used to construct these system headers.
address
- the address which represents the outbound interfacejava.lang.IllegalStateException
- if this method is called on an invalidated sessionjava.lang.IllegalArgumentException
- if the address
does not represent one of the container's outbound interfacesjava.lang.NullPointerException
- on null address
boolean isValid()
invalidate()
on it or if its invalidateWhenReady flag is true and it transitions to the ready-to-invalidate state. Also the SipSession can be invalidated by the container when either the associated SipApplicationSession
times out or SipApplicationSession.invalidate()
is invoked.SipApplicationRoutingRegion getRegion()
SipSession.getSubscriberURI()
.
If this SipSession is created when this servlet receives an initial request, this method returns the region in which this servlet is invoked. The SipApplicationRoutingRegion
is only available if this SipSession received an initial request. Otherwise, this method throws IllegalStateException.
java.lang.IllegalStateException
- if this method is called on an invalidated sessionURI getSubscriberURI()
java.lang.IllegalStateException
- if this method is called on an invalidated sessionServletContext getServletContext()
SipSession
belonging to a distributed application deployed to a distributed container may be available across JVMs , this method returns the context that is local to the JVM on which it was invoked.javax.servlet.ServletContext
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 1996, 2010, Oracle and/or its affiliates. All rights reserved. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.
Java SIP Servlet API 1.1 Reference
Part Number E17883-01