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