BMC Atrium CMDB 2.1.0.2
API Specification

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

See:
Description

Packages

com.bmc.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) What's new in this release

II) Programming model

III) Java API program structure

IV) Installation and deployment

A) Contents of Java API installation
B) Windows environment setup
C) UNIX environment setup
D) Java API programs at runtime
E) Using the Java API documentation

V) Glossary Terms

I) What's new in this release

In BMC Atrium CMDB version 2.1, the following changes have been made to the Java API.

• API compatibility
• Configuration and installation changes
• Package name changes
• Java Runtime Environment (JRE) version changes
• AR System API changes
• Java API signature changes

API compatibility[Return to TOC]

BMC Atrium CMDB 2.0.x clients that use version 2.0.x DLLs and libraries can continue to work with the 2.1 server. However, if you use version 2.1 DLLs and libraries, you need to make appropriate changes to your code and recompile it. For more information about BMC Atrium CMDB Java API changes, see the section BMC Atrium CMDB Java API changes.

Configuration and installation changes[Return to TOC]

Additional .jar files are now required to use the Java API. For more information, see the section Installation and Deployment.

In addition, the AR System Java API now uses the log4j logging library. You can configure the logging through the Log4j.xml file. This file should be present in CLASSPATH.

Package name changes[Return to TOC]

For Java API, the package name has been changed from com.remedy.cmdb.api to com.bmc.cmdb.api. When you write your program to extend the BMC Atrium CMDB, make sure you update the package name and recompile your program.

JRE version changes[Return to TOC]

In BMC Atrium CMDB version 2.1, the minimum JRE version required is changed to 1.5.0_06 or greater. If you do not upgrade to this version of JRE, your might encounter compiler errors.

AR System API changes[Return to TOC]

Since the AR System Java API was initially written as a wrapper around the AR System C API, the Java API did not utilize the full potential of the Java language. With AR System version 7.1, the Java API is enhanced to use some of the features of Java, such as, annotations, enumerations, and typed-collections.

The following list outlines the changes in the AR System 7.1 Java API:

• Several String-like wrapper classes are replaced with String.
• The AccessNameID class has been replaced with a String class.
• The AttachmentInfo class has been replaced with the AttachmentValue class.
• Several Integer wrapping classes are replaced with int.
• Removed, restructured or renamed several Java API classes.
• Added Class hierarchies for classes emulating C language Unions.
• Re-implemented toString, hashCode, equals and clone methods for applicable Java API classes.
• Several helper API method enhancements.
• Better class hierarchies as opposed to C language Union emulating Java classes.
• API methods added to ARServerUser class, to replace API methods scattered over multiple classes.

For detailed information about these AR System API changes, see the What's new in the AR System 7.1 Java API section of the AR System Java API Help.

Note: If you directly access the AR System Java API in your program, you need to make changes and recompile it.

BMC Atrium CMDB Java API changes[Return to TOC]

Because the BMC Atrium CMDB Java API uses classes in the AR System Java API, the 7.1 API changes impact the BMC Atrium CMDB Java API. The level of impact on BMC Atrium CMDB Java API depends on the extent on which you use the AR System API classes and methods in your program.

The BMC Atrium CMDB Java API uses the following AR System API classes:

• ARServerUser
• ARException
• Value
• CriteriaFlags
• Constants
• QualifierInfo
• AccessNameID*
• PropInfo
• DataType
• CurrencyDetail
• EnumItem
• AttachmentInfo
• BulkEntryReturn

Note:The AccessNameID class has been replaced with a String class.

Example 1-1 illustrates how the AR System Java API changes might affect the BMC Atrium CMDB Java API code.

Example 1-1: Effects of AR System Java API changes

//Initialize ARServerUser instance
ARServerUser context = new ARServerUser();
context.setUser(new AccessNameId("USER")); // Will not compile in 7.1
CMDBClass.find(context, ...); //CMDB API call
The above code will not compile in AR System 7.1 because the AR System API class AccessNameId is replaced with a String class.

Although no modifications are made to the BMC Atrium CMDB API signatures, the input parameter ARServerUser, which is a class defined in AR System API, has changed in version 7.1. The Java compiler might generate an error on the line related to constructing the ARServerUser instance.

Example 1-2 illustrates the changes you need to make to resolve compiler errors.

Example 1-2: Possible modifications to avoid compiler errors

//Initialize ARServerUser instance
ARServerUser context = new ARServerUser(); context.setUser("USER");// Updated for 7.1
//Solution 2.
//Context = new ARServerUser("USER", password, ...);
CMDBClass.find(context, ...);//CMDB API call

Because of the changes in the AR System Java API, certain signatures of classes and methods in the BMC Atrium CMDB Java API have been modified. These changes are listed in the following table.

BMC Atrium CMDB Java API signature changes
Class	Previous signature	Changed signature
CMDBAuditValueList	(constructor) public CMDBAuditValueList( int aOperation, AccessNameID aChangedBy, Timestamp aAuditDate, String[ ] aAttrNameChange, CMDBAttributeValue[ ] aAttributeList)	public CMDBAuditValueList( int aOperation, String aChangedBy, Timestamp aAuditDate, String[ ] aAttrNameChange, CMDBAttributeValue[ ] aAttributeList)
CMDBAuditValueList	public AccessNameID getChangedBy()	public String getChangedBy()
CMDBAuditValueList	public void setChangedBy(AccessNameID aChangedBy)	public void setChangedBy(String aChangedBy)
CMDBInstance	static void findBlobByKey( ARServerUser context,CMDBClassNameKey aClassKey, java.lang.String aDatasetId, int aGetMask, java.lang.String instanceId, java.lang.String attributeName, AttachmentInfo attachment)	static void findBlobByKey( (ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String aDatasetId, int aGetMask, java.lang.String instanceId, java.lang.String attributeName, AttachmentValue attachment)
CMDBInstance	static void findBlobByKey( ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String instanceId, java.lang.String attributeName, AttachmentInfo attachment)	static void findBlobByKey( ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String instanceId, java.lang.String attributeName, AttachmentValue attachment)
CMDBInstanceBase	static void findBlobByKey( ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String aDatasetId, int aGetMask, java.lang.String instanceId, java.lang.String attributeName, AttachmentInfo attachment)	static void findBlobByKey( ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String aDatasetId, int aGetMask, java.lang.String instanceId, java.lang.String attributeName, AttachmentValue attachment)
CMDBInstanceBase	static void findBlobByKey( ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String instanceId, java.lang.String attributeName, AttachmentInfo attachment)	static void findBlobByKey( ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String instanceId, java.lang.String attributeName, AttachmentValue attachment)
CMDBUIComponentResult	CMDBUIComponentResult( java.lang.String aInstanceId, CMDBUIComponentInfo aCompInfo, java.lang.String aDataString, AttachmentInfo aAttachVal)	CMDBUIComponentResult( java.lang.String aInstanceId, CMDBUIComponentInfo aCompInfo, java.lang.String aDataString, AttachmentValue aAttachVal)
CMDBUIComponentResult	AttachmentInfo getAttachVal()	AttachmentValue getAttachVal()
CMDBUIComponentResult	void setAttachVal(AttachmentInfo aAttachVal)	void setAttachVal(AttachmentValue aAttachVal)

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

The BMC Atrium CMDB Java API uses some of the AR System Java API classes. See the AR System Java API.

Because the Java API provides an object model for the BMC Atrium CMDB, the functionality of the C API is encapsulated 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.

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.bmc.cmdb.api and com.bmc.arsys.api packages and other packages you might be using in your program, for example:
   
   import com.bmc.cmdb.api.*;
   import com.bmc.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);

Although the Java API is a wrapper on top of the C API, it uses naming conventions that are different than the C structure. The following table lists these differences:

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

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]

cmdbapi21.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 cmdbapi21.jar file, it must be stored in the classes directory to be loaded multiple times.
log4j.xml	The logging configuration file for the AR System Java API. Details can be found at http://logging.apache.org/. This file must be present in CLASSPATH.
New in version 2.1: arapi71.jar arcmn71.jar arrpc71.jar arutil71.jar commons-beanutils.jar commons-codec-1.3.jar commons-collections-3.2.jar commons-configuration-1.3.jar commons-digester-1.7.jar commons-lang-2.2.jar commons-logging-1.1.jar log4j-1.2.14.jar oncrpc.jar spring.jar	AR System Java API library JAR files that contains the Java API and dependent class files for AR System Java API clients. If two or more applications need to load the arapi71.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.
Windows cmdbapi21.dll cmdbjni21.dll arapi71.dll arcatalog_eng.dll arjni71.dll arrpc71.dll arutiljni71.dll arutl71.dll icudt32.dll icudtbmc32.dll icuinbmc32.dll icuucbmc32.dll mfc71.dll msvcp71.dll msvcr71.dll rcmn71.dll Solaris, Linux libcmdbapi21.so libcmdbjni21.so libarjni71.so libarutiljni71.so libicudatabmc.so.32 libicui18nbmc.so.32 libicuucbmc.so.32 libjlicapi71.so AIX libcmdbapi21.a libcmdbjni21.a libarjni71.a libarutiljni71.a libicudatabmc32.a libicui18nbmc32.a libicuucbmc32.a libjlicapi71.a HP-UX libcmdbapi21.sl libcmdbjni21.sl libarjni71.sl libarutiljni71.sl libicudatabmc.sl.32 libicui18nbmc.sl.32 libicuucbmc.sl.32 libjlicapi71.sl	C API libraries for BMC Atrium CMDB 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.5.0_06 or higher.
JAR Files and CLASSPATH	All .jar files 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;.
Logging and CLASSPATH	The log4j.xml file must be present in CLASSPATH.

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.5.0_06 or higher.
JAR Files and CLASSPATH	All .jar files 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 libcmdbjni21.so file is installed. For AIX, set the LIBPATH environment variable to the location where the libcmdbjni21.a file is installed. For HP-UX, set the SHLIB_PATH environment variable to the location where the libcmdbjni21.sl file is installed.
Logging and CLASSPATH	The log4j.xml file must be present in CLASSPATH.

D) 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 cmdbjni21.dll and arjni71.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 .;cmdbapi21.jar JavaDriver

E) Using the 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/javadoc/cmdbapi subdirectory of your BMC Atrium CMDB installation directory.

IV) Glossary Terms

This section includes definitions 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.bmc.cmdb.api com.bmc.arsys.api
update	Server object member method that updates an object on the database.

[Return to TOC]