BMC CMDB Object Manager API

The BMC Atrium CMDB Java API enables you to integrate your Java applications with the BMC Atrium CMDB.

See:
Description

Packages

com.remedy.cmdb.api

The BMC Atrium CMDB Java API enables you to integrate your Java applications with the BMC Atrium CMDB. The Java API, provides methods to manipulate the CMDB classes, instances and its attributes.

If you have any comments or suggestions about this documentation, contact BMC Information Design and Development by email at doc_feedback@bmc.com.

Table of Contents

I) Programming Model and Featured Design Patterns

A) Proxy Design Pattern
B) Exception Handling (Errors)

II) Java API Program Structure

A) Naming Conventions: How C Structures and Functions Correspond to Java API Objects

III) Installation and Deployment

A) Contents of BMC Atrium CMDB Java API Installation
B) Windows Environment Setup
C) UNIX Environment Setup
D) BMC Atrium CMDB Java API Programs at Runtime
E) Using the BMC Atrium CMDB Java API Documentation

IV) Glossary Terms

I) Programming Model

The Java API is built as a "wrapper," on top of the C API through the Java Native Interface (JNI) layer, which means for every function in the C API, there is an equivalent method in the Java API. You can use the Java API only on the following supported AR System platforms:

• Windows
• Solaris
• HP-UX
• AIX
• Linux

Because the Java API provides an object model for the BMC Atrium CMDB, the functionality of the C API is encapuslated within specific Java classes.
Note: The Java API methods do not correspond 1:1 with their C API equivalents. Therefore, the signatures for these methods might be different than the C API.

Featured Design Patterns

A) Proxy Design Pattern [Return to TOC]

The Proxy design pattern is used for handling the technical aspects of server objects, such as memory management and access to the AR System server. The Proxy class that performs this function is not visible to users of the BMC Atrium CMDB Java API and is designed for internal use only.

The Proxy class contains all the native methods required for interaction with the BMC Atrium CMDB. Each of these native methods perform data conversion from C to Java (or Java to C) and "wrap" the BMC Atrium CMDB C API functions.

B) Exception Handling (Errors) [Return to TOC]

Errors are modeled through the ARException class. All error messages that are returned by the server are thrown as an ARException in the Java API.

II) Java API Program Structure

Use the following high-level steps in your Java program to implement the BMC Atrium CMDB:

1. Import the BMC Atrium CMDB and AR System packages. In this part of the program, you import the com.remedy.cmdb.api and com.remedy.arsys.api packages and other packages you might be using in your program, for example:
   
   import com.remedy.cmdb.api.*;
   import com.remedy.arsys.api.*;
   import java.util.*;
   
   
2. Create a new ARServerUser context. The following example shows how to create an ARServerUser context:
   
   ARServerUser context = new ARServerUser("Demo", "", "password", "localhost");
   
   
3. Create the object. The following example shows how to create an object:
   
   CMDBClassNameKey nameKey= new CMDBClassNameKey("Movie", "VirtualNamespace");
   CMDBClass movie = new CMDBClass(nameKey, "ObjectID101", null);
   
   
4. Populate the object. The following example shows how to populate an object:
   
   movie.setDescription("Movie Object");
   
   movie.setAbstract(0);
   Map anAttributeMap = new HashMap();
   
   CMDBAttribute attribute1 = new CMDBAttribute("title", 4530354,
   CMDBAttribute.CMDB_ATTR_ENTRYMODE_REQUIRED,
   new CMDBCharLimit(127),
   null);
   anAttributeMap.put(attribute1.getName(), attribute1);
   
   movie.setAttributes(anAttributeMap);
   
   
5. Perform the operation for creating the user context. The following example shows how to create the context:
   
   movie.create(context);

A) Naming Conventions: How C Structures and Functions Correspond to Java API Objects [Return to TOC]

Although the Java API is a wrapper on top of the C API, it uses different terms to refer to specific objects. The following table lists these differences:

Differences in Naming Conventions
C API	Java API
Get	findByKey
Set	update
Create	create
Delete	delete
GetList	find

III) Installation and deployment

To use the Java API, the following libraries and DLLs must be installed on your system:

A) Contents of the BMC Atrium CMDB installation [Return to TOC]

cmdbapi20.jar	The Java API library JAR file that contains the Java API class files for the BMC Atrium CMDB Java API clients. If two or more applications need to load the cmdbapi20.jar file, it must be stored in the classes directory to be loaded multiple times.
arapi70.jar arutil70.jar	AR System Java API library JAR files that contains the Java API class files for AR System Java API clients. If two or more applications need to load the arapi70.jar file, it must be stored in the classes directory to be loaded multiple times.
CMDB Java API & AR System Java API	Javadoc generated HTML documents for the BMC Atrium CMDB API and the AR System Java API.
JavaDriver.java	Sample Java code file that shows examples of using the Java API.
AR System Java API constructs, such as AccessNameID	The BMC Atrium CMDB Java API uses some of the AR System Java API classes. See the AR System Java API.
arapi70.dll arutil70.dll arrpc70.dll	AR System C API libraries for AR System C API clients.
Windows mfc71.dll msvcp71.dll.dll msvcr71.dll Xalan-C_1_9.dll XalanMessages_1_9.dll arapi70.dll arcatalog_eng.dll ariapi70.dll arjni70.dll arrpc70.dll arutiljni70.dll arutl70.dll arxmlutil70.dll cmdb2asset.dll cmdbapi20.dll cmdbeng20.dll cmdbjni20.dll cmdbsvr20.dll icudt32.dll icuin32.dll icuuc32.dll libcmdbconsolefilterapi20.dll rcmn70.dll xerces-c_2_6.dll xerces-depdom_2_6.dll Solaris, Linux libcmdbjni20.so libcmdbeng20.so libcmdbsvr20.so libutil.a libcmdbapi20.so libcmdb2asset.so libcmdbconsolefilterapi20.so libar.a libcmdbjni20.so libxerces-depdombmc.so.26 libari70.so libicui18nbmc.so.32 libarutiljni70.so libarjni70.so libicudatabmc.so.32 libxalanMsgbmc.so.19 libjlicapi70.so libxalan-cbmc.so.19 libarxmlutil.so libicuucbmc.so.32 libxerces-cbmc.so.26 AIX libcmdbsvr20.a libcmdbapi20.a libcmdbeng20.a libcmdbconsolefilterapi20.a libutil.a libcmdb2asset.a libar.a libcmdbjni20.a libxerces-cbmc26.0.a libarutiljni70.a libarxmlutil.a libxerces-depdombmc.a libxerces-cbmc.a libarjni70.a libxerces-cbmc26.a libxalan-cbmc19.a libxerces-depdombmc26.a libicui18nbmc32.a libicuucbmc32.a libxerces-depdombmc26.0.a libxalanMsgbmc.a libicudatabmc32.a libjlicapi70.a libari70.a HP-UX libutil.a libcmdbjni20.sl libar.a libcmdb2asset.sl libcmdbeng20.sl libcmdbapi20.sl libcmdbsvr20.sl libcmdbconsolefilterapi20.sl libicui18nbmc.sl.32 libxalan-cbmc.sl.19 libari70.sl libarjni70.sl libjlicapi70.sl libicudatabmc.sl.32 libxalanMsgbmc.sl.19 libarxmlutil.sl libxerces-depdombmc.sl.26 libarutiljni70.sl libxerces-cbmc.sl.26 libicuucbmc.sl	C API libraries for BMC Atrium CMDB C API clients.

B) Windows Environment Setup [Return to TOC]

The following table lists the environment variables you need to set up for Windows.

Compiler	Requires J2SE Software Development Kit (SDK) 1.4.2 (or higher).
JAR Files and CLASSPATH	cmdbapi20.jar and arapi70.jar should be present in CLASSPATH. If you are running the BMC Atrium CMDB Java API on a web server, you must set the CLASSPATH information on the web server.
DLLs and System Path	The Java API requires the BMC Atrium CMDB API and AR System API DLLs. All DLLs should be available in the DLL search path. Point to the sdk\bin subdirectory of your BMC Atrium CMDB installation directory;.

C) UNIX Environment Setup [Return to TOC]

The following table lists the environment variables you need to set up for UNIX:

Compiler	Requires J2SE Software Development Kit (SDK) 1.4.2 (or higher).
JAR Files and CLASSPATH	cmdbapi20.jar and arapi70.jar should be present in CLASSPATH. If you are running the BMC Atrium CMDB Java API on a web server, you must set the CLASSPATH information on the web server.
PATH	Update your PATH environment variable to include the bin directory for the JDK.
Library path	Set the library path environment variables to where the libcmdbjni.<operating_system> file is installed on your particular UNIX OS: For Solaris and Linux, set both the LD_LIBRARY_PATH and LIBPATH environment variables to the location where the libcmdbjni20.so file is installed. For AIX, set the LIBPATH environment variable to the location where the libcmdbjni20.a file is installed. For HP-UX, set the SHLIB_PATH environment variable to the location where the libcmdbjni20.sl file is installed.

D) BMC Atrium CMDB Java API Programs at Runtime [Return to TOC]

Install and configure the Java Runtime Environment on user systems.

Tips

• When running a program that uses the API, make sure that cmdbjni20.dll and arjni70.dll exist in the DLL search path.
  
• If you are running your application from the command-line, make sure you include the classpath option when you specify the Java command. For example, the following command runs the JavaDriver.java program and the classpath option points to the current directory for the JAR file:

java -D java.library.path = <directory>; -classpath .;cmdbapi20.jar JavaDriver

E) Using the BMC Atrium CMDB Java API Help [Return to TOC]

The BMC Atrium CMDB Java API Help provides the class and method definitions for the Java API. To launch the BMC Atrium CMDB Java API Help, double-click the index.html file installed in the sdk/doc/javadoc/cmdbapi subdirectory of your BMC Atrium CMDB installation directory.

IV) Glossary Terms

This section includes defintions for terms used in the BMC Atrium CMDB Java API.

Term	Definition
ARException	The class that is used for handling errors from the AR System server. Use the ARException methods to obtain status information (using the StatusInfo class) and to describe errors.
ARServerUser	The ARServerUser class represents user information that contains login information for accessing the AR System. You use a ARServerUser object to initialize calls to a particular AR System server.
AR System Java API	Application programming interface that integrates with the AR System. It consists of a collection of classes, interfaces, and relationships that abstract the AR System C API and hide some of its details, such as the memory management for data structures, managing connections, and so on. Using the Java development environment, you can use the AR System Java API--clicking this link opens the AR System Java API documentation in a new window--to communicate with the AR System server without programming in C.
Context	The user session information that pertains to the current operation within an object. You create a Context with user information (user name, password, etc.) contained in the ARServerUser object for an operation performed in the specified session.
create	Server object member method that creates an object on the server specified in the ARServerUser object.
delete	Server object member method that deletes an object or an instance in the Class Manager.
find	Server object method that returns a list of objects or instances.
findByKey	Server object that returns an object or an instance.
JNI	The Java Native Interface. This is a C++ layer that takes calls from Java and makes corresponding calls to the C API. This happens transparently.
Package	The package is a name space in Java for all objects and classes pertaining to the BMC Atrium CMDB Java API. com.remedy.cmdb.api com.remedy.arsys.api
update	Server object member method that updates an object on the database.

[Return to TOC]