Getting Started With the Admin API
The BBj Admin API is an API used to provide administrative functionality programmatically to BBj and Java programs. For an example of the many features of the API, simply look no further than the BBj Enterprise Manager. All the administrative management and configuration functionality in the Enterprise Manager utilizes the Admin API to interact with the server.
Getting started developing with the Admin API can be challenging for the uninitiated for two primary reasons: (1) configuration options are vast, and (2) the API often requires multiple steps to accomplish tasks. The purpose of this article is to help developers understand the general concepts required to understand the API and how to use the documentation to build administrative solutions into BBj and Java applications.
Documentation Format - Javadocs
The Admin API uses technology called Javadocs to document the API methods and functionality. Javadocs essentially self-documents APIs by building a navigable hierarchy of HTML pages with documentation containing hyperlinks pointing to other areas of the API to make it easy to jump from methods and classes to other related methods and classes. See the Javadocs when looking for information about interacting with the API as well as sample code for each portion of the API.
Client/Server Architecture
The Admin API is a client/server API. This makes it possible for an application to perform administrative tasks on the same machine or any accessible remote machine. When making calls on a remote machine, all the work occurs on the server side. In this case, the client is little more than an interface between the application utilizing the API, and the server.
Java Applications Using the Admin API
In order to use the Admin API in a client Java application outside BBj, the BBjAdminAPI.jar file must be added to the application’s classpath. This file is located in the BBj installation’s lib directory. See the Java documentation for details concerning the use of JAR files in the classpath.
Important Note Before Getting Started
Applications requiring access to Admin API functionality all begin at the same point with a call to create an instance of a BBjAdminBase object. It is NOT good practice to directly instantiate objects in the Admin API using the new command due to the client/server nature of the API. The API uses RMI (remote method invocation) to communicate between the client and server so it is important to acquire instances using getXXX(), createXXX(), or newXXX() depending on the class. Allow the objects to create the proper instances to ensure they interact properly with the server. See the Javadocs for details.
There are also certain classes that should never be referenced directly. These classes all start with BBjAdminLocal. For example, there is a BBjAdminDatabase interface and a BBjAdminLocalDatabase class. NEVER reference BBjAdminLocalDatabase as this can cause unforeseen consequences down the road should BASIS decide to change implementation classes. Always reference only the base interfaces. For example, the following code shows how to correctly declare a variable that will hold an instance of a BBjAdminDatabase:
declare
BBjAdminDatabase myDB! // CORRECT
declare BBjAdminLocalDatabase myDB! // INCORRECT - DO NOT DO THIS
API Entry Point
All Admin API requests require user authentication to validate the user and to limit their access to only those operations which they are allowed to perform. To gain access to the Admin API, begin by acquiring an instance of BBjAdminBase by making a static call to the BBjAdminFactory class:
REM
Acquire an instance of the API on the local BBjServices
api! = BBjAdminFactory.getBBjAdmin("admin", "admin123")
REM Acquire an instance connected to a remote machine
Address! = java.net.InetAddress.getByName("myserver")
ssl = 1
api! = BBjAdminFactory.getBBjAdmin(address!, 2002, ssl, "admin", "admin123")
Additional getBBjAdmin() method
variations are available. Consult the Javadocs
for complete details.
Getting/Setting Values
Getting and setting values is a bit unique in the Admin API. Typically, developers use getXXX() and setXXX() methods to get and set object values. To keep the API as backward compatible as possible since it uses RMI, the API uses getString()/setString(), getInt()/setInt(), etc. where each call takes a property name to indicate the value of interest. For example, the following call on a BBjAdminDatabase returns the name of the database (rather than calling getDatabaseName() which does not exist):
myDB!
= api!.getDatabase("MyDatabase")
dbName$ = myDB!.getString(BBjAdminDatabase.DATABASE)
Note
the use of a constant: BBjAdminDatabase.DATABASE. This is the recommended
method for accessing properties. This insures the correct property name
is passed into the call without misspellings, case issues, etc. Always
use the constants when available.
This paradigm is used throughout the Admin API. Some objects will have getter/setter methods available but these generally occur when the method will be performing some kind of server side action other than setting a property value. Make sure to check the Javadocs for details when working with any objects in the Admin API.
Off and Running
At this point the best way to proceed is to consult the Javadocs and look over the various code samples available. The Admin API is a growing API and the documentation is always changing so more examples are likely to be available on a regular basis.