JAIN OAM Release 1.0 Requirements Specification

3 Requirements Definition

3.1 The JAIN OAM Object Model

JAIN is built upon standardized JavaTM APIs and Object technology. In Object Technology, data and programming logic are treated as objects. Unlike traditional computer programs, objects can be readily integrated into a running environment, accessed and managed remotely; debugged and maintained in live systems by standardized interfaces such as the JavaTM Management Extension (JMX).

A JAIN OAM application can be either a traditional JavaTM program or a JavaBean, where a JavaBeanä is a reusable software component/object. While JAIN does not mandate that all applications must be built as JavaBeans, the design of the API specification will not exclude any application from executing as a JavaBean. The unifying features of a JavaBean are explained with examples in [Reference 5].

The main points are:

Introspection: Can be used by an application builder tool to discover the properties, methods and Events of a JAIN OAM object.
Customization: Allows an operator to dynamically change the properties of a JAIN OAM object at run time using an application builder tool.
Events: Can be used to send OAM messages between JAIN OAM objects.
Persistence: Allows the state of a JAIN OAM object to be stored for retrieval at a later time.

The three most important features of a JavaBean are:

Property Management: Properties are named attributes associated with a bean that can be read or written by calling appropriate methods on the bean.
Method Management: The methods a JavaBeanä exports are standard and extended Java methods which can be called from other objects or from a scripting environ-ment, such as HTML invoking an applet. By default, all of the bean's public methods will be exported.
State Management: Events provide a way for one object to notify other objects that a change in state has occurred. Under the JavaTM Event model an Event Listener object can be reg-istered with an Event source. When the Event source detects a state change it will call the appropriate method on the Event Listener object.

REQ-OM-01-01: The API shall adhere to the JavaBeansä Model (Reference [6]).

If the API is implemented using JavaBeansä it offers the advantage of using the Beans as reusable objects in a plug and play fashion.

REQ-OM-02-01: The API implementation shall not be restricted to JavaBeansä .

This permits the API to be implemented in standard Javaä code, such as a program, applet or servlet.

3.2 JAIN OAM Naming Convention

JAIN OAM objects must conform to a specific naming convention in order to support JavaBeanÔ implementation. For a JavaBean to expose a property i.e. within a visual tool, it must supply a ‘get’ method to read the property value and/or a ‘set’ method to write the property value. These ‘get’ and ‘set’ methods have the following signature:

public < PropertyType> get< PropertyName>();

public void set< PropertyName>(< PropertyType> a);

If we discover a matching pair of "get<PropertyName>" and "set<PropertyName>" methods that take and return the same type, then we regard these methods as defining a read-write property whose name shall be "<propertyName>". For a Boolean property the ‘get’ method signature changes to:

public boolean is< PropertyName>();

REQ-NC-01-01: The API shall follow the JavaBeanä naming convention (Reference [6]).

3.3 Managed Object Requirements

REQ-MO-01-01: The API shall define Protocol Layer Managers for the following protocol layers:

TCAP

SCCP

MTP Level 3

MTP Level 2

Each MO defined in the API shall be classified as belonging to a particular protocol layer. This classification will permit a logical grouping of Managed Objects based on the protocol layers of an SS7 Stack. For each protocol layer a 'Protocol Layer Manager' shall control the creation and deletion of all MOs belonging to that layer. The Protocol Layer Manager shall allow an application to register as an Event Listener for all of the MOs belonging to that protocol layer, however remember certain managed objects span more than one layer or more than one vertical functional division [e.g. a Signaling Point].

REQ-MO-02-01: Each Protocol Layer Manager shall have a set of methods defined in the API for the creation and deletion of MOs belonging to that layer.

If an application wishes to create or delete a MO it will request the operation from the Protocol Layer Manager.

REQ-MO-03-01: Each Protocol Layer Manager shall have a 'readCurrentConfiguration()' method defined within the API.

The implementation of this method shall read the current system configuration, create the appropriate MOs and set the attribute values for the MOs to reflect the current stack configuration. This method can be used if a protocol stack is already configured when a JAIN OAM application begins to execute. This method shall either return successfully (returning void) or throw an exception if an error is encountered.

REQ-MO-04-01: Each Protocol Layer Manager shall have a 'commit()' method defined within the API.

The implementation of this method shall commit all operations to the underlying proprietary management system.

Successfully invoking the 'commit()' command shall have three separate consequences:

When an application requests the creation of a MO from a Protocol Layer Manager, the Protocol Layer Manager should create the appropriate MO. Only when the commit() method has been invoked should the corresponding network element be created in the underlying proprietary management system.

When the attributes of a MO are modified, the attribute values will be changed in that MO. Only when a commit() method has been invoked shall the changes be propagated to the corresponding network element.

When an application requests the deletion of a MO from a Protocol Layer Manager, that MO should be tagged for deletion from the system, but the corresponding network element should not be deleted from the underlying proprietary management system until a commit() method has been invoked.

REQ-MO-05-01: The 'commit()' method shall throw an Exception if any of the operations were not successfully committed.

This Exception shall contain a string listing the operations to be committed and whether or not they were successfully committed. This string shall take the format of:

1 : <ManagedObject> : <operationRequested> : <SUCCESS | FAILURE> ;

2 : <ManagedObject> : <operationRequested> : <SUCCESS | FAILURE> ;

……. ……… ……..

N : <ManagedObject> : <operationRequested> : <SUCCESS | FAILURE> ;

Eg.

1 : Route : setDestinationPointCode : SUCCESS ;

2 : Route : setPriority : SUCCESS ;

3 : LinkSet : setDestinationPointCode : SUCCESS ;

3 : LinkSet : addLink : FAILURE ;

REQ-MO-06-02: The API shall define the following MOs for the TCAP layer:

TCAP

A standard set of network components that Stack management systems must monitor and configure does not exist for TCAP. The set of MOs defined for JAIN OAM Release 1.0 represents a common subset of network components that are monitored and configured by most Stack management systems. At the TCAP layer, a TCAP MO shall be defined to represent a local TCAP layer. Where a number of logical local signalling points exist within the one physical stack, one TCAP MO shall exist for each logical TCAP layer.

REQ-MO-06.1-02: The TCAP MOs shall support the containment hierarchy outlined in Figure 3.0

Figure 3.0 - The TCAP MO containment hierarchy

REQ-MO-07-02: The API shall define the following MOs for the SCCP layer:

SCCP Routing Control

Global Title Entry

SCCP Entity Set

Local Subsystem

Remote Subsystem (SCCP Service Access Point)

Concerned Area

SCCP Timer Profile

REQ-MO-08-02: The SCCP MOs shall support the containment hierarchy outlined in Figure 3.1

Figure 3.1 - The SCCP MO containment hierarchy

REQ-MO-09-02: The API shall define the following MOs for the MTP-3 layer:

Own Signalling Point

Remote Signalling Point (MTP3 Service Access Point)

Signaling Link

Signaling Linkset

Signaling Route

Signaling Routeset

Screening Table

MTP-3 Timer

REQ-MO-10-02: The MTP-3 Layer Managers shall support the containment hierarchy outlined in Figure 3.2

Figure 3.2 - The MTP-3 Layer Manager containment hierarchy

REQ-MO-11-02: The API shall define the following MOs for the MTP-2 layer:

MTP2 Service Access Point
MTP-2 Timer

REQ-MO-12-02: The MTP-2 Layer Managers shall support the containment hierarchy outlined in Figure 3.3

Figure 3.3 - The MTP-2 Layer Manager containment hierarchy

REQ-MO-13-01: The API shall define a set of attributes for each Managed Object.

These attributes will be used for storing the characteristics of that Managed Object. For each MO a set of parameters fully describe it. These parameters are called the attributes of the MO. Specific values of the attributes define the characteristics of a specific instance of the MO. Each attribute of a MO can be one of many valid values, a particular combination of attribute values for a MO will be referred to as an instance of that MO.

REQ-MO-14-01: The API shall ensure that the attribute values are within the range of allowable values for that attribute if they have been defined in an international standard.

For some attribute values a range of legal values have been specified in international standards. Attempting to set the attribute value to a value outside of this range will throw an Exception.

REQ-MO-15-02: The API shall provide a means to constrain the maximum number of instances of a particular MO that may exist within an implementation.

A proprietary stack management system may specify, for a particular Managed Object, a maximum number of instances that may exist simultaneously.

REQ-MA-18-01: An application shall have the ability to register as an Event Listener for more than one protocol layer.

For the purposes of the JAIN OAM API specification Release 1.0, an application may either register as an MTP-2, MTP-3, SCCP or TCAP Event Listener or any combination of these. By registering as an Event Listener of a particular protocol layer, an application indicates that it is only interested in receiving Events relating to MOs belonging to that protocol layer. By registering as an Event Listener of many layers, an application indicates that it is interested in receiving Events from all MOs belonging to all of those layers.

3.4 Event Requirements

3.4.1 Alarm Event Requirements

REQ-EV-01-01: The API shall provide an Alarm Event delivery mechanism to inform registered applications when the state of a MO changes.

REQ-EV-02-02: When a change of state occurs within an MO, the MO shall send an Alarm Event to all Alarm Event Listeners registered with that MO.

For example, if the attributes of a Link MO are changed, Alarm Events will be sent to all MTP-3 Event Listeners registered with that MO. A management application registered as an Alarm Event Listener of the Link MO will receive the Alarm Event. Furthermore, within an implementation of the API, a particular MO may also be registered as an Alarm Listener of other MOs. For example, a Linkset MO may register as an Alarm Listener of a Link MO.

REQ-EV-03-01: All Alarm Events shall be timestamped.

An application may wish to record the Events received in a log-file or present them to an operator in a display window. By including a timestamp, an application can record the sequence in which the Alarm Events are received.

REQ-EV-04-01: A priority shall be associated with each Alarm Event.

This will allow an application to process received Events according to their priority within the system.

REQ-EV-05-01: The priority may be one of the following:

Informational:

Indicates that the state of a MO has changed as a result of circumstances other than an operation by a Manager. The cause of this Event does not affect the functional state of the system and may be ignored. This priority of Event shall be helpful for system diagnostics or for verification of any faults occurring in the system.

Low:

Indicates that the state of a MO has changed as a result of an operation by a Manager.

High:

Indicates that the physical network element associated with the MO that caused the Event has gone out of service. Without corrective action, service reliability can be severely affected.

Critical:

Indicates the complete failure of the physical network element associated with the MO that caused the Event.

3.4.2 Measurement Event Requirements

REQ-MR-01-01: A category shall be associated with each Statistic Event.

This will allow an application to process received Events according to their priority within the system.

REQ-MR-02-01: The category may be one of the following:

Fault Management:

Fault management encompasses fault detection, location, isolation and the correction of abnormal operation of the SS7 network.

Configuration Management:

Configuration management controls the resources of, and collects and provides data for, the signaling network and its components.

Performance Management:

This enables the behavior of network resources and the effectiveness of communication activities in the network to be evaluated.

REQ-MR-03-01: The API shall provide a means to collect all statistics listed in Table 3.1

The suggested measurements represent the obligatory ITU measurements for monitoring an SS7 network for MTP, SCCP and TCAP protocol layers as outlined in the ITU standard for monitoring and control of an SS7 network.

No.	ITU Ref	Description of Measurements	Protocol	Measuring
	1.1	Duration of link in the In-service state	MTP	Signal Link Points and Performance
	1.2	SL failure - All reasons	MTP	Signal Link Points and Performance
	1.8	Number of signal units received in error	MTP	Signal Link Points and Performance
	2.1	Duration of SL unavailability (for any reason)	MTP	Signaling Link availability
	3.1	Number of SIF and SIO octets transmitted	MTP	Signaling Link Utilization
	3.4	Number of SIF and SIO octets received	MTP	Signaling Link Utilization
	3.10	MSUs discarded due to SL congestion	MTP	Signaling Link Utilization
	4.9	Unavailability of route set to a given destination or set of destinations	MTP	signaling link set and route set availability
	4.10	Duration of unavailability in 4.9	MTP	signaling link set and route set availability
	5.1	Adjacent SP inaccessible	MTP	signaling point status
	5.2	Duration of adjacent SP inaccessible	MTP	signaling point status
	5.5	MSU discarded due to a routing data error⁾	MTP	signaling point status
	7.1	Routing Failure - No translation for address of such nature)	SCCP	SCCP error performance
	7.2	Routing Failure - No translation for this specific address)	SCCP	SCCP error performance
	7.3	Routing Failure - Network Failure (Point Code not available)	SCCP	SCCP error performance
	7.4	Routing Failure - Network Congestion	SCCP	SCCP error performance
	7.5	Routing Failure - Subsystem Failure (unavailable)	SCCP	SCCP error performance
	7.6	Routing Failure - Subsystem Congestion	SCCP	SCCP error performance
	7.7	Routing Failure - Unequipped user (Subsystem)	SCCP	SCCP error performance
	7.8	Syntax Error Detected	SCCP	SCCP error performance
	7.9	Routing Failure - Unqualified	SCCP	SCCP error performance
	7.10	Reassembly error - Timer T_reass expiry	SCCP	SCCP error performance
	7.11	Reassembly error - Segment received out of sequence (inc. duplicates, recpt. of non-first segment for which no reassembly process)	SCCP	SCCP error performance
	7.12	Reassembly error - No reassembly space	SCCP	SCCP error performance
	7.13	Hop counter violation (XUDT, XUDTS, LUDT, LUDTS and CR)	SCCP	SCCP error performance
	7.14	Message too large for segmentation	SCCP	SCCP error performance
	7.15	Failure of release complete supervision	SCCP	SCCP error performance
	7.16	Timer T(iar) expiry	SCCP	SCCP error performance
	7.17	Provider initiated reset of a connection	SCCP	SCCP error performance
	7.18	Provider initiated release of a connection	SCCP	SCCP error performance
	7.20	Segmentation error - Segmentation failed	SCCP	SCCP error performance
	9.6	Total (L)(X)UDT messages originated per class and source SSN	TCAP	Utilization
	9.7	Total (L)(X)UDT messages terminated per class and sink SSN	TCAP	Utilization
	13.1	bisTotal number of TC messages sent by the node	TCAP	Local TC utilization
	13.2	bisTotal number of TC messages received by the node	TCAP	Local TC utilization
	14.1	Protocol error detected in transaction portion (abort received) - with P-abort cause: d)unrecognized TID e)resource limitation	TCAP	TC fault measurements
	A.1	Protocol error detected in transaction portion (abort received) - with P-abort cause: a)unrecognized message type b)incorrect TP c)badly formatted TP	TCAP	TC fault measurements
38	A.2	Protocol error detected in component portion (reject received) - with problem code: a)unrecognized component (general problem) b)mistyped component (general problem) c)badly structured component (general problem)	TCAP	TC fault measurements

Table 3.1 - JAIN P&M Measurements

REQ-MR-04-01: The API shall provide a Statistic Event delivery mechanism to inform registered applications when a measurement is complete.

Each Layer Manager shall send statistic events to all Statistic Listeners registered with it.

3.4.3 Error Event Requirements

REQ-EE-01-01: The API shall provide an Error Event delivery mechanism to inform registered applications when a system error occurs

REQ-EE-02-01: When a system error occurs within an MO, the MO shall send an Error Event to all Error Event Listeners registered with that MO.

3.5 JAIN OAM Event Processing

JAIN OAM Events (resulting from a change in state occurring within an MO) are passed from the MO) to applications (EventListeners) as Event Objects. Event handling methods defined in the EventListener interface conform to a standard naming convention:

void <eventOccurenceMethodName>(<EventStateObjectType> event);

where the <EventStateObjectType> is a subclass of java.util.EventObject.

The MOs (Alarms and Errors) and Layer Managers (Statistics) will provide methods for registering and de-registering Listener applications, which allow applications to establish an Event flow from all MOs and Layer Managers to the Listener application. The standard naming convention for Listener registration is:

public void add< ListenerType>(< ListenerType> listener)

throws java.util.TooManyListenersException,

throws java.util.ListenerAlreadyRegisteredException;

When this method is invoked, it depends on the implementation of the JAIN OAM specification, whether or not the TooManyListenersException is thrown, however the ListenerAlreadyRegisteredException should always be thrown if the Listener tries to register more than once with the same protocol layer.

public void remove< ListenerType>(< ListenerType> listener);

throws java.util.ListenerNotRegisteredException;

The ListenerNotRegisteredException should always be thrown if a removeListener() method is invoked by a Listener, and the Listener is not registered with that Object.

An overview of the JAIN OAM Event Processing model is illustrated in Figure 3.9.

Figure 3.9 – An overview of the JavaBeanä Event model in JAIN OAM

Invoking the add<ListenerType> method adds the given Listener to the set of Event Listeners registered for Events associated with the <ListenerType>. Similarly invoking the remove<ListenerType> method removes the given Listener from the set of Event Listeners registered for Events associated with the <ListenerType>.

If you have any comments on these webpages or content, please send them to:
JainOam@East.Sun.Com
Copyright - 1999 Sun Microsystems