javax.servlet.sip
Interface SipFactory

public interface SipFactory

Factory interface for a variety of SIP Servlet API abstractions.

SIP servlet applications can obtain an implementation of the SipFactory interface by looking it up as an attribute with name "javax.servlet.sip.SipFactory" on the ServletContext.

Method Summary

SipApplicationSession	createApplicationSession() Returns a new SipApplicationSession.
Contact	createContact(SipAddress addr) Returns a Contact object corresponding to the specified SipAddress.
Contact	createContact(java.lang.String contact) Parses the argument string as a SIP Contact (an element of the SIP Contact header) and returns the corresponding Contact object.
Contact	createContact(URI uri) Returns a new Contact with the specified URI.
Contact	createContact(URI uri, java.lang.String displayName) Returns a new Contact with the specified URI and display name.
SipServletRequest	createRequest(SipApplicationSession appSession, java.lang.String method, SipAddress from, SipAddress 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.
SipAddress	createSipAddress(java.lang.String sipAddress) Returns a SipAddress corresponding to the specified string.
SipAddress	createSipAddress(URI uri) Returns a SipAddress with the specified URI and no display name.
SipAddress	createSipAddress(URI uri, java.lang.String displayName) Returns a new SipAddress with the specified URI and display name.
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 javax.servlet.ServletException

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 SipAddress objects.

The object returned will typically be an instance of SipURI or TelURL. An implementation may be able to handle other URI schemes but MUST be able to handle sip: URLs.

Parameters:

uri - the URI string to parse

Returns:

a parsed URI object

Throws:

ServletException - if the URI scheme is unknown or parsing failed

createSipAddress

public SipAddress createSipAddress(java.lang.String sipAddress)
                            throws javax.servlet.ServletException

Returns a SipAddress corresponding to the specified string. The resulting object can be used as the value of From or To headers of locally initiated SIP requests.

Parameters:

sipAddress - valid value of SIP From or To header

Returns:

a parsed SipAddress

Throws:

ServletException - if parsing failed

createSipAddress

public SipAddress createSipAddress(URI uri)

Returns a SipAddress with the specified URI and no display name.

Parameters:

uri - the URI of the returned SipAddress

Returns:

a SipAddress whose URI component is the argument

createSipAddress

public SipAddress createSipAddress(URI uri,
                                   java.lang.String displayName)

Returns a new SipAddress with the specified URI and display name.

Parameters:

uri - URI of the new SipAddress

displayName - display name of the new SipAddress

createContact

public Contact createContact(java.lang.String contact)
                      throws javax.servlet.ServletException

Parses the argument string as a SIP Contact (an element of the SIP Contact header) and returns the corresponding Contact object.

Parameters:

contact - String value of contact

Returns:

a Contact corresponding to the argument throws ServletException if the argument isn't a valid element of a SIP Contact header

createContact

public Contact createContact(URI uri)

Returns a new Contact with the specified URI.

Parameters:

uri - URI of the new Contact

Returns:

a Contact with the specified URI

createContact

public Contact createContact(URI uri,
                             java.lang.String displayName)

Returns a new Contact with the specified URI and display name.

Parameters:

uri - URI of the new Contact

displayName - display name of the new Contact

Returns:

a Contact with the specified URI and display name

createContact

public Contact createContact(SipAddress addr)

Returns a Contact object corresponding to the specified SipAddress.

Parameters:

addr - the SipAddress to use as a template

Returns:

a Contact object with display name, URI, and parameters identical to those of the argument

createRequest

public SipServletRequest createRequest(SipApplicationSession appSession,
                                       java.lang.String method,
                                       SipAddress from,
                                       SipAddress 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 javax.servlet.ServletException

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.createSipAddress(from), f.createSipAddress(to));
 

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 SipAddress

to - value of the To header -- this must be a valid SipAddress

Returns:

the request object with method, request URI, and From, To, Call-ID, CSeq, Route headers filled in.

Throws:

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

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