Bootstrap Interfaces Definition by Leveraging OSS Common JSR Design and Shared Entities

Articles Index

Operations Support Systems (OSS) enable telecommunications companies to manage, monitor and control telecommunications networks. Billing, customer care systems, directory services, inventories, network elements and network management are all Operational Support Systems. Service management considerations include handling new customers and service activation with subsequent service assurance. Service management is always looking to minimize the costs of introducing new services and of changing existing ones.

This article provides users with guidelines about how to extend the OSS Common API. The OSS Common API was developed through the Java Community Process(JCP) as Java Specification Request (JSR) 144. There are several different JSRs related to OSS which have already been completed and, at the time of writing, more are either in progress or planned. The purpose of JSR 144 is to provide a standardized set of APIs for use by all the different OSS specifications for the Java platform. The other OSS implementations will then be able to extend this common set of APIs, thereby avoiding unnecessary and wasteful duplication of the base interfaces and classes, such as data types and exception definitions.

To be a truly common API for OSS, the OSS Common API implements the OSS Design guidelines, which are a set of Java Enterprise Edition (Java EE) patterns applied to Java APIs. The ultimate goal of these patterns is to reduce the integration nightmare by standardizing a subset of the interfaces between applications.

All the domain-specific APIs under the OSS technologies section on jcp.org inherit from the implementation of the design guidelines defined by JSR 144. JSR 144 also provides the definition and implementation of all the components (also called Core Business Entities (CBE)) that are shared, manipulated, extended and managed between all the interfaces. These ready-made implementations are available to users to extend as they need. Generic objects can be used or shared between specific implementations, and these objects can be assembled by the containment relations, which are also defined by JSR 144, to create application models.

In this article, the term "Entity" refers to a component of the CBE model that is implemented as a Plain Old Java Object (POJO). "EJB entity bean" will be used to represent the persistent business object in the Java EE SDK.

The problems solved by the OSS Common API are the following:

• Uniform definition of the base classes for use by all OSS applications
  
• Avoidance of duplication of shared objects
  
• Removal of the need to start every new OSS specification or implementation from scratch

Note also that the Reference Implementation (RI) for the OSS Common API has completed the Java Application verification Kit (AVK) for the Enterprise testing process. This guarantees that the RI does not depend on non-portable Java EE application server features.

Extending JSR 144 dramatically reduces the definition and implementation of domain-specific interfaces by providing the minimum/base set of components. Developers can therefore focus on operations and possible extension of components.

In order to extend the OSS Common API you need to consider the following steps:

1. List the entities that the interface (API) will manipulate. An entity is composed of a value and a key. These components can be organized to follow a domain-specific standard or a vendor-specific model. They should be implemented as extensions of the CBEs specified in JSR 144. This list will later be used to define and implement the necessary factory for entities and query definitions.
   
2. List the actions or interactions (business methods) that the interface will expose and that will be implemented by the Java EE application. These methods will mainly handle the previously-defined entity values and keys.
   
3. Determine the granularity of the client interface, namely the number and name of the EJB session and EJB entity beans.
   
4. List the asynchronous information and events that the implementation will publish or receive.
   
5. Finally, implement the Java API definitions by extending the base interface javax.oss.JVTSession and the CBEs from the JSR 144 definitions.

This chapter lists some constraints related to the Java implementations of CBE. Then it gives the extension rules, according to the steps described above.

Programming Restrictions for the Value Types

If Clients access the APIs by using the Java Value Type interface, the byte code of the Value types will be executed in the Java virtual machine¹ of the Client.

The environment of the Client is different from the environment of the OSS API implementation (the deployed application). Therefore, the implementation of the Value types must take the following into account:

• Follow the programming restrictions of EJB code. This is required if the Client is an EJB. Note that you are not allowed to use the full Java Platform, Standard Edition (Java SE) APIs.
  
• Do not use any API that is not part of the Java SE platform.

Constraints on Types

An implementation supports a certain set of Entity Types. Each Entity Type has attributes that describe the Entity. Depending on the Entity Type, not all attribute values  are valid. It is recommended that you deal with the attribute value constraints as follows:

• Attribute value constraints are checked on the provider side (the deployed application). This means that all the methods of the Session Bean that creates the Entities should include the logic to verify that the attribute values are valid.
  
• Minimum attribute value checks should be done when calling set methods of the Value objects.

By doing this, the complete verification mechanism (or logic) is centralized in one place, in the Session Bean implementation. Only the Session Bean is expected to have all the necessary information to verify all the attribute values. The Session Bean is thus able to perform intra- and inter-object checks. If the attribute values violate any constraint, a java.lang.IllegalArgumentException is raised by the implementation.

Java EE and Portability Considerations

Any implementation/extension must follow the Java EE specifications. The Application Verification Kit (AVK) tool and the  Java Power for Enterprise program, both of which are available at the Java Platform, Enterprise Edition (Java EE) home page, provide the means to ensure a Java EE implementation that is correct and portable.

Any implementation and extension of JSR 144 must also pass the static and dynamic part of the Java EE AVK. Once done, the results can be published through the Java Powered for the Enterprise Program.

NOTE: The TCK of the API is used to run the dynamic part the AVK.

Implementations require the extension of this model to map specific information models, whether related to industry standards or not. The model must be extended by sub-classing the core model entities, specifications or associations. The following diagram shows how the entities are extended, using the existing OSS API as an example:

How Entities Are Extended, Using the Existing OSS API as an Example

The following is an example of extension for a Service definition:

Package com.infomodel;

Class MplsVpnServiceValueImpl implements Com.infomodel.MplsVpnServiceValue {
...
}
Package com.infomodel;
Interface MplsVpnServiceValue extends javax.oss.cbe.ServiceValue{
...
}

Package javax.oss.cbe.service ;
Interface ServiceValue extends javax.oss.cbe.EntityValue{
...}

Package javax.oss.cbe ;
Interface EntityValue extends javax.oss.CBEManagedEntityValue{
...} 

New Entity Types

The entity model is extended by specialization. The specification requires that all extensions must extend one of the Value types, namely, XXXValue components and their corresponding key, namely, XXXKey.

Every extended Value type interface must follow the standard JavaBean property patterns, by implementing the get and set methods. They must also respect the inheritance mechanism.

For example, the following Java code extends a ManagedEntityValue interface:

Package a.b.c;
public interface XXXValue extends
javax.oss.ManagedEntityValue
{
public static final String VALUE_TYPE = "a.b.c.XXXValue";
// as return by XXXValue.class.getName();
...
}


Package a.b.c;
public interface XXXKey extends
javax.oss.ManagedEntityKey
{
...
} 

The implementation must inform the Client that it supports this extended type and it must also create an instance of the new type. This is done with the getManagedEntityTypes() operations from the javax.oss.JVTSession EJB, which returns the new constant XXXValue.VALUE_TYPE, for example.

Also, the makeManagedEntityValue(Stringtype) in the JVTSession interface definition creates a new instance if the input parameter is set to XXXValue.VALUE_TYPE.

For query values, the constant identifying the query is named QUERY_TYPE. It must be used to declare the query type in the same way as entities are declared.

Controlled Attributes

An implementation can extend the definition of an Entity by adding additional Client attributes to the Entity definition; these attributes are controlled by the Client or by the implementation.

The same constraints as for Entity (Chapter: Extending the Entity Model above) apply to named query and update procedures.

The new named query type must declare and implement the public final static String QUERY_TYPE.

The NamedQueryValue and NamedQueryResponse interfaces defined in a specific implementation of a specific API must be compliant with the following rules:

• The <QueryName> QueryValue interface must derive from the javax.oss.NamedQueryValue interface
  
• A <QueryName> QueryResponse interface must be provided for each <QueryName>QueryValue type.
  
• The <QueryName> QueryResponse interfaces must derive from the javax.oss.NamedQueryResponse

The update procedure type must declare and implement the public final static String UPDATE_TYPE.

The UpdateProcedureValue and UpdateProcedureResponse interfaces defined in a specific API definition must be compliant with the following rules:

• The <UpdateProcedureName> Value interface must derive from the javax.oss.UpdateProcedureValue interface
  
• An <UpdateProcedureName> Response interface must be provided for each <UpdateProcedureName> Value type.
  
• The <UpdateProcedureName> Response interfaces must derive from the javax.oss.UpdateProcedureResponse

The OSS application provides particular functions that can be activated through simple operations that are also called business methods. The basic set of business methods, for manipulating entities (CBEs) are Create, Retrieve, Update and Delete (CRUD).

The JVT Session already provides the base interface definition to perform/implement these basic operations. The developer will only have to focus on the specific or extended operations.

An application can expose a large variety of functionalities. These are grouped per sub-domain or per component into an independent set of client-dedicated interfaces, which are also called session beans in Java EE terminology.

Implementation Classes

The OSS Common API defines the following Session Bean and Local Session Bean interfaces. The base JVTSession interfaces provide a common set of operations shared by all the session Beans. The implementation of the JVTSession operations is mandatory.

Interface names:

• JVTSession
  
• JVTLocalSession

These interfaces provide specification for modeling Session Beans with parameters of the Entities type. This type of Session Bean provides access to the entities as Java Value Objects.

Extending Session Beans

The purpose of the JVTSession and JVTLocalSession Beans is to add additional domain-specific operations to the Session Beans.

The JVTSession or JVTLocalSession interface extension must follow the Enterprise JavaBeans Specification Version 2.1.

The client of an extended JVT session bean can be a remote client or a local client, depending on whether the client makes use of the enterprise bean's remote or local client view interfaces. An implementation can define the JVT bean usage by declaring/implementing either one or both of the JVT session interfaces.

Note: The differences between remote and local clients are discussed in Sections 5.2 through 5.4 of the Enterprise JavaBeans Specification, Version 2.1.

Events are extended by specialization. Clients that recognize the standard events will be able to understand the extended events as well. This is the minimum expected behavior of the implementations, when dealing with extensions to the base Event Model.

All Events emitted by an implementation must be derived from either the base interface of OSS, javax.oss.Event, or one of its sub-interfaces as defined in this specification. An implementation must not emit other event types.

Extending the Event and EventPropertyDescriptor Interfaces

An Event object already includes:

• The time when the event was emitted,
  
• The ApplicationDN (Distinguish Name) that identifies the emitter of the event,
  
• The class and the instance identifier of the concerned object.

The user might want to add specific attributes by defining new getXxx() and setXxx method definitions.

The corresponding EventPropertyDescriptor interface also extends the base javax.oss.EventPropertyDescriptor to document and specify the new filterable properties of the new event definition that was mentioned previously.

The name of the specific EventPropertyDescriptor interface should be <EventType>EventPropertyDescriptor where <EventType> is the name of the new event interface.

The event descriptor definition must at least contain the definition of the supported event type as a public final static string, following the example below:

public interface AlarmEventPropertyDescriptor extends
EventPropertyDescriptor {
...
public static final String EVENT_TYPE_VALUE = AlarmEvent.class.getName();
...
} 

The OSS Common API provides the foundation to other OSS domain-specific specifications and implementations. JSR 144 provides a neutral  Java EE interface to get the base of agile OSS applications.

The specification provides guidelines on how to implement the Runtime Client as well as guidelines on how developers can share Core Business Entities into an application by means of an API -- without limitation.

And finally, you will find in the specification how the Java API is mapped using the XML and JMS technologies to offer the same level of functionality for loosely-coupled integration.

• JSR 144 OSS Common API
  
• Download the JSR 144 Reference Implementation
  
• OSS through Java Initiative
  
• OSS Technology JSRs
  
• How Core Business Entities Integrate with the Common API and Relate to the SID. (PDF)

¹ As used on this web site, the terms "Java virtual machine" or "JVM" mean a virtual machine for the Java platform.