jain.protocol.ip.sip
Interface JainSipStack

public interface JainSipStack

This interface defines the methods required to represent a proprietary JAIN SIP protocol stack, the implementation of which will be vendor specific. Each vendor's protocol stack will have an object that implements this interface to control the creation/deletion of proprietary JainSipProviders .

It must be noted that under the JAIN Naming Convention 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 JainSipStack will be located at:
pathname.jain.protocol.ip.sip.JainSipStackImpl
Where:
pathname = reverse domain name, e.g. com.sun'
The resulting Peer JAIN IP Object would be located at: com.sun.jain.protocol.ip.sip.JainSipStackImpl
An application may create a JainSipStackImpl by invoking the JainIPFactory.createJainIPObject() method. The PathName of the vendor specific implementation of which you want to instantiate can be set before calling this method or the default or current pathname may be used.


For applications that require some means to identify multiple stacks setStackName() can be used. An application can choose to supply any identifier to this method.

Version:

0.6

See Also:

JainSipProvider

Method Summary

JainSipProvider	createProvider(ListeningPoint listeningPoint) Creates a new Peer (vendor specific) JainSipProvider that is attached to this JainSipStack on a specified ListeningPoint and returns a reference to it.
void	deleteProvider(JainSipProvider providerToBeDeleted) Deletes the specified Peer JAIN SIP Provider attached to this JainSipStack.
ListeningPoint[]	getListeningPoints() Returns an array of ListeningPoints available to this stack
JainSipProvider[]	getProviders() Returns an array of existing Peer JAIN SIP Providers that have been created by this JainSipStackImpl.
java.lang.String	getStackName() Gets the name of this JainSipStack instance.
void	setStackName(java.lang.String stackName) Sets the name of this JainSipStack instance.

Method Detail

getListeningPoints

public ListeningPoint[] getListeningPoints()
                                    throws ListeningPointUnavailableException

Returns an array of ListeningPoints available to this stack

Returns:

array of ListeningPoints available to this JainSipStack.

Throws:

ListeningPointUnavailableException - if stack has no ListeningPOints

createProvider

public JainSipProvider createProvider(ListeningPoint listeningPoint)
                               throws IPPeerUnavailableException,
                                      ListeningPointUnavailableException,
                                      java.lang.IllegalArgumentException

Creates a new Peer (vendor specific) JainSipProvider that is attached to this JainSipStack on a specified ListeningPoint and returns a reference to it. Note to developers: The implementation of this method should add the newly created JainSipProvider to the providerList once the JainSipProvider has been successfully created.

Parameters:

listeningPoint - the ListeningPoint the Provider is to be attached to

Returns:

Peer JAIN Sip Provider attached to this JainSipStack on specified ListeningPoint.

Throws:

IPPeerUnavailableException - thrown if the Peer class could not be found

ListeningPointUnavailableException - thrown if the ListeningPoint specified is not owned by this JainSipStack, or if another Provider is already using the ListeningPoint

java.lang.IllegalArgumentException - if listeningPoint is null

deleteProvider

public void deleteProvider(JainSipProvider providerToBeDeleted)
                    throws UnableToDeleteProviderException,
                           java.lang.IllegalArgumentException

Deletes the specified Peer JAIN SIP Provider attached to this JainSipStack. Note to developers: The implementation of this method should remove the specified Peer JAIN SIP Provider from the providerList.

Parameters:

providerToBeDeleted - the Peer JAIN SIP Provider to be deleted from this JainSipStack.

Throws:

UnableToDeleteProviderException - thrown if the specified Peer JAIN SIP Provider cannot be deleted. This may be because the Peer JAIN SIP Provider has already been deleted, or because the Peer JAIN SIP Provider is currently in use.

java.lang.IllegalArgumentException - if providerToBeDeleted is null

getProviders

public JainSipProvider[] getProviders()
                               throws SipException

Returns an array of existing Peer JAIN SIP Providers that have been created by this JainSipStackImpl. All of the Peer JAIN SIP Providers of this JainSipStack will be proprietary objects belonging to the same stack vendor.

Returns:

an array containing all existing Peer JAIN SIP Providers created by this JainSipStack.

Throws:

SipException - if JainSipStack has no Providers

getStackName

public java.lang.String getStackName()

Gets the name of this JainSipStack instance.

Returns:

a string describing the stack instance

setStackName

public void setStackName(java.lang.String stackName)
                  throws java.lang.IllegalArgumentException

Sets the name of this JainSipStack instance. This name should be unique to this instance of a vendor's implementation and optionally include a means to identify what listening points the stack owns.

Parameters:

stackName/var> - the stack name.

Throws:

java.lang.IllegalArgumentException - if stackName is null or zero-length