SipFactory

The SipFactory interface serves as a factory for creating various SIP Servlet API abstractions, such as SIP requests, responses, addresses, and URIs. It acts as a central point for generating protocol-level objects used in SIP communication.
SIP servlet containers are required to provide a SipFactory instance to applications. This instance can be accessed through the ServletContext attribute with the name javax.servlet.sip.SipFactory. By leveraging the SipFactory, applications can dynamically create and manage SIP-specific objects, enabling seamless integration with the SIP protocol.

Methods:

createURI

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

Creates and returns a URI object corresponding to the specified string. The input string should represent an escaped SIP, SIPS, or tel URI, which can be used as the request URI in SIP requests or as the URI component in Address objects.
The method supports URIs of any scheme.
If the URI is a SIP or SIPS URI, a SipURI object is returned.
If the URI is a tel URL, a TelURL object is returned.
The container ensures that any reserved characters in the URI string are properly escaped according to RFC 2396.
Parameters:
uri: A string representing the SIP, SIPS, or tel URI to be parsed.
Throws:
ServletParseException: If the URI scheme is unknown or if parsing the URI fails.

createSipURI

SipURI createSipURI(java.lang.String user,
                    java.lang.String host)

Creates and returns a new SipURI object with the specified user and host components. The URI scheme is initially set to sip, but it can be changed to sips by calling setSecure(true) on the returned SipURI object. The port number is initially unspecified and can be set later using the setPort() method.
Constructs a SipURI with the given user and host parts.
Reserved characters in the URI string are escaped by the container in compliance with RFC 2396.
Parameters:
user: The user part of the new SipURI.
host: The host part of the new SipURI.

createAddress

Address createAddress(java.lang.String addr)
                      throws ServletParseException

Creates and returns an Address object based on the specified string. The resulting Address can be used in SIP headers, such as From or To, for locally initiated SIP requests. If the string is "*", the method returns a wildcard Address, where isWildcard() returns true. Wildcard addresses are intended for use in Contact headers only.
The input string must be UTF-8 encoded.
If the URI component contains reserved characters, the container escapes them in compliance with RFC 2396, as described in createURI(String).
Parameters:
addr: A string representing a valid SIP From or To header value.
Throws:
ServletParseException: If parsing the address string fails.

createAddress

Address createAddress(URI uri)

Creates and returns an Address object with the specified URI and no display name. The resulting Address can be used in SIP headers or other relevant components where only a URI is required.
Parameters:
uri: The URI to be used as the URI component of the Address.

createAddress

Address createAddress(URI uri,
                      java.lang.String displayName)

Creates and returns an Address object with the specified URI and display name. The display name provides a human-readable identifier for the address, commonly used in SIP headers like From or To.
Parameters:
uri: The URI to be used as the URI component of the Address.
displayName: A string representing the display name for the Address.

createParameterable

Parameterable createParameterable(java.lang.String s)
                                  throws ServletParseException

Creates and returns a new Parameterable object parsed from the specified string. The input string must conform to the following format:
field-value *(;parameter-name[=parameter-value])
The field-value can be:
In name-addr or addr-spec format, as defined in RFC 3261.
Any sequence of tokens up to the first semicolon (;).
The Parameterable object allows manipulation of parameters, making it useful for working with headers that include parameters.
Parameters:
s: A string representing the header field in the specified format.
Throws:
ServletParseException: If parsing the input string fails.

createRequest

SipServletRequest createRequest(SipApplicationSession appSession,
                                java.lang.String method,
                                Address from,
                                Address to)

Creates a new SipServletRequest with the specified request method, From, and To headers. The request belongs to a new SipSession within the given SipApplicationSession. The container assigns appropriate headers, such as Call-ID, CSeq, and Contact (if the method is not REGISTER).
Method copies and sanitizes the From and To arguments, removing invalid components as specified in RFC 3261.
A new tag is generated for the From header, and any tag in the To header is removed.
Parameters:
appSession: The SipApplicationSession to which the new request and SipSession belong.
method: The method of the new request (e.g., "INVITE").
from: The Address for the From header.
to: The Address for the To header.
Returns:
A SipServletRequest object with the specified method and headers.
Throws:
IllegalArgumentException if the method is ACK or CANCEL, or the appSession is invalid.

createRequest

SipServletRequest createRequest(SipApplicationSession appSession,
                                java.lang.String method,
                                URI from,
                                URI to)

Similar to the Address version but accepts URI objects for the From and To headers. This method sanitizes and processes the URIs to conform to SIP standards.
Parameters:
appSession: The SipApplicationSession to which the new request and SipSession belong.
method: The method of the new request (e.g., "INVITE").
from: The URI for the From header.
to: The URI for the To header.
Returns:
A SipServletRequest object with the specified method and headers.
Throws:
IllegalArgumentException: If the method is ACK or CANCEL, or the appSession is invalid.

createRequest

SipServletRequest createRequest(SipApplicationSession appSession,
                                java.lang.String method,
                                java.lang.String from,
                                java.lang.String to)
                                throws ServletParseException

This method works similarly to the previous ones but accepts String representations of the From and To headers. Internally, it parses the strings into Address objects.
Parameters:
appSession: The SipApplicationSession to which the new request and SipSession belong.
method: The method of the new request (e.g., "INVITE").
from: A string representing the From header.
to: A string representing the To header.
Returns:
A SipServletRequest object with the specified method and headers.
Throws:
ServletParseException: If parsing the from or to strings fails.
IllegalArgumentException: If the method is ACK or CANCEL, or the appSession is invalid.

createRequest

SipServletRequest createRequest(SipServletRequest origRequest,
                                boolean sameCallId)

Deprecated: This method is deprecated because using the same Call-ID for multiple dialogs violates RFC 3261. Applications should use B2buaHelper.createRequest(SipServletRequest) instead.
Creates a new SipServletRequest based on the specified original request. The new request:

• Shares the same SipApplicationSession as the original request.
• Has a new SipSession with a new From tag and no To tag.
• If sameCallId is false, a new Call-ID is assigned.

Parameters:
origRequest: The original request to copy.
sameCallId: Whether to use the same Call-ID as the original request.
Returns:
A new SipServletRequest object based on the original request.
Throws:
IllegalArgumentException: If the method violates SIP standards or the sameCallId flag leads to protocol inconsistency.

createApplicationSession

SipApplicationSession createApplicationSession()

Creates and returns a new SipApplicationSession. This is useful when an application needs to perform signaling actions outside the context of an existing session, such as during initialization.
Returns:
A new SipApplicationSession object.

createApplicationSessionByKey

SipApplicationSession createApplicationSessionByKey(java.lang.String sipApplicationKey)

Creates and returns a new SipApplicationSession identified by the specified SipApplicationKey. This allows incoming requests to be associated with an existing SipApplicationSession based on the key. The key should match one generated by the method annotated with @SipApplicationKey.
Parameters:
sipApplicationKey: A string representing the identifier for the SipApplicationSession.
Returns:
A new SipApplicationSession object with the specified key.

createAuthInfo

AuthInfo createAuthInfo()

Creates and returns a new AuthInfo object. This object can be used to manage authentication information for servlet-initiated requests, making it easier to handle authentication challenges from SIP servers.
Returns:
A new instance of AuthInfo.