Package org.jainslee.resources.sip

Interface SipFactory

public interface SipFactory

Method Summary

Modifier and Type	Method	Description
Address	createAddress(String sipAddress)	Returns an Address corresponding to the specified string.
Address	createAddress(URI uri)
Address	createAddress(URI uri, String displayName)
Parameterable	createParameterable(String value)
OutgoingSipRequest	createRequest(String method, String from, String to)	Returns a new request object with the specified request method, From, and To headers.
OutgoingSipRequest	createRequest(String method, Address from, Address to)	Returns a new request object with the specified request method, From, and To headers.
OutgoingSipRequest	createRequest(String method, URI from, URI to)	Returns a new request object with the specified request method, From, and To headers.
OutgoingSipRequest	createRequest(IncomingSipRequest origRequest, boolean sameCallId)	Creates a new request object belonging to a new SipSession.
SipURI	createSipURI(String user, String host)
URI	createURI(String uri)
SipMessage	decodeMessage(DataInput in)	Decode a SipMessage from an input stream that was previously encoded by encodeMessage(SipMessage, DataOutput).
void	encodeMessage(SipMessage message, DataOutput out)	Encode a SipMessage to an output stream, for storage in CMP.
SipURI	getInternalASURI()	Get a URI that uniquely identifies this AS including it node and cluster IDs, for use when directing inter-node traffic.
SipURI	getLocalSipURI(String transport)	Convenience method for obtaining a SIP URI addressed to the calling service on this host.
SipURI	getLocalSipURI(String transport, boolean secure)	Convenience method for obtaining a SIP URI addressed to the calling service on this host.
SipOverloadControlPlugin	getRegisteredOverloadControlPlugin()	Retrieves the currently registered overload control plugin.
SipSession	getSipSession(String id)	Lookup a SipSession by its session ID.
boolean	isInternalASURI(String uri)	Check if a URI matches this node's internal AS URI.
boolean	isInternalASURI(URI uri)	Check if a URI matches this node's internal AS URI.
boolean	isLocalSipURI(SipURI uri)	Determine if a URI is local to this SIS instance, .
void	registerLimiterFilter(SipLimiterFilter filter)	Register a rate limiter filter.
void	registerOverloadControlPlugin(SipOverloadControlPlugin overloadControlPlugin)	Register an overload control plugin.

Method Detail

createURI

URI createURI(String uri)
       throws SipParseException

Throws:

SipParseException

createSipURI

SipURI createSipURI(String user,
                    String host)
             throws SipParseException

Throws:

SipParseException

getLocalSipURI

SipURI getLocalSipURI(String transport)

Convenience method for obtaining a SIP URI addressed to the calling service on this host. For example, an SBB might want to forward a request to an external application server, then route it back to this service. This can be achieved by pushing a route to the app server followed by a Route containing this local SIP URI.

Parameters:

transport - a case-insensitive transport name, such as "udp", "tcp" or "tls". This will be used as the transport parameter in the resulting SipURI, unless transport is "tls", in which case the RA Entity shall return a secure sips: URI. If transport is null, no transport parameter will be used in the URI.

Returns:

a SipURI addressed to the calling service on this SIP RA Entity.

Since:

EasySIP 1.2

getLocalSipURI

SipURI getLocalSipURI(String transport,
                      boolean secure)

Convenience method for obtaining a SIP URI addressed to the calling service on this host. For example, an SBB might want to forward a request to an external application server, then route it back to this service. This can be achieved by pushing a route to the app server followed by a Route containing this local SIP URI.

Parameters:

transport - a case-insensitive transport name, such as "udp", "tcp" or "tls". This will be used as the transport parameter in the resulting SipURI. If transport is null, no transport parameter will be used in the URI.

secure - if true, the URI returned will be a SIPS URI. If transport was "tls" then the transport parameter in the SIPS URI will be omitted.

Returns:

a SipURI addressed to the calling service on this SIP RA Entity.

Since:

EasySIP 3.0

isLocalSipURI

boolean isLocalSipURI(SipURI uri)

Determine if a URI is local to this SIS instance, .

Returns:

true if the host and port in the URI match an endpoint that this SIS instance is listening on (or a configured virtual address), otherwise false.

createAddress

Address createAddress(String sipAddress)
               throws SipParseException

Returns an 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:

sipAddress - a valid SIP address from a From or To header.

Returns:

a parsed Address

Throws:

SipParseException - if parsing fails

createAddress

Address createAddress(URI uri)

createAddress

Address createAddress(URI uri,
                      String displayName)

createParameterable

Parameterable createParameterable(String value)
                           throws SipParseException

Throws:

SipParseException

createRequest

OutgoingSipRequest createRequest(String method,
                                 Address from,
                                 Address to)
                          throws SipException

Returns a new request object with the specified request method, From, and To headers. The returned request belongs a new SipSession activity, accessible using SipMessage.getSession(). SBBs must attach to the session in order to receive responses.

This method is used by SBBs acting as SIP clients in order to send a request in a new call leg. The RA 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 RA 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:

method - the method of the new request, e.g. "INVITE"

from - value of the From header

to - value of the To header

Returns:

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

Throws:

IllegalArgumentException - if the method is "ACK" or "CANCEL"

SipException - if unable to create the request or session activity

createRequest

OutgoingSipRequest createRequest(String method,
                                 URI from,
                                 URI to)
                          throws SipException

Returns a new request object with the specified request method, From, and To headers. The returned request belongs a new SipSession activity, accessible using SipMessage.getSession(). SBBs must attach to the session in order to receive responses.

This method is used by SBBs acting as SIP clients in order to send a request in a new call leg. The RA 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 RA 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:

method - the method of the new request, e.g. "INVITE"

from - value of the From header

to - value of the To header

Returns:

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

Throws:

IllegalArgumentException - if the method is "ACK" or "CANCEL"

SipException - if unable to create the request or session activity

createRequest

OutgoingSipRequest createRequest(String method,
                                 String from,
                                 String to)
                          throws SipException,
                                 SipParseException

Returns a new request object with the specified request method, From, and To headers. The returned request belongs a new SipSession activity, accessible using SipMessage.getSession(). SBBs must attach to the session in order to receive responses.

This method is used by SBBs acting as SIP clients in order to send a request in a new call leg. The RA 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 RA 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:

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:

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

Throws:

IllegalArgumentException - if the method is "ACK" or "CANCEL"

SipParseException - if the URI scheme of the from or to argument is unknown or if parsing failed

SipException - if unable to create the request or session activity

createRequest

OutgoingSipRequest createRequest(IncomingSipRequest origRequest,
                                 boolean sameCallId)
                          throws SipException

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 RA.
• 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. The RA will add its own Via header field to the request.
• For non-REGISTER requests, the Contact header field is not copied but is populated by the RA.

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 the same Call-ID for the new dialog.

Returns:

the "copied" request object.

Throws:

SipException - if unable to create the request or session activity

getSipSession

SipSession getSipSession(String id)

Lookup a SipSession by its session ID.

Parameters:

id - a session ID string from SipSession.getId()

Returns:

the matching SipSession, or null if no matching session exists.

Throws:

IllegalArgumentException - if id is not a string returned by SipSession.getId()

encodeMessage

void encodeMessage(SipMessage message,
                   DataOutput out)
            throws IOException

Encode a SipMessage to an output stream, for storage in CMP. The encoding format is internal to the SIS and is only suitable for decoding via decodeMessage(DataInput).

Parameters:

message - the message to encode

out - the data output stream

Throws:

IOException - if unable to encode the message

decodeMessage

SipMessage decodeMessage(DataInput in)
                  throws IOException

Decode a SipMessage from an input stream that was previously encoded by encodeMessage(SipMessage, DataOutput). The decoded message will implement the same interface as the original message (IncomingSipRequest, OutgoingSipRequest, etc) but will not implement any methods with side effects such as OutgoingSipRequest.send(). But the original message headers and body are fully accessible, and the message may be encoded and decoded over and over again indefinitely.

Parameters:

in - the data input stream

Returns:

a SipMessage of the same type as the originally encoded message

Throws:

IOException - if unable to encode the message

getInternalASURI

SipURI getInternalASURI()

Get a URI that uniquely identifies this AS including it node and cluster IDs, for use when directing inter-node traffic.

Returns:

a URI that uniquely identifies this node.

isInternalASURI

boolean isInternalASURI(URI uri)

Check if a URI matches this node's internal AS URI.

Parameters:

uri - The URI to check

Returns:

true if the given URI matches the internal AS URI for this node.

isInternalASURI

boolean isInternalASURI(String uri)

Check if a URI matches this node's internal AS URI.

Parameters:

uri - The URI to check

Returns:

true if the given URI matches the internal AS URI for this node.

registerLimiterFilter

void registerLimiterFilter(SipLimiterFilter filter)

Register a rate limiter filter. Filters return if the incoming initial request should be considered for limiting. Filters are linked to individual services for lifetime management but apply to all requests, regardless of which composition and services are invoked. Should be called during service activation to ensure that no events are missed by the filter.

Parameters:

filter - The filter registered by the service

registerOverloadControlPlugin

void registerOverloadControlPlugin(SipOverloadControlPlugin overloadControlPlugin)

Register an overload control plugin. If a plugin is registered, SIS will invoke it for every received request prior to regular Rhino platform overload control.

At most one overload control plugin can be registered with each SIS instance in a given JVM instance at any one time. Registering a plugin atomically deregisters any previously registered plugin.

Parameters:

overloadControlPlugin - the plugin to register. May be null, which deregisters any previously registered plugin.

getRegisteredOverloadControlPlugin

SipOverloadControlPlugin getRegisteredOverloadControlPlugin()

Retrieves the currently registered overload control plugin.

Returns:

the currently registered plugin, or null if there is no registered plugin.