NvdmAPI
Class NvdmConnection

java.lang.Object
  NvdmAPI.NvdmConnection

public class NvdmConnection

extends java.lang.Object

This class is the central interface element of the Novadigm Radia API. It represents a TCP connection to a Radia Configuration Server (RCS) and offers methods to manipulate data held in the RCS database.
Before doing any manipulation on the RCS database, a connection has to be opened, giving the RCS IP address (or it's DNS name) and the port. When all operations are completed, the connection has to be closed again. A typical use of NvdmConnection thus looks like this:

    NvdmConnection rcs;
    rcs = new NvdmConnection("15.136.123.255", 3464);
    
    // here: set logging options...

    rcs.open();
        
    // here: do some RCS database manipulation...
    
    rcs.close();

Version:

1.07, 09-April-2004

Author:

Lothar Baum

Constructor Summary

NvdmConnection(java.lang.String mgr, int port)
Creates a connection instance for the specified Radia Configuration Server.

NvdmConnection(java.lang.String mgr, int port, java.lang.String user, int[] passwd, int plen)
Creates a connection instance for the specified Radia Configuration Server.

Method Summary

void	addLoggingLevel(long levelCode) Adds a level of logging.
void	addLoggingType(int typeCode) Adds a type of logging.
int	close() Closes the connection and destroys the socket.
int	createObject(NvdmObject obj) Creates a new object in the Radia database.
int	deleteObject(java.lang.String file, java.lang.String dom, java.lang.String clss, java.lang.String inst) Deletes an object from the Radia database.
boolean	exists(java.lang.String file, java.lang.String dom, java.lang.String clss, java.lang.String inst) Checks for the existence of an object in the Radia database.
NvdmObject	getObject(java.lang.String file, java.lang.String dom, java.lang.String clss, java.lang.String inst) Reads an object from the Radia database.
NvdmList	listClasses(java.lang.String file, java.lang.String dom, java.lang.String clss) Reads a list of class names from the Radia database.
NvdmList	listObjects(java.lang.String file, java.lang.String dom, java.lang.String clss, java.lang.String inst) Reads a list of object names from the Radia database.
int	open() Opens the connection to the RCS by creating a corresponding socket.
int	setLoggingDestination(java.lang.String filename) Specifies a logfile for writing logging information.
int	setLoggingStream(java.io.PrintStream where) Specifies an output stream for writing logging information.
int	updateObject(NvdmObject obj) Modifies an existing object in the Radia database.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NvdmConnection

public NvdmConnection(java.lang.String mgr,
                      int port)

Creates a connection instance for the specified Radia Configuration Server. A network connection is not yet created to allow for first setting the logging options (see setLoggingDestination, setLoggingStream, addLoggingLevel, addLoggingType). The connection is later opened via open.
Signon to the RCS will be done with RAD_MAST / no password.

Parameters:

mgr - DNS name or IP address of the RCS

port - the manager's port number

NvdmConnection

public NvdmConnection(java.lang.String mgr,
                      int port,
                      java.lang.String user,
                      int[] passwd,
                      int plen)

Creates a connection instance for the specified Radia Configuration Server. A network connection is not yet created to allow for first setting the logging options (see setLoggingDestination, setLoggingStream, addLoggingLevel, addLoggingType). The connection is then opened via open.
Signon to the RCS will be done with a user name and password. Since the DES key used to secure the password in transit is Novadigm's secret (it has to be: DES is a symmetric algorithm), this API cannot do the encryption itself but has to be given the encoded byte stream of the password.
Sample: rcs = new NvdmConnection("localhost", 3464, "RAD_MAST", new int[] { 0x06, 0xbe, 0xbb, 0xa7, 0xba, 0x7b, 0x8c, 0x3d }, 3);
How to find the correct byte stream for a given plain text password? Just turn on the logging of 'COMM' on the RCS and use the Radia System Explorer to log on with your password. Then examine the manager's log file for received ZADMIN objects. Here you can read the bytes of the encoded password (length of the encrypted password is always a multiple of 8 bytes). For more details, click here.

Parameters:

mgr - DNS name or IP address of the RCS

port - the manager's port number

user - the user name to log on with

passwd - a list of byte values of the DES-encoded password (number of entries in the list must be a multiple of 8)

plen - the length of the plain text password

Method Detail

setLoggingDestination

public int setLoggingDestination(java.lang.String filename)

Specifies a logfile for writing logging information. If the file already exists, all previous contents will be erased; otherwise the file will be created.

Parameters:

filename - the name of the logfile (possibly including path information in the platform-specific format)

Returns:

0 if successful, or an error code > 0 (see RTE.getErrorText)

setLoggingStream

public int setLoggingStream(java.io.PrintStream where)

Specifies an output stream for writing logging information. For example, this can be used to direct logging information to System.err, the standard error stream of the Java console.

Parameters:

where - the stream where to write logging information (e.g., System.err or System.out)

Returns:

0 if successful, or an error code > 0 (see RTE.getErrorText)

addLoggingLevel

public void addLoggingLevel(long levelCode)

Adds a level of logging. By default, nothing is written to the logging desitination (logfile or output stream). By adding individual levels of logging, the amount of logging information that will be created can be increased. Remember to also set the type of logging information via addLoggingType.

Parameters:

levelCode - the code of the logging level to add (see class RTE)

addLoggingType

public void addLoggingType(int typeCode)

Adds a type of logging. By default, nothing is written to the logging desitination (logfile or output stream). By adding individual types of logging, the amount of logging information that will be created can be increased. Currently, two types are defined: RTE.ERR for error information, RTE.INFO for all other information.

Parameters:

typeCode - the code of the logging type to add (RTE.ERR or RTE.INFO)

open

public int open()

Opens the connection to the RCS by creating a corresponding socket. The socket will remain open until close is called. In the case of an error, null will be returned and (if configured via setLoggingDestination or setLoggingStream) an error message will be written to stderr or a logfile.

Returns:

0 if successful, or an error code > 0 (see RTE.getErrorText)

close

public int close()

Closes the connection and destroys the socket. If the connection didn't exist, nothing will happen (except for creating an error message, if configured via setLoggingDestination or setLoggingStream).

Returns:

0 if successful, or an error code > 0 (see RTE.getErrorText)

getObject

public NvdmObject getObject(java.lang.String file,
                            java.lang.String dom,
                            java.lang.String clss,
                            java.lang.String inst)

Reads an object from the Radia database. Requires an established connection to the RCS. If the object does not exist or another error occurs, en "empty" object will be returned which includes an error code -- see NvdmObject for details.

Parameters:

file - the database file

dom - the database domain

clss - the database class

inst - the object name (32 characters short name)

Returns:

the requested object (which, in case of an error, only includes an error code)

deleteObject

public int deleteObject(java.lang.String file,
                        java.lang.String dom,
                        java.lang.String clss,
                        java.lang.String inst)

Deletes an object from the Radia database. Requires an established connection to the RCS.

Parameters:

file - the database file

dom - the database domain

clss - the database class

inst - the object name (32 characters short name)

Returns:

0 if successful, or an error code > 0 (see RTE.getErrorText)

exists

public boolean exists(java.lang.String file,
                      java.lang.String dom,
                      java.lang.String clss,
                      java.lang.String inst)

Checks for the existence of an object in the Radia database. Requires an established connection to the RCS.

Parameters:

file - the database file

dom - the database domain

clss - the database class

inst - the object name (32 characters short name)

Returns:

true if object exists and can be read, false if object does not exist or an error occured

listObjects

public NvdmList listObjects(java.lang.String file,
                            java.lang.String dom,
                            java.lang.String clss,
                            java.lang.String inst)

Reads a list of object names from the Radia database. Requires an established connection to the RCS. The file, domain, and class must be fully specified; for the instance argument wildcards (*) can be used.
Note: up to now, I haven't tested this method for receiving more than about 620 instances. If your search pattern reveals more than about 620 instances, the received packet size will be greater than 0xFFFF bytes, which might cause problems in decoding and decompression.

Parameters:

file - the database file

dom - the database domain

clss - the database class

inst - a filter for the object name (32 characters short name), may include wildcards (*)

Returns:

an NvdmList object representing a list of NvdmEntity. In the case of an error, the NvdmList object is basically "empty" but only contains an error code which can be read via NvdmList.getRC.

listClasses

public NvdmList listClasses(java.lang.String file,
                            java.lang.String dom,
                            java.lang.String clss)

Reads a list of class names from the Radia database. Requires an established connection to the RCS. The file and domain must be fully specified; for the class argument wildcards (*) can be used.
Note: up to now, I haven't tested this method for receiving more than about 620 classes. If your search pattern reveals more than about 620 classes, the received packet size will be greater than 0xFFFF bytes, which might cause problems in decoding and decompression.

Parameters:

file - the database file

dom - the database domain

clss - a filter for the class name (8 characters short name), may include wildcards (*)

Returns:

an NvdmList object representing a list of NvdmEntity. In the case of an error, the NvdmList object is basically "empty" but only contains an error code which can be read via NvdmList.getRC.

createObject

public int createObject(NvdmObject obj)

Creates a new object in the Radia database. Requires an established connection to the RCS. The object must not yet exist in the database; otherwise an error will be returned. The NvdmObject must have been correctly instantiated to hold file, domain, class, and instance name information. It is not necessary to set every variable defined for the respective class in the NvdmObject; variables missing will be set to empty (resulting in the _BASE_INSTANCE_ values to possibly overwrite them). Values of variables that are identical to the corresponding values of the _BASE_INSTANCE_ will be ignored (removed) by the server. Variables not defined in the class definition will be ignored as well.

Parameters:

obj - the object to be created

Returns:

0 if successful, or an error code > 0 (see RTE.getErrorText)

updateObject

public int updateObject(NvdmObject obj)

Modifies an existing object in the Radia database. Requires an established connection to the RCS. The NvdmObject must have been correctly instantiated to hold file, domain, class, and instance name information. The object must already exist in the database. It is not necessary to set every variable defined for the respective class in the NvdmObject; variables missing will remain unchanged in the database. Values of variables that are identical to the corresponding values of the _BASE_INSTANCE_ will be ignored (removed) by the server. Variables not defined in the class definition will be ignored as well.

Parameters:

obj - the object to be modified, including the variables (and values) to be modified

Returns:

0 if successful, or an error code > 0 (see RTE.getErrorText)