2 Using the OJDL

This chapter outlines the OJDL, including the Java classes provided for developers.

Java Development Environment

In order to develop Java code you need a suitable development environment, such as the Java Platform, Standard Edition (Java SE), which includes the Java Development Kit (JDK). Java SE can be downloaded from the Oracle Technology Network Web site:

http://www.oracle.com/technetwork/java/javase/downloads/index.html

For information about the recommended JDK version for use with the OJDL, see IP Service Activator Installation Guide.

Java SE/JDK can be downloaded free of charge, and can be used for commercial or non-commercial purposes. However, you must retain the copyright notices.

This guide assumes the use of JDK, but other suitable Java tools can be used if required. You need to ensure they are configured correctly.

OJDL Directory and File Structure

When using the OJDL for developing Java code, you need the directories shown in Figure 2-1.

Figure 2-1 OJDL Directories

Description of "Figure 2-1 OJDL Directories"

The doc Directory

The doc directory contains HTML files containing class and package information. The index.html file lists all the classes and packages, and contains links to access the HTML files which provide the relevant information. The doc directory contains the following two subdirectories:

doc\com\mslv\osa\ojdl\eom contains HTML files describing the EOM Java API classes.
doc\com\mslv\osa\ojdl\Oim contains HTML files describing the OIM Java API subclasses (for the OIM IDL).

The lib Directory

The lib directory contains the ojdl.jar file, which contains a compressed version of all the OJDL Java classes. Figure 2-2 shows the internal directory structure of ojdl.jar.

Figure 2-2 Internal Directory Structure of ojdl.jar

Description of "Figure 2-2 Internal Directory Structure of ojdl.jar"

Note:

You must put the ojdl.jar file in the class path.

The Samples Directory

The samples directory contains Java code samples, which provide an illustration of the use of the OJDL classes. The Java code samples are available in the following directory:

samples\com\oracle\communications\ipsa\ojdlSamples

For a brief explanation of the code samples, see the README.txt file in the ojdlSamples folder.

JavaDocs

The JavaDocs are stored in the doc directory. For more information, see "The doc Directory".

Java Classes

The OJDL Java classes provide access to the EOM objects. The classes can also be used to create Java beans which can then be used to create reusable user interface components for particular tasks. These may be written as Java applications, applets, or as scripts within a Java Server Page.

The OJDL Java classes are stored in the lib directory. For more information, see "The lib Directory".

The Java classes are documented as follows:

Information on the classes is accessed through the doc\index.htm file.
Details of methods and variables used are contained in the doc\index-all.htm file

The main classes are summarized in Table 2-1. Refer to the JavaDocs for details.

Table 2-1 Main Java Classes

Class	Description
EomAttribute	A base class for representing an attribute within the EOM.
EomAttributesSe	Holds a set of EomAttribute objects.
EomConnectionManager	Defines a connection manager interface for connecting to the OIM.
EomDebug	Provides a way to enable traces.
EomDefaultConnection	The default implementation of EomConnectManager using the JDK ORB.
EomDifferenceResolver	Finds the logical difference of EomObjects contained in two iterators.
EomDiscovery	Enables the discovery of devices.
EomException	The base class for any exception thrown by the OJDL. May be thrown by methods interacting with the OIM.
EomExtendedSearchIterator	Extends the EomSearchIterator by searching on an iterator of EomObjects.
EomIntersectionResolver	Finds the logical intersection of EomObjects contained in two iterators.
EomIterator	An extension of the java.util.Iterator interface. Provides a wrapper around the search functionality of the OIM find command.
EomIteratorParameters	Provides a way to pass parameters to an EomSearchIterator to refine the search.
EomNonIntegerException	Thrown when a non-integer value is being assigned to an integer variable.
EomObject	A base class for representing objects within the EOM. Each object has an Id, name, and set of attributes.
EomObjectException	Thrown during an EomObject creation.
EomObjectFactory	A factory to build EomObjects.
EomOimException	Thrown when a command cannot be executed by OIM.
EomResolver	A base class for combining the results of two iterator sets.
EomSearchIterator	Looks for all objects of a specific type with a given attribute.
EomSession	Represents a connection to the OIM.
EomSessionException	Thrown by a method in EomSession when connected to the OIM.
EomTransaction	Models the general IP Service Activator transaction concept.
EomTransactionStateChange	A base class that allows IP Service Activator to synchronously return configuration success or failure messages through the OJDL for transactions which perform adds, modifies, or deletes.

Best Practices for Minimizing Commits

It is good to minimize the number of IP Service Activator transaction commits to complete an operation, because each commit introduces a delay when the object model is updated to reflect the new changes.

The following example shows how commits may be minimized when an application generates a large number of devices for testing. These devices are all of the same type and use the device capabilities of an existing device.

To link the desired capabilities, you must first unlink the default capabilities that are linked when the device is created. In the least efficient case, the client code would take three commits; device create, commit, setpath to device and unlink existing caps, commit, link new caps, commit.

In the more efficient form, the client code could accomplish this through one commit by constructing a reference to the default capabilities of the device by appending the following to the path of the device object:

/DeviceCapabilities:"DeviceCapabilities"

The following excerpt shows how to construct an EomIdentifier that references the capabilities linked to the device when the transaction is committed:

EomIdentifier idForNotYetLinkedDefaultCaps = new EomIdentifier("DeviceCapabilities", "DeviceCapabilities", newDevice.getPath() + "/" + "DeviceCapabilities" + ":\"DeviceCapabilities\"");

Then the default caps are unlinked and the appropriate device caps are linked using the following excerpt:

itsTransaction.unlinkObjects(newDevice, itsSession.createEomObject(idForNotYetLinkedDefaultCaps));
itsTransaction.linkObjects(newDevice, deviceCaps);
tr = eomSession.openTransaction();
tr.commit();

Very large transactions can take more time to process once they are committed. This must be balanced against the overall number of commits you issue.