Radia NvdmAPI
The JavaTM API to Radia Configuration Servers
Documentation

Version 1.0.11, 5-May-2005

 Java

General Information   Guide to Features   API: Classes & Methods
  Version History   Compatibility   Download NvdmAPI.jar   Download Documentation

Your feedback is highly appreciated! Please send comments, bug reports, and enhancement requests to: lbaum@web.de.

General Information
 
 

The NvdmAPI provides a Java-based API to Novadigm Radia Configuration Servers (RCS). It performs basic read / write access to the Radia database from any Java-capable platform. The NvdmAPI provides similar functionality to the Novadigm proprietary Tcl-based API, which is available as part of the Radia Integration Server (RIS) package, and uses the original Novadigm TCP-based protocol also deployed by the Radia System Explorer.
The NvdmAPI offers enhanced performance, a broad availability for any Java-capable platform, and an improved programming experience (higher level data types and abstractions allow you to reduce the amount of coding required to achieve typical tasks).
NvdmAPI uses the Novadigm communication protocol that is used between the Radia System Explorer and the Radia Configuration Server. As this communication protocol is used by Novadigm as the fundamental basis for the overall Radia product suite, it is expected to remain stable with little or few changes in the future, and therefore the NvdmAPI can be expected to provide a stable basis for application programming for quite some time.
NvdmAPI has been written entirely from scratch and does not use or include any Novadigm related or proprietary code. As it is written in completely native Java, it is expected to run on any Java-capable platform version 1.2 and up.

 
Guide to Features
 
 

The NvdmAPI provides basic read / write access to the Radia database via a simple one port TCP connection. In principle, the underlying Novadigm protocol allows any operation on the database, including creation of new classes, domains etc. However, currently only instance related operations are supported by NvdmAPI. These include:

NvdmAPI provides easy to use abstractions to perform the above operations and to build individual functionality on top of these operations. The abstractions include:
  • NvdmConnection, the central interface element for establishing a connection to the RCS, setting logging options, and to perform the operations mentioned above
  • NvdmObject, the representation of a class instance in the Radia database
  • NvdmVariable, the representation of an instance attribute (variable)
  • NvdmList, the datastructure holding a list of entities (either class instances or classes)
  • NvdmEntity, an abstraction of class instances and classes as being elements of a NvdmList
The NvdmAPI is typically used in three consecutive stages:
  • stage 1: opening the connection, i.e., creation of a NvdmConnection object, setting the logging level, and logging on to the Radia server
  • stage 2: performing a sequence of operations on the database
  • stage 3: closing the connection
The following will give simple examples of how to use the NvdmAPI in the different stages (the NvdmConnection object 'rcs' created in the first example is expected to exist with a correctly opened connection throughout all examples). The full API documentation can be found here.
 

Establishing a connection

 

               import NvdmAPI.*;
               
               
               NvdmConnection rcs;
               int rc;
               
               // create the connection object  
               rcs = new NvdmConnection("15.136.123.255", 3464);
               
               // set up logging                         
               rcs.setLoggingStream(System.err);
               rcs.addLoggingLevel(RTE.BUFF);
               rcs.addLoggingLevel(RTE.OBJC);
               rcs.addLoggingLevel(RTE.APPL);
               rcs.addLoggingType(RTE.ERR);
               rcs.addLoggingType(RTE.INFO);
               
               // establish the connection and log in   
               rc = rcs.open();
               
               if ( rc != 0 ) {
                  System.err.println("Error: "+RTE.getErrorText(rc));
                  System.exit(-1);
               }

 

Listing existing classes

 
               Enumeration policyEnum;
               NvdmList policyList;
               NvdmEntity policyClass;
               int rc;
               
               // get all classes defined in the POLICY domain
               policyList = rcs.listClasses("PRIMARY","POLICY","*");
               
               rc = policyList.getRC();
               if ( rc != 0 ) {
                  System.err.println("Error reading POLICY classes: "+RTE.getErrorText(rc));
                  System.exit(-1);
               }
               
               policyEnum = policyList.getEntries();
               while ( policyEnum.hasMoreElements() ) {
                  policyClass = (NvdmEntity) policyEnum.nextElement();
                  System.out.println("class found: "+policyClass.getClss());
               }

 

Listing existing class instances

 
               Enumeration usersEnum;
               NvdmList usersList;
               NvdmEntity user;
               int rc;
               
               // get all users/machines set up in the database
               usersList = rcs.listObjects("PRIMARY","POLICY","USER","*");
               
               rc = usersList.getRC();
               if ( rc != 0 ) {
                  System.err.println("Error reading USER instances: "+RTE.getErrorText(rc));
                  System.exit(-1);
               }
               
               usersEnum = usersList.getEntries();
               while ( usersEnum.hasMoreElements() ) {
                  user = (NvdmEntity) usersEnum.nextElement();
                  System.out.println("instance found: "+user.getInstance());
               }

 

Reading an existing instance

 
               NvdmObject myMachine;
               NvdmVariable firstConnection;
               int rc;
               String userID;
               String software;
               
               // read the object from the database
               myMachine = rcs.getObject("PRIMARY","POLICY","USER","PC4711");
            
               rc = myMachine.getRC();
               if ( rc != 0 ) {
                  System.err.println("Error reading PC4711: "+RTE.getErrorText(rc));
                  System.exit(-1);
               }
            
               // read the USERID attribute
               userID = myMachine.getVariableDataString("USERID");
               System.out.println("The userID is "+userID);
               
               // read the first class connection attribute
               firstConnection = myMachine.getVariable("_ALWAYS_", 0);
               software = firstConnection.getDataString();
               System.out.println("Assigned software is "+software);

 

Updating an existing instance

 
               NvdmObject myMachine;
               int rc;
               
               // read the object from the database
               myMachine = rcs.getObject("PRIMARY","POLICY","USER","PC4711");
            
               rc = myMachine.getRC();
               if ( rc != 0 ) {
                  System.err.println("Error reading PC4711: "+RTE.getErrorText(rc));
                  System.exit(-1);
               }
            
               // update the USERID attribute to 'lbaum'
               myMachine.updateVariable("USERID", "lbaum");
               
               // write object back to database
               rc = rcs.updateObject(myMachine);
            
               if ( rc != 0 ) {
                  System.err.println("Error updating PC4711: "+RTE.getErrorText(rc));
                  System.exit(-1);
               }

 

Creating a new instance

 
               NvdmObject newMachine;
               int rc;
               
               // create new client-side object
               newMachine = new NvdmObject("PRIMARY","POLICY","USER","PSPC");
               
               // add variables and their values
               newMachine.add(new NvdmVariable("USERID", "psmith"));
               newMachine.add(new NvdmVariable("NAME", "Peter Smith's PC"));
               newMachine.add(new NvdmVariable("ZTIMEO", "360"));
               newMachine.add(new NvdmVariable("_ALWAYS_", 0, "SOFTWARE.ZSERVICE.AMORTIZE"));
               newMachine.add(new NvdmVariable("_ALWAYS_", 1, "SOFTWARE.ZSERVICE.GS-CALC"));
              
               rc = rcs.createObject(newMachine);
               
               if ( rc != 0 ) {
                  System.err.println("Error creating PSPC: "+RTE.getErrorText(rc));
                  System.exit(-1);
               }

 

Deleting an instance

 
               int rc;
               
               // delete instance from database
               rc = rcs.deleteObject("PRIMARY","POLICY","USER","PSPC");
               
               if ( rc != 0 ) {
                  System.err.println("Error deleting PSPC: "+RTE.getErrorText(rc));
                  System.exit(-1);
               }

 

Checking the existence of an instance

 
               if ( rcs.exists("PRIMARY","POLICY","USER","PSPC") )
                  System.out.println("instance 'PSPC' exists");
               else
                  System.out.println("instance 'PSPC' does not exist");

 

Closing the connection

 
               int rc;
               
               // close connection
               rc = rcs.close();
               
               if ( rc != 0 ) {
                  System.err.println("Error closing: "+RTE.getErrorText(rc));
                  System.exit(-1);
               }

 
Version History
 
 

05-May-2005: version 1.0.11
Changed the way RCS servers version 4.5.3 (and above) are detected. The original detection method (introduced in 1.0.9) caused problems when reading class templates (_BASE_INSTANCE_).

14-Apr-2005: version 1.0.10
Fixed a bug in NvdmObject.updateVariable that prevented addressing the correct object attribute in the case where there are several attributes with the same name.

13-Apr-2005: version 1.0.9
Added compatibility with RCS version 4.5.3 protocol (Radia 4.x suite). With RCS 4.5.3, a small change to the GETOBJ protocol response was introduced which caused the API to fail on reading objects from the RCS.

15-Apr-2004: version 1.0.8
Loosened the error checking on RCS result codes a little; seems like some "errors" reported by the RCS actually are not fatal and can/should be ignored...

09-Apr-2004: version 1.0.7
Added support for authenticated connections with passwords being longer than 8 characters.

24-Jun-2003: version 1.0.6
Changed the authentication check in the updateObject method from the attribute ZOBJRCRC to ZOBJID. This should solve problems where an update of an 'authentic' instance was rejected because the instance didn't have an attribute ZOBJRCRC.

12-Jun-2003: version 1.0.5
Added support for retrieving large lists of instances / classes from 4.5.x servers via the listClasses() and listObjects() methods. These methods should now work fine with all Radia servers for up to at least 620 instances / classes. It should also work for even more instances / classes, but I didn't yet have the chance to test that.

04-Jun-2003: version 1.0.4
Fixed a small bug that could scramble read object data in some rare cases.

02-Jun-2003: version 1.0.3
Fixed the decompression of objects for compatibility with manager versions 4.5 and above. Again, a special byte sequence could confuse the decoding of objects and thus scramble object data (it might have been a new feature of the servers or a bug in my old decompression code). Novadigm really seems to have a lot of 'exceptions to the rule' :-/

29-May-2003: version 1.0.2
Updated the documentation to explain in more detail how to identify the encrypted password for establishing an authenticated connection. No changes to the NvdmAPI implementation itself.

03-Dec-2002: version 1.0.2
Fixed a small bug in the decompression of received objects. For some special byte sequences, this bug confused the decoding of the object and thus scrambled object data.

30-Oct-2002: version 1.0.1
Fixed a small bug that occured when retrieving long lists of instances or classes from the RCS (more than about 120 entities). The RCS seems to split large data into several blocks, so I had to add the correct handling of these blocks.

6-Oct-2002: version 1.0
The October 2002 release is the first stable and fully functional version of NvdmAPI that has been used to actually build a major database manipulation application. The major limitations of the NvdmAPI have been removed, and compatibility with Radia 3.x Configuration Servers has been added.

  • compatible with Radia 3.x servers
  • supports user name / password logins
  • dynamic buffer management (removes limitations on maximum list lengths of returned class and instance lists as well as maximum object sizes)

17-Mar-2002: version 0.9
First public release of the NvdmAPI. The API is fully functional, however, with some limitations:

  • only anonymous logins to the Radia server (standard user name RAD_MAST, no password) are supported
  • static buffer management requires pre-allocation of object and list buffer (as a consequence, the programmer has to know how large requested objects will be, or how many entities in a requested class or instance listing will be returned)

 
Compatibility
 
 

The NvdmAPI is expected to work with:

  • any 2.x, 3.x, and 4.x Radia Configuration Server
  • any Java 1.2 (or higher) client platform
It has been successfully tested with:
  • Windows RCS 4.4, 4.4.1, 4.4.2 (Radia 2.x)
  • Windows RCS 4.5, 4.5.1, 4.5.2 (Radia 3.x)
  • Windows RCS 4.5.3 (Radia 4.x)
  • Sun's JDK 1.3 on Windows 2000
  • Sun's JDK 1.3.1 on Windows 2000
  • MacOS 10.1, 10.1.1 - 10.1.5 Java 1.3
  • MacOS 10.2, 10.2.1 Java 1.3.1
  • MacOS 10.2.4 - 10.2.6 Java 1.4.1
  • MacOS 10.3.0 - 10.3.8 Java 1.4.2
Please report other successful deployments (or bugs etc.) to lbaum@web.de.

 
Copyright © 2002/2003/2004/2005 Dr. Lothar Baum, All Rights Reserved.

Please send comments, bug reports, and enhancement requests to: lbaum@web.de