javax.servlet.sip
Interface SipFactory


public interface SipFactory

Factory interface for a variety of SIP Servlet API abstractions.

SIP servlet containers are requried to make a SipFactory instance available to applications through a ServletContext attribute with name javax.servlet.sip.SipFactory.


Method Summary
 Address createAddress(java.lang.String addr)
          Returns a Address corresponding to the specified string.
 Address createAddress(URI uri)
          Returns an Address with the specified URI and no display name.
 Address createAddress(URI uri, java.lang.String displayName)
          Returns a new Address with the specified URI and display name.
 SipApplicationSession createApplicationSession()
          Returns a new SipApplicationSession.
 SipApplicationSession createApplicationSessionByKey(java.lang.String sipApplicationKey)
          Returns a new SipApplicationSession identified by the specified SipApplicationKey.
 AuthInfo createAuthInfo()
          Creates a new AuthInfo object that can be used to provide authentication information on servlet initiated requests.
 Parameterable createParameterable(java.lang.String s)
          Creates a new Parameterable parsed from the specified string.
 SipServletRequest createRequest(SipApplicationSession appSession, java.lang.String method, Address from, Address to)
          Returns a new request object with the specified request method, From, and To headers.
 SipServletRequest createRequest(SipApplicationSession appSession, java.lang.String method, java.lang.String from, java.lang.String to)
          Returns a new request object with the specified request method, From, and To headers.
 SipServletRequest createRequest(SipApplicationSession appSession, java.lang.String method, URI from, URI to)
          Returns a new request object with the specified request method, From, and To headers.
 SipServletRequest createRequest(SipServletRequest origRequest, boolean sameCallId)
          Deprecated. usage of this method is deprecated. Setting the sameCallId flag to "true" actually breaks the provisions of [RFC 3261] where the Call-ID value is to be unique accross dialogs. Instead use a more general method defined on the B2buaHelper B2buaHelper.createRequest(SipServletRequest)
 SipURI createSipURI(java.lang.String user, java.lang.String host)
          Constructs a SipURI with the specified user and host components.
 URI createURI(java.lang.String uri)
          Returns a URI object corresponding to the specified string, which should represent an escaped SIP, SIPS, or tel URI.
 

Method Detail

createURI

URI createURI(java.lang.String uri)
              throws ServletParseException
Returns a URI object corresponding to the specified string, which should represent an escaped SIP, SIPS, or tel URI. The URI may then be used as request URI in SIP requests or as the URI component of Address objects.

Implementations must be able to represent URIs of any scheme. This method returns a SipURI object if the specified string is a sip or a sips URI, and a TelURL object if it's a tel URL.

If the specified URI string contains any reserved characters, then the container is responsible for escaping them, in accordance with RFC2396.

Parameters:
uri - the SIP, SIPS, or tel string to parse
Returns:
a parsed URI object
Throws:
ServletParseException - if the URI scheme is unknown or parsing failed

createSipURI

SipURI createSipURI(java.lang.String user,
                    java.lang.String host)
Constructs a SipURI with the specified user and host components. The scheme will initially be sip but the application may change it to sips by calling setSecure(true) on the returned SipURI. Likewise, the port number of the new URI is left unspecified but may subsequently be set by calling setPort on the returned SipURI.

If the specified URI string contains any reserved characters, then the container is responsible for escaping them, in accordance with RFC2396.

Parameters:
user - user part of the new SipURI
host - host part of the new SipURI
Returns:
new insecure SipURI with the specified user and host parts

createAddress

Address createAddress(java.lang.String addr)
                      throws ServletParseException
Returns a Address corresponding to the specified string. The resulting object can be used, for example, as the value of From or To headers of locally initiated SIP requests.

The special argument "*" results in a wildcard Address being returned, that is, an Address for which isWildcard returns true. Such addresses are for use in Contact headers only.

The specified address string must be UTF-8 encoded. Furthermore, if the URI component of the address string contains any reserved characters then the container is responsible for escaping them in accordance with RFC2396 as indicated for createURI(String)

Parameters:
addr - valid value of SIP From or To header
Returns:
a parsed Address
Throws:
ServletParseException - if parsing failed

createAddress

Address createAddress(URI uri)
Returns an Address with the specified URI and no display name.

Parameters:
uri - the URI of the returned Address
Returns:
an Address whose URI component is the argument

createAddress

Address createAddress(URI uri,
                      java.lang.String displayName)
Returns a new Address with the specified URI and display name.

Parameters:
uri - URI of the new Address
displayName - display name of the new Address

createParameterable

Parameterable createParameterable(java.lang.String s)
                                  throws ServletParseException
Creates a new Parameterable parsed from the specified string. The string must be in the following format:
 field-value *(;parameter-name[=parameter-value])
 
where the field-value may be in name-addr or addr-spec format as defined in RFC 3261 or may be any sequence of tokens till the first semicolon.

Parameters:
s - the header field string
Returns:
a parsed Parameterable
Throws:
ServletParseException - if parsing failed
Since:
1.1

createRequest

SipServletRequest createRequest(SipApplicationSession appSession,
                                java.lang.String method,
                                Address from,
                                Address to)
Returns a new request object with the specified request method, From, and To headers. The returned request object exists in a new SipSession which belongs to the specified SipApplicationSession.

This method is used by servlets acting as SIP clients in order to send a request in a new call leg. The container is responsible for assigning the request appropriate Call-ID and CSeq headers, as well as Contact header if the method is not REGISTER.

This method makes a copy of the from and to arguments and associates them with the new SipSession. Any component of the from and to URIs not allowed in the context of SIP From and To headers are removed from the copies [refer Table 1, Section 19.1.1, RFC3261]. This includes, headers and various parameters. Also, a "tag" parameter in either of the copied from or to is also removed, as it is illegal in an initial To header and the container will choose it's own tag for the From header. The copied from and to addresses can be obtained from the SipSession but must not be modified by applications.

Parameters:
appSession - the application session to which the new SipSession and SipServletRequest belongs
method - the method of the new request, e.g. "INVITE"
from - value of the From header
to - value of the To header
Returns:
the request object with method, request URI, and From, To, Call-ID, CSeq, Route headers filled in.
Throws:
java.lang.IllegalArgumentException - if the method is "ACK" or "CANCEL", or the specified SipApplicationSession is invalid.

createRequest

SipServletRequest createRequest(SipApplicationSession appSession,
                                java.lang.String method,
                                URI from,
                                URI to)
Returns a new request object with the specified request method, From, and To headers. The returned request object exists in a new SipSession which belongs to the specified SipApplicationSession.

This method is used by servlets acting as SIP clients in order to send a request in a new call leg. The container is responsible for assigning the request appropriate Call-ID and CSeq headers, as well as Contact header if the method is not REGISTER.

This method makes a copy of the from and to arguments and associates them with the new SipSession. Any component of the from and to URIs not allowed in the context of SIP From and To headers are removed from the copies [refer Table 1, Section 19.1.1, RFC3261]. This includes, headers and various parameters. The from and to addresses can subsequently be obtained from the SipSession or the returned request object but must not be modified by applications.

Parameters:
appSession - the application session to which the new SipSession and SipServletRequest belongs
method - the method of the new request, e.g. "INVITE"
from - value of the From header
to - value of the To header
Returns:
the request object with method, request URI, and From, To, Call-ID, CSeq, Route headers filled in.
Throws:
java.lang.IllegalArgumentException - if the method is "ACK" or "CANCEL", or the specified SipApplicationSession is invalid.

createRequest

SipServletRequest createRequest(SipApplicationSession appSession,
                                java.lang.String method,
                                java.lang.String from,
                                java.lang.String to)
                                throws ServletParseException
Returns a new request object with the specified request method, From, and To headers. The returned request object exists in a new SipSession which belongs to the specified SipApplicationSession.

This method is used by servlets acting as SIP clients in order to send a request in a new call leg. The container is responsible for assigning the request appropriate Call-ID and CSeq headers, as well as Contact header if the method is not REGISTER.

This method is functionally equivalent to:

 createRequest(method, f.createAddress(from), f.createAddress(to));
 
Note that this implies that if either of the from or to argument is a SIP URI containing parameters, the URI must be enclosed in angle brackets. Otherwise the address will be parsed as if the parameter belongs to the address and not the URI.

Parameters:
appSession - the application session to which the new SipSession and SipServletRequest belongs
method - the method of the new request, e.g. "INVITE"
from - value of the From header -- this must be a valid Address
to - value of the To header -- this must be a valid Address
Returns:
the request object with method, request URI, and From, To, Call-ID, CSeq, Route headers filled in.
Throws:
ServletParseException - if the URI scheme of the from or to argument is unknown or if parsing failed
java.lang.IllegalArgumentException - if the method is "ACK" or "CANCEL", or the specified SipApplicationSession is invalid.

createRequest

SipServletRequest createRequest(SipServletRequest origRequest,
                                boolean sameCallId)
Deprecated. usage of this method is deprecated. Setting the sameCallId flag to "true" actually breaks the provisions of [RFC 3261] where the Call-ID value is to be unique accross dialogs. Instead use a more general method defined on the B2buaHelper B2buaHelper.createRequest(SipServletRequest)

Creates a new request object belonging to a new SipSession. The new request is similar to the specified origRequest in that the method and the majority of header fields are copied from origRequest to the new request. The SipSession created for the new request also shares the same SipApplicationSession associated with the original request.

This method satisfies the following rules:

This method provides a convenient and efficient way of constructing the second "leg" of a B2BUA application. It is used only for the initial request. Subsequent requests in either leg must be created using SipSession.createRequest(java.lang.String) as usual.

Parameters:
origRequest - request to be "copied"
sameCallId - whether or not to use same Call-ID for the new dialog
Returns:
the "copied" request object

createApplicationSession

SipApplicationSession createApplicationSession()
Returns a new SipApplicationSession. This is useful, for example, when an application is being initialized and wishes to perform some signaling action.

Returns:
a new SipApplicationSession object

createApplicationSessionByKey

SipApplicationSession createApplicationSessionByKey(java.lang.String sipApplicationKey)
Returns a new SipApplicationSession identified by the specified SipApplicationKey. This is same as the one generated by the method annotated with @SipApplicationKey annotation. This allows a way to associate incoming requests to an already existing SipApplicationSession.

Parameters:
sipApplicationKey - id for the SipApplicationSession
Returns:
a new SipApplicationSession object with the specified id
Since:
1.1

createAuthInfo

AuthInfo createAuthInfo()
Creates a new AuthInfo object that can be used to provide authentication information on servlet initiated requests.

Returns:
AuthInfo a new instance of AuthInfo