jain.protocol.ip
Class JainIPFactory

java.lang.Object
  |
  +--jain.protocol.ip.JainIPFactory

public class JainIPFactory

extends java.lang.Object

The JAIN(tm) IP Factory is a singleton class by which JAIN IP applications can obtain a proprietary (Peer) JAIN IP Object. The term 'peer' is Java nomenclature for "a particular platform-specific implementation of a Java interface or API". This term has the same meaning for the JAIN IP API specifications.
A Peer JAIN IP Object can be obtained from the JAIN IP Factory by ethier :

• instantiating a new Peer JAIN IP Object using the createIPObject() method, or
• selecting from the list of JAIN IP Objects returned by the getJainObjectList() method.

The JAIN IP Factory utilises a naming convention defined for each JAIN IP API to identify the location of proprietary JAIN IP Objects.

Under this convention the lower-level package structure and classname of a Peer JAIN IP Object is mandated by a convention defined within the JAIN IP API from which the Object originates.

For example: within the JAIN SIP API, the lower-level package structure and classname of a proprietary implementation of the jain.protocol.ip.sip.JainSipStack interface must be jain.protocol.ip.sip.JainSipStackImpl.

Under the JAIN naming convention, the upper-level package structure (pathname) can be used to differentiate between proprietary implementations from different IP Vendors. The pathname used by each IP Vendor must be the domain name assigned to the Vendor in reverse order, e.g. Sun Microsystem's would be 'com.sun'

It follows that a proprietary implementation of a JAIN IP Object can be located at:
'pathname'.'lower-level package structure and classname'

Where:

pathname = reverse domain name, e.g. com.sun'

lower-level package structure and classname = mandated naming convention for the JAIN IP Object in question

e.g. jain.protocol.ip.sip.JainSipStackImpl is the mandated naming convention for jain.protocol.ip.sipp.JainSipStack.

The resulting Peer JAIN IP Object would be located at: com.sun.jain.protocol.ip.sip.JainSipStackImpl
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 'foo.com' would have their Peer JainSipStack Object located at com.foo.jain.protocol.ip.sip.JainSipStackImpl.
This is a similar concept to the JAVA conventions used for managing package names.

The pathname is defaulted to 'com.sun' but may be set using the setPathName() method. This allows a JAIN application to switch between different Vendor implementations, as well as providing the capability to use the default or current pathname.

The JAIN IP Factory is a Singleton class. This means that there will only be one instance of the class with a global point of access to it. The single instance of the JAIN IP Factory can be obtained using the getInstance() method. In this way, the JAIN IP Factory can acts a single point obtaining JAIN IP Objects.

Version:

0.6

Method Summary

java.lang.Object	createIPObject(java.lang.String objectClassName) Returns an instance of a Peer JAIN IP Object identified by the supplied classname.
static JainIPFactory	getInstance() Returns an instance of a JainIPFactory.
java.util.Vector	getJainObjectList() Returns a Vector containing all of the Peer JAIN Objects that have previously been created using this JainIPFactory.
java.lang.String	getPathName() Returns the current Pathname.
void	setPathName(java.lang.String pathname) Sets the Pathname that identifies the location of a particular Vendor's implementation of the JAIN IP Objects.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static JainIPFactory getInstance()

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

Returns:

the single instance of this singleton JainIPFactory

setPathName

public void setPathName(java.lang.String pathname)

Sets the Pathname that identifies the location of a particular Vendor's implementation of the JAIN IP Objects. The pathname must be the domain name assigned to the Vendor providing the implementation in reverse order.

Parameters:

pathname - the reverse domain name of the Vendor. e.g. Sun Microsystem's would be 'com.sun'

getPathName

public java.lang.String getPathName()

Returns the current Pathname. The pathname identifies the location of a particular Vendor's implementation of the JAIN IP Objects. The pathname will always be the domain name assigned to the Vendor providing the implementation in reverse order.

Returns:

the pathname

createIPObject

public java.lang.Object createIPObject(java.lang.String objectClassName)
                                throws IPPeerUnavailableException

Returns an instance of a Peer JAIN IP Object identified by the supplied classname. This supplied classname is the lower-level package structure and classname of the required Peer JAIN IP Object. This classname is mandated by a convention defined within the JAIN IP API from which the Object originates.

For example: To create an instance of the jain.protocol.ip.sip.JainSipStack from the JAIN SIP API, the supplied classname will be jain.protocol.ip.sip.JainSipStackImpl.

Under the JAIN naming convention, the upper-level package structure (pathname) can be used to differentiate between proprietary implementations from different IP Vendors.

The location of the returned JAIN IP Object is dependent on the current pathname and the supplied classname.

If the specified class does not exist or is not installed in the CLASSPATH an IPPeerUnavailableException exception is thrown.

Once a Peer IP Object is created an object reference to the newly created object is stored along with object refernces to any other Peer IP Objects that have previously been created by this JainIPFactory. This list of Peer IP Objects may be retrieved at any time using the getJainObjectList() method.

Parameters:

objectClassName - lower-level package structure and classname of the Peer JAIN IP Object class that is mandated by a convention defined within the JAIN IP API from which the Object originates.

Returns:

An instance of a Peer JAIN IP Object.

Throws:

SS7PeerUnavailableException - Indicates that the Peer JAIN IP Object specified by the classname and the current pathname cannot be located.

getJainObjectList

public java.util.Vector getJainObjectList()

Returns a Vector containing all of the Peer JAIN Objects that have previously been created using this JainIPFactory.

NOTE: The Vector returned may contain Objects of any type that may have been created through this factory.

Returns:

a vector containing all JAIN IP Objects created through this JAIN IP Factory.