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 sipAddress) 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.
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) Creates a new request object belonging to a new SipSession.
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.

Method Detail

createURI

public URI createURI(java.lang.String uri)
              throws ServletParseException

Returns a URI object corresponding to the specified string. 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.

Parameters:

uri - the URI string to parse

Returns:

a parsed URI object

Throws:

ServletParseException - if the URI scheme is unknown or parsing failed

createSipURI

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

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

public Address createAddress(java.lang.String sipAddress)
                      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.

Parameters:

addr - valid value of SIP From or To header

Returns:

a parsed Address

Throws:

ServletParseException - if parsing failed

createAddress

public 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

public 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

createRequest

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

createRequest

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

createRequest

public 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"

createRequest

public SipServletRequest createRequest(SipServletRequest origRequest,
                                       boolean sameCallId)

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.

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 (To/From tags will make its ID unique)

Returns:

the "copied" request object

createApplicationSession

public 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