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:

• The From header field of the new request has a new tag chosen by the container.
• The To header field of the new request has no tag.
• If the sameCallId argument is false, the new request (and the corresponding SipSession)is assigned a new Call-ID.
• Record-Route and Via header fields are not copied. As usual, the container will add its own Via header field to the request when it's actually sent outside the application server.
• For non-REGISTER requests, the Contact header field is not copied but is populated by the container as usual.

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