jain.protocol.ss7.tcap
Interface JainTcapStack

public interface JainTcapStack

This interface defines the methods required to represent a proprietary JAIN TCAP 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 JainTcapProviders and the implicit attaching/detaching of those JainTcapProviders to this JainTcapStack implementation.

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.ss7.tcap.JainTcapStack interface must be jain.protocol.ss7.tcap.JainTcapStackImpl .

Under the JAIN naming convention, the upper-level package structure (pathname) can be used to differentiate between proprietary implementations from different SS7 Vendors. The pathname used by each SS7 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 JainTcapStack will be located at:
. jain.protocol.ss7.tcap.JainTcapStackImpl
Where:
pathname = reverse domain name, e.g. com.sun'
The resulting Peer JAIN SS7 Object would be located at: com.sun jain.protocol.ss7.tcap.JainTcapStackImpl
An application may create a JainTcapStackImpl by invoking the JainSs7Factory.createJainSS7Object() 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 (with multiple SPCs) setStackName() can be used. An application can choose to supply any identifier to this method.

Note that a JainTcapStack represents a single SPC.

Version:

1.1

Author:

Sun Microsystems Inc.

See Also:

JainTcapProvider

Method Summary

void	attach(JainTcapProvider jainTcapProvider) Deprecated. As of JAIN TCAP v1.1. No replacement the attach of the JainTcapProvider occurs implicitly within the createProvider method of this interface.
JainTcapProvider	createAttachedProvider() Deprecated. As of JAIN TCAP v1.1. This method has been replaced by the createProvider method in this Interface.
JainTcapProvider	createDetachedProvider() Deprecated. As of JAIN TCAP v1.1. This method has been replaced by the createProvider method in this Interface.
JainTcapProvider	createProvider() Creates a new Peer (vendor specific) JainTcapProvider whose reference is exposed by this JainTcapStackImp.
void	deleteProvider(JainTcapProvider providerToBeDeleted) Deletes the specified Peer JAIN TCAP Provider attached to this JainTcapStackImpl.
void	detach(JainTcapProvider jainTcapProvider) Deprecated. As of JAIN TCAP v1.1. No replacement the detach of the JainTcapProvider occurs implicitly within the deleteProvider method of this interface.
int	getProtocolVersion() Deprecated. As of JAIN TCAP v1.1. This method has been replaced by getStackSpecification in the JainTcapStack Interface. Note: These get/set protocolVersion methods were deprecated to avoid confusion between the stack standards supported and the protocol version field supported by the ANSI 1996 Dialogue Portion
JainTcapProvider[]	getProviderList() Update v1.1: Changed return type of provider List from Vector to Array.
int[]	getSignalingPointCode() The Signaling Point Code can be implemented in one of the following 4 ways ITU_14bit - Split 3-8-3 across member/cluster/zone.
java.lang.String	getStackName() Returns the name of the stack as a string
int	getStackSpecification() Gets the stack Specification that this Stack is currently supporting.
java.lang.String	getVendorName() Returns the Vendor's name for this stack
void	setProtocolVersion(int protocolVersion) Deprecated. As of JAIN TCAP v1.1. This method has been replaced by setStackSpecification in the JainTcapStack Interface.
void	setStackName(java.lang.String stackName) Sets the name of the stack as a string
void	setStackSpecification(int stackSpecification) Sets the Stack specification that this Stack is to support.
void	setVendorName(java.lang.String vendorName) Sets the Vendors name for this stack, this name will be the Vendor's domain name inverted i.e.

Method Detail

getSignalingPointCode

public int[] getSignalingPointCode()

The Signaling Point Code can be implemented in one of the following 4 ways

ITU_14bit - Split 3-8-3 across member/cluster/zone.

ANSI_24bit - Split 8-8-8 across member/cluster/zone.

Chinese_24bit - Split 8-8-8 across member/cluster/zone.

Japanese_16bit - Split 5-4-7 across member/cluster/zone.
Note to developers: There is no setSignalingPointCode method visible in the JainTcapStack Interface for security reasons. By hiding the setSignalingPointCode method from applications, 3rd party vendors application developers will not be able to configure the signaling Point Code of a specific stack implemetation of the JAIN TCAP API, unless they use the JAIN OAM specification which provides a standard interface into provisioning the TCAP Layer of a SS7 stack.
A developer can alternatively implement a setSignalingPointCode method behind the JainTcapStack Interface and allow propreitory JAIN TCAP applications to cast this interface to their implementation in order to provision the Signaling Point Code.

Returns:

the signalingPointCode of this JainTcapStack.

createProvider

public JainTcapProvider createProvider()
                                throws PeerUnavailableException

Creates a new Peer (vendor specific) JainTcapProvider whose reference is exposed by this JainTcapStackImp. This method replaces the createAttachedProvider and createDetachedProvider methods, which have become deprecated in this interface.
Note to developers: The implementation of this method should add the newly created JainTcapProvider to the providerList once the JainTcapProvider has been successfully created and set the JainTcapStack reference in the newly create JainTcapProvider to this object.

Example:-
public JainTcapProvider createProvider() throws PeerUnavailableException {

try {

JainTcapProviderImpl myProvider = new JainTcapProviderImpl();

} catch(ClassNotFoundException err) {

throw new ss7PeerUnavailableException("Couldn't find peer");

}
myProvider.myStack = this;
return myProvider;

}

Returns:

Peer JAIN TCAP Provider referenced by this JainTcapStackImpl.

Throws:

PeerUnavailableException - thrown if the class is not found for a specific peer implementation

Since:

JAIN TCAP v1.1

createAttachedProvider

public JainTcapProvider createAttachedProvider()
                                        throws PeerUnavailableException,
                                               ProviderNotAttachedException

Deprecated. As of JAIN TCAP v1.1. This method has been replaced by the createProvider method in this Interface.

createDetachedProvider

public JainTcapProvider createDetachedProvider()
                                        throws PeerUnavailableException

Deprecated. As of JAIN TCAP v1.1. This method has been replaced by the createProvider method in this Interface.

deleteProvider

public void deleteProvider(JainTcapProvider providerToBeDeleted)
                    throws DeleteProviderException

Deletes the specified Peer JAIN TCAP Provider attached to this JainTcapStackImpl. Note to developers: The implementation of this method should remove the specified Peer JAIN TCAP Provider from the getProviderList.

Example:-
public void deleteProvider(JainTcapProvider providerToBeDeleted) throws DeleteProviderException {

if (null == providerToBeDeleted) { }
JainTcapProvider[] myProviderList = this.getProviderList();
for (int i=0; i<myProviderList.length; i++) {

if (providerToBedeleted == myProviderList[i]){

myProviderList[i] = null;

} else {

throw new DeleteProviderException("Couldn't find provider");

}

}
return;

}

Parameters:

providerToBeDeleted - the provider to be deleted

Throws:

DeleteProviderException - thrown if not such provider exists

attach

public void attach(JainTcapProvider jainTcapProvider)
            throws ProviderNotAttachedException

Deprecated. As of JAIN TCAP v1.1. No replacement the attach of the JainTcapProvider occurs implicitly within the createProvider method of this interface.

Deprecated attach and detach methods as the object reference signifying the attach/detach can be associated/nullified with the Provider upon creation and deletion.

detach

public void detach(JainTcapProvider jainTcapProvider)
            throws ProviderNotAttachedException

Deprecated. As of JAIN TCAP v1.1. No replacement the detach of the JainTcapProvider occurs implicitly within the deleteProvider method of this interface.

getProviderList

public JainTcapProvider[] getProviderList()

Update v1.1: Changed return type of provider List from Vector to Array. Returns the array of Peer JAIN TCAP Providers that have been created by this JainTcapStackImpl. All of the Peer JAIN TCAP Provider s of this JainTcapStackImpl will be proprietary objects belonging to the same stack vendor.

Returns:

an JainTcapProvider Array containing all the of Peer JAIN TCAP Providers created by this JainTcapStackImpl.

getStackName

public java.lang.String getStackName()

Returns the name of the stack as a string

Returns:

a string describing the Stack Name

setStackName

public void setStackName(java.lang.String stackName)

Sets the name of the stack as a string

Parameters:

stackProtocol - The new Stack Name value

getVendorName

public java.lang.String getVendorName()

Returns the Vendor's name for this stack

Returns:

a string describing the Vendor's name

Since:

JAIN TCAP v1.1

setVendorName

public void setVendorName(java.lang.String vendorName)

Sets the Vendors name for this stack, this name will be the Vendor's domain name inverted i.e. "com.sun" similar to the path name of the JAIN Factory.

Parameters:

vendorName - The new Vendor's Name

Since:

JAIN TCAP v1.1

getProtocolVersion

public int getProtocolVersion()

Deprecated. As of JAIN TCAP v1.1. This method has been replaced by getStackSpecification in the JainTcapStack Interface. Note: These get/set protocolVersion methods were deprecated to avoid confusion between the stack standards supported and the protocol version field supported by the ANSI 1996 Dialogue Portion

setProtocolVersion

public void setProtocolVersion(int protocolVersion)
                        throws TcapException

Deprecated. As of JAIN TCAP v1.1. This method has been replaced by setStackSpecification in the JainTcapStack Interface.

getStackSpecification

public int getStackSpecification()

Gets the stack Specification that this Stack is currently supporting.

Note to developers :- This should not be confused with the protocol version field supported by the ANSI 1996 Dialogue Portion.

Returns:

the current Protocol Version of this stack. This may be one of the following values:

• STACK_SPECIFICATION_ANSI_92
• STACK_SPECIFICATION_ANSI_96
• STACK_SPECIFICATION_ITU_93
• STACK_SPECIFICATION_ITU_97

These values are defined in the TcapConstants class.

Since:

JAIN TCAP v1.1 Note: These get/set protocolVersion methods were deprecated to avoid confusion between the stack standards supported and the protocol version field supported by the ANSI 1996 Dialogue Portion

setStackSpecification

public void setStackSpecification(int stackSpecification)
                           throws VersionNotSupportedException

Sets the Stack specification that this Stack is to support. Invoking this method should initially configure the stack to support the given specification if the specification supported has not already been set. In the event that this Stack is already supporting a specification other than the supplied specification, then the Stack will change the supported specification if possible, or throw an Exception if this is not possible.

Note to developers :- This should not be confused with the protocol version field supported by the ANSI 1996 Dialogue Portion.

Parameters:

stackSpecification - one of the following values:

• STACK_SPECIFICATION_ANSI_92
• STACK_SPECIFICATION_ANSI_96
• STACK_SPECIFICATION_ITU_93
• STACK_SPECIFICATION_ITU_97

Throws:

VersionNotSupportException - thrown if the supplied stack specification cannot be supported by this Stack, or if the Stack cannot change supported stack specifications because it is not in a idle state.

Since:

JAIN TCAP v1.1

See Also:

TcapConstants