Development API Reference

The Development API is the Common Object Request Broker Architecture (CORBA)-based application program interface (API) to ss. You can also refer to it as the ss Object Request Broker (SSORB) interface or SSORB, because it depends on an object request broker (ORB). This section explains the purpose of the Development API, what it consists of, and what you can do with it.
casp1032
The Development API is the Common Object Request Broker Architecture (CORBA)-based application program interface (API) to 
SpectroSERVER
. You can also refer to it as the 
SpectroSERVER
 Object Request Broker (SSORB) interface or SSORB, because it depends on an object request broker (ORB). This section explains the purpose of the Development API, what it consists of, and what you can do with it.
See the Release Information section for notifications of release-specific changes (if any) to the Development API interface.
 
 
Architecture
The Development API advertises through the CORBA Naming Service. Advertising through the CORBA naming service facilitates compatibility with other ORBs such as Orbacus and Java that support the standard Naming Service.
Client applications contact the Naming Service to retrieve the list of available services. You can view the list by using the 
osfind
 tool or the 
nsutil
 tool for the Naming Service list. Once the client application contacts an advertiser and gets the location of the required service, the client application can contact that service directly. Calls for data retrieval are possible after security checks are cleared.
Native threads handle incoming data requests at the VisiBroker CORBA layer. The requests then queue for 
SpectroSERVER
 processing.
The 
SpectroSERVER
 takes the first request off the queue and retrieves the required data. The data is attached to the outgoing queue to return to the client application. In the case of asynchronous data or callbacks, the 
SpectroSERVER
 maintains an active list of changes and notifies the client application about them. On multi-CPU systems where client applications implement callbacks, this workload is redistributed among native threads, freeing up processing cycles.
The Development API has the following architecture:
  image2014-10-16 12:12:47.png  
In this architecture, the Location Server, 
SpectroSERVER
, and Archive Manager (not pictured) each have a CORBA interface for data retrieval. The Location Server provides the list of 
SpectroSERVER
s available in the distributed 
SpectroSERVER
 domain. 
SpectroSERVER
 handles the interfaces to the model domain, alarm domain and type catalog. The Archive Manager handles the event domain.
When the 
SpectroSERVER
, Location Server, or Archive Manager starts up, it advertises its services to the Naming Service.
The CORBA Standard
CORBA is a standard developed by the Object Management Group (OMG) consortium. The CORBA standard is a middleware, a framework that specifies how distributed applications can communicate using an ORB.
The following illustration shows client-server communication through an ORB:
  image2014-10-16 12:13:21.png  
The ORB facilitates communication between software components coded in different languages for different operating systems with different hardware architectures. It enables disparate objects on the network to recognize each other and invoke each other's methods.
The ORB is not a product; it is an implementation of OMG's CORBA standard. The CORBA standard defines the Interface Definition Language (IDL) used to describe the following:
  • Interfaces to CORBA objects
  • Programming language mappings
  • Transport protocols
  • High level services like naming and security
The CORBA Mechanism
The CORBA component that facilitates communication between remote applications is the IDL that defines an API. The 
SPECTRUM Development API
 consists of an IDL file for each object type. This set of IDL files is usually referred to as the 
DX NetOps Spectrum
 IDL.
 The term IDL can also describe an interface.
CORBA defines a language mapping for every programming language. The language mapping describes how an IDL converts into the language-specific API. An IDL compiler implements this mapping by compiling an IDL file into a set of stubs and skeletons. 
Stubs
 are the methods and objects that an application can use; 
skeletons
 are empty methods and objects that you fill in to implement a server. The IDL generates stubs and skeletons while a vendor provides the ORB.
A programmer who creates a CORBA service object defines the interface in a CORBA-standard language, namely the IDL. If the IDL is run through the appropriate compilers, it produces both server and client code in standard programming languages. The server code is the skeleton because it represents a basic object as an abstract class from which the programmer derives a class to implement a service. The client code consists of a set of object reference stubs, which need no further coding.
For example, for a C++ mapping, the stubs include the header files used to compile the application and the object library linked to the application.
The application and server should link to the ORB library as shown in the following diagram:
  image2014-10-16 12:13:37.png  
To develop a server, you need to write the IDL and the implementation inside the skeletons. To develop an application, you need to call the stubs.
A program participating in the CORBA framework relies on its local ORB to overcome the communication barriers of language and process location. The program sends requests and gets responses to and from a data pipeline composed of all the ORBs in the system. This network of ORBs is often referred to as the ORB.
Each CORBA service resides on some computer and is implemented as an object coded in a programming language. To make itself available to clients, the object advertises its services through the ORB. A naming service (a standard CORBA service) picks up the advertisements and records the service name and object reference. If a client wants to use the service, it specifies the service name and contacts the naming service through the ORB. It receives the object reference and uses it to access the object's services.
The object reference and its corresponding server object are instances of different classes with the same interface. An object reference, obtained by the client from the naming service, executes on the client. The server object resides on the server. If a client invokes an object reference method, the method uses the ORB to call the corresponding method on the server. This server method fulfills the service request and returns the required data. For the client, the local object reference simulates the server object, but actually, the reference only does remote method invocations to the server.
Why 
DX NetOps Spectrum
 Uses CORBA
The Development API uses CORBA to focus on Java application development.
Use of Java in web-based applications is increasing. The 
SPECTRUM Development API
 focuses more on Java though it provides the same set of core services to both C++ and Java developers.
CORBA, an open standard, is best suited for Java application development. CORBA helps 
DX NetOps Spectrum
 customers write CORBA applications that integrate 
DX NetOps Spectrum
 with other CORBA services.
CORBA Sources
OMG publishes CORBA standard sections that cover the architecture and the language-specific mappings of CORBA. These standards are available at http://www.omg.org.
You can also get CORBA information from Borland Software Corporation, the vendor of VisiBroker ORB that 
DX NetOps Spectrum
 uses. The documentation is available at http://www.borland.com.
Data Structure Classes
Data structure classes are of two types: parameter and helper.
  •  
    Parameter Class
    Transfers data. Your client programs instantiate these classes and pass them to interface methods. The methods also return instances of these classes to your programs. Examples include CsCModelPropList, CsCMTypePropList, and CsCAttrValList.
  •  
    Helper Class
    Builds and unwraps complex parameter class objects.
You can find the Java docs for these classes by clicking the link com.aprisma.spectrum.core.util in the file <
$SPECROOT
>/SDK/docs/SSORB/index.html. Examples include CsCorbaValueHelper and CsCAttrFilterHelper.
Error Reporting
CORBA reports errors through exceptions. Error reporting through exceptions is an all-or-nothing approach because no other result is possible. This approach is not helpful for partial failures, when only a few items of a request fail. Also, it is not optimal to raise an exception for every failure. The CORBA approach is to use exceptions for complete failures and report partial failures with error codes in result lists. Because it is not optimal to search an entire list to see if any item failed, result lists also provide an overall error code to indicate partial failures.
C++ Development on Windows
The following table lists the library and dynamic link libraries necessary for C++ development on Windows. The corresponding directory location is <
$SPECROOT/lib
>.
 
Library Files
 
 
SDK
 
libGlobl (dll), libssorb (dll), ibssorbutil (dll)
SPECTRUM
orb_r_70 (dll), cosnm_r_70 (dll), vport_r_70 (dll), vdlog_r_70 (dll)
Borland VisiBroker
The following table shows the corresponding header file locations:
 
Library
 
 
Header File Location
 
libGlobl.dll
<
$SPECROOT
>\SDK\include\GLOBL
libssorb.dll
<
$SPECROOT
>\SDK\include\SSORB\idl
libssorbutil.dll
<
$SPECROOT
>\SDK\include\SSORB\util
cosnm_r_70.dll, orb_r_70.dll, vbsec.dll, vdlog_r_70.dll, vport_r_70.dll
Provided by Borland VisiBroker SDK (Not included in SPECTRUM CORBA toolkit.)