javax.sip

Class SipFactory

java.lang.Object

javax.sip.SipFactory

public class SipFactory
extends Object

The SipFactory is a singleton class which applications can use a single access point to obtain proprietary implementations of this specification. As the SipFactory is a singleton class there will only ever be one instance of the SipFactory. The single instance of the SipFactory can be obtained using the getInstance() method. If an instance of the SipFactory already exists it will be returned to the application, otherwise a new instance will be created. A peer implementation object can be obtained from the SipFactory by invoking the appropriate create method on the SipFactory e.g. to create a peer SipStack, an application would invoke the createSipStack(Properties) method.

Naming Convention
Note that the SipFactory utilises a naming convention defined by this specification to identify the location of proprietary objects that implement this specification. The naming convention is defined as follows:

• The upper-level package structure referred to by the SipFactory with the attribute pathname can be used to differentiate between proprietary implementations from different SIP stack vendors. The pathname used by each SIP vendor must be the domain name assigned to that vendor in reverse order. For example, the pathname used by Sun Microsystem's would be com.sun.
• The lower-level package structure and classname of a peer object is also mandated by this specification. The lowel-level package must be identical to the package structure defined by this specification and the classname is mandated to the interface name appended with the Impl post-fix. For example, the lower-level package structure and classname of a proprietary implementation of the javax.sip.SipStack interface must be javax.sip.SipStackImpl.

Using this naming convention the SipFactory can locate a vendor's implementation of this specification without requiring an application to supply a user defined string to each create method in the SipFactory. Instead an application merely needs to identify the vendors SIP implementation it would like to use by setting the pathname of that vendors implementation.

It follows that a proprietary implementation of a peer object of this specification can be located at:

'pathname'.'lower-level package structure and classname'.

For example an application can use the SipFactory to instantiate a NIST peer SipStack object by setting the pathname to gov.nist and calling the createSipStack method. The SipFactory would return a new instance of the SipStack object at the following location: gov.nist.javax.sip.SipStackImpl.java Because the space of domain names is managed, this scheme ensures that collisions between two different vendor's implementations will not happen. For example: a different vendor with a domain name 'bea.com' would have their peer SipStack object located at com.bea.javax.sip.SipStackImpl.java.

Default Namespace:
This specification defines a default namespace for the SipFactory, this namespace is the location of the Reference Implementation. The default namespace is gov.nist the author of the Reference Implementation, therefore the pathname will have the initial value of gov.nist for a new instance of the SipFactory. An application must set the pathname of the SipFactory on retrieval of a new instance of the factory in order to use a different vendors SIP stack from that of the Reference Implementation. An application can not mix different vendor's peer implementation objects.

Version:

1.2

Author:

BEA Systems, NIST

Method Summary

Methods

Modifier and Type	Method and Description
AddressFactory	createAddressFactory() Creates an instance of the AddressFactory implementation.
HeaderFactory	createHeaderFactory() Creates an instance of the HeaderFactory implementation.
MessageFactory	createMessageFactory() Creates an instance of the MessageFactory implementation.
SipStack	createSipStack(Properties properties) Creates an instance of a SipStack implementation based on the configuration properties object passed to this method.
static SipFactory	getInstance() Returns an instance of a SipFactory.
String	getPathName() Returns the current pathname of the SipFactory.
void	resetFactory() This method reset's the SipFactory's references to the object's it has created.
void	setPathName(String pathName) Sets the pathname that identifies the location of a particular vendor's implementation of this specification.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static SipFactory getInstance()

Returns an instance of a SipFactory. This is a singleton class so this method is the global access point for the SipFactory.

Returns:

the single instance of this singleton SipFactory

createSipStack

public SipStack createSipStack(Properties properties)
                        throws PeerUnavailableException

Creates an instance of a SipStack implementation based on the configuration properties object passed to this method. The recommended behaviour is to not specify an "javax.sip.IP_ADDRESS" property in the Properties argument, in this case the "javax.sip.STACK_NAME" uniquely identifies the stack. A new stack instance will be returned for each different stack name associated with a specific vendor implementation. The ListeningPoint is used to configure the IP Address argument. For backwards compatability, if a "javax.sip.IP_ADDRESS" is supplied, this method ensures that only one instance of a SipStack is returned to the application for that IP Address, independent of the number of times this method is called. Different SipStack instances are returned for each different IP address.

See SipStack for the expected format of the properties argument.

Throws:

PeerUnavailableException - if the peer class could not be found

createMessageFactory

public MessageFactory createMessageFactory()
                                    throws PeerUnavailableException

Creates an instance of the MessageFactory implementation. This method ensures that only one instance of a MessageFactory is returned to the application, no matter how often this method is called.

Throws:

PeerUnavailableException - if peer class could not be found

createHeaderFactory

public HeaderFactory createHeaderFactory()
                                  throws PeerUnavailableException

Creates an instance of the HeaderFactory implementation. This method ensures that only one instance of a HeaderFactory is returned to the application, no matter how often this method is called.

Throws:

PeerUnavailableException - if peer class could not be found

createAddressFactory

public AddressFactory createAddressFactory()
                                    throws PeerUnavailableException

Creates an instance of the AddressFactory implementation. This method ensures that only one instance of an AddressFactory is returned to the application, no matter how often this method is called.

Throws:

PeerUnavailableException - if peer class could not be found

setPathName

public void setPathName(String pathName)

Sets the pathname that identifies the location of a particular vendor's implementation of this specification. The pathname must be the reverse domain name assigned to the vendor providing the implementation. An application must call resetFactory() before changing between different implementations of this specification.

Parameters:

pathName - - the reverse domain name of the vendor, e.g. Sun Microsystem's would be 'com.sun'

getPathName

public String getPathName()

Returns the current pathname of the SipFactory. The pathname identifies the location of a particular vendor's implementation of this specification as defined the naming convention. The pathname must be the reverse domain name assigned to the vendor providing this implementation. This value is defaulted to gov.nist the location of the Reference Implementation.

Returns:

the string identifying the current vendor implementation.

resetFactory

public void resetFactory()

This method reset's the SipFactory's references to the object's it has created. It allows these objects to be garbage collected assuming the application no longer holds references to them. This method must be called to reset the factories references to a specific vendors implementation of this specification before it creates another vendors implementation of this specification by changing the pathname of the SipFactory.