Provides the authenticated Application Programming Interface (API) used by all client applications to access the Systems Insight Manager functionality.

All applications that provide programmatic or user interaction with the Systems Insight Manager Central Management Server (CMS) are referred to as clients of the Systems Insight Manager CMS.  All client access is managed by this Client Application Programming Interface (Client API).  The Client APIs provide the public APIs that allow a client application to establish a client session and gain access to all the controller APIs available in the Domain Manager part of the CMS while hiding the complexity of the secure RMI access via the use of the CMS public and private keys and the transaction model used for security by the controller APIs.  The default implementation of these interfaces is an authenticated RMI interface to the Domain Manager's Controllers API (RMI Client API).

The Client API is defined by a set of interfaces that allow the application to establish a client session with the Systems Insight Manager and gain access to a set of client interfaces, which provide the methods to interact directly with the Systems Insight Manager CMS to manipulate the core objects and services of the system and query the database.  The default RMI Client API implementation of these interfaces is provided in this same package.

The Client API interfaces hide the implementation details from the client application developers and provide an interface that could possibly have several implementations.  The default RMI Client API implementation hides the complexity of the authentication and transaction model required to interface with the Systems Insight Manager CMS via the RMI Controllers API.  It is feasible that another implementation of the interfaces could be written that use the SOAP API to communicate with the Systems Insight Manager CMS, or provides a direct implementation that bypasses RMI for use within the Domain Manager JVM (this implementation would need to insure the integrity of the Domain Manager cached core objects by copying parameter objects and returned objects to emulate the behavior of the RMI serialized object interface).

The Client APIs provide a client session interface class, MxSessionClient, and an RMI implementation class, MxSessionClientImpl, that take a pre-authenticated user name as input to create an authorized RMI client session with the Systems Insight Manager CMS.   The Client APIs expect that the user name used to create a client session has already been authenticated by the native login mechanism of the operating system where the CMS is running.   The client session will only be established if the user name is also registered as a user in the CMS database.  The client session instance can then serve up the various other client interfaces which provide access to all the Systems Insight Manager controller functionality made available through RMI for the client APIs.  The behavior of the client methods will be determined by the authorizations and privileges assigned to the user used to establish the client session.

The set of client interfaces are all derived from the MxClient interface base class and the corresponding default RMI implementations of these interfaces are all derived from the MxClientImpl base class. This client base classes define and implement a custom event listener interface.  Using this event listener interface a client application can monitor major events which occur to the core objects in the Systems Insight Manager.  Events include objects added, modified, or removed from the repository and when a client's session lease has expired and/or ended.  This allows an application to be proactive in monitoring and refreshing its local data cache/view when it becomes obsolete.  Each derived client interface class and implementation class mirror a similar controller API interface and correspond to the management of a specific core object in the system (such as a Node Client for the Node object).

The RMI Client API implementation of the MxClientImpl derived classes is strictly a remote invocation of an equivalent method on the corresponding controller's interface providing the MxTransaction object required of all the controller methods.  The controller classes reside in the Domain Manager JVM and their methods are executed over a Java RMI interface.   So, all parameters passed in and objects returned through these methods are serialized objects.   This means the objects are copies on both sides.  The design of the controllers and the client API implementation depend upon this behavior.  When establishing a client session a static method is called which connects to a secure RMI server, authenticates the connection, requests a client session for a valid Systems Insight Manager CMS user to be established, and returns a remote interface to the session manager.  A core session manager remote interface is returned, which represents an open session in the CMS for that user.  All of this complexity is hidden within the MxClientSessionImpl class implemented in the RMI Client APIs.  Likewise, every method call in the RMI Controller API interfaces, retrieved through the open session to the CMS, require a MxTransaction parameter to be passed in to provide transaction validation and security on every method call.  This is hidden within the default client interface implementations in the RMI Client APIs.

So, the Client APIs provide an implementation-independent interface to the public methods available to to provide a cleaner and simpler interface for client applications to use.  And, the RMI Client APIs encapsulate and hide all the RMI access and transaction complexity required to interface with the RMI Controller APIs provided by the Domain Manager of the CMS.  This allows this implementation to possibly change in the future with minimal impact on the client applications.

Core Objects

The primary core objects in the system are found in many different packages.  They are mostly found in the same package as their corresponding core manager.  As you go through the Javadoc for a specific class there should be links to the specific core objects you need to reference.  If not, then refer to the corresponding manager package or the related controller class in the com.hp.mx.core.controllers package.  Since most of the primary core objects derive from the MxObject or MxObjectName base classes it is definitely useful to be familiar with the com.hp.mx.core.objectmodel package.

Core Objects
Class Name Description
com.hp.mx.object.MxObjectName 

Base class for: MxUserName, MxNodeName, MxNodeGroupName, MxRoleName, MxToolName.

The user-input name string assigned to each object in the database.
com.hp.mx.object.MxGUID A unique primary key assigned to each object in the database.
com.hp.mx.object.MxObjectID The MxObjectName/MxGUID pair that uniquely identifies an object in the database.
com.hp.mx.object.MxObject

Base class for: MxUser, MxNode, MxNodeGroup, MxRole, MxTool.

This is the base class for most the core objects in the database.  This class has the methods to access the MxObjectID and MxGUID and all the methods to add/modify/remove client Attributes from the objects.  The subclasses' "getName()" method should be used to get the MxObjectName derived class name object for the corresponding object's class.

 

Understanding How to Use the Core Objects with the Client APIs

There are some basic concepts that need to be understood by the client programmer about how core objects relate to the Client APIs and the database.  All objects passed and/or returned through the RMI Client APIs are serialized to/from the Systems Insight Manager CMS RMI controllers interfaces.  This is important to understand for various reasons:

  1. All objects retrieved from the database are copies of the corresponding objects in the database cache.
  2. Any changes you make to the local object are NOT reflected in the database until you commit the changes using the proper "modify*()" method on the client that manages that specific object type.
  3. Requests for large objects and lists of objects should be minimized for performance and optimized for efficiency.

How to Publish a New Client API with RMI Access to a New Controller API

When a new controller is added to the Systems Insight Manager CMS domain and you want to add a new client API to provide access to it there are a number of required steps to go through.

The first thing is to understand that a consistent naming scheme has been developed to make the file relationships easy to recognize.  The "base name" of the controller and client classes should be the same and should match the name of the primary core object, if there is one, that is being managed by this controller.

For the examples used here, let us say we are adding a new primary object that is named "Widget".  The controller class for "Widget"s will be named "WidgetController".  This class must reside in the "com.hp.mx.core.controllers" package.  It must be a singleton object and must provide an RMI interface and implementation to allow multiple client access to the controller:

Controller Classes
Class Name Description
com.hp.mx.core.controllers.WidgetController.java  The real code that implements the controller. This class must extend MxController This should be a singleton object that returns a reference to its instance through the getDefaultController() method.
com.hp.mx.core.controllers.WidgetControllerIfc.java The remotable public interface to the controller. This interface must extend MxControllerIfc
com.hp.mx.core.controllers.WidgetControllerImpl.java The implementation of the remotable interface to the controller. This class must extend UnicastRemoteObject and implement WidgetControllerIfc

By extending from the MxController class, the new controller inherits a fully implemented event notification dispatcher with methods to send notifications of add/modify/delete operations on the Widget objects in the database.  The base class also provides methods to submit audit log messages and methods to handle verifying parameters.  Extending from the MxControllerIfc interface allows the event listener methods to be propogated through the remotable interface to allow clients to be notified by the controller.

All the public methods made available through the RMI interface are required to take a MxTransaction object so that the transaction can be verified to be a currently logged in session user and properly sequenced transactions.  This is meant to prevent a replay attack.  This is also a reason for the RMI Client API implementation - to hide this complexity from the user's of the client APIs.

When the controller classes have been implemented they will be part of the Domain Manager JVM and will need to be accessible through a Secure RMI interface so that the client API implementation can get access to them.  The Domain Manager (mxdomainmgr) registers a single service in the RMI registery that provides a public method to retrieve a MxSessionManagerIfc interface from the Domain Manager using a secure protocol.  The retrieved MxSessionManagerIfc interface provides methods to then retrieve aany of the RMI controller interfaces.  So, to expose the new controller interface we need to add a "getWidgetControllerIfc(MxTransaction)" method to both the com.hp.mx.core.daemon.MxSessionManagerIfc interface class and com.hp.mx.core.daemon.MxSessionManagerImpl implementation class.  The implementation of this method is best done by copying an existing "get*ControllerIfc(MxTransaction)" method and modifying it to instantiate an instance of a WidgetControllerImpl class and return it as a WidgetControllerIfc interface.  You will also need to add a private WidgetControllerImpl myWidgetControllerImpl data member to the class.

Now that the RMI controller interface is available through the MxSessionManagerIfc interface it is time to implement the corresponding Client API to provide access to the WidgetControllerIfc.  The client API interface will be named "WidgetClient" and the default RMI implementation will be the WidgetClientImpl class. These classes must reside in the "com.hp.mx.core.client" package:

Client Classes
Class Name Description
com.hp.mx.core.client.WidgetClient.java The client interface for application access to manipulate and query the Widget objects in the database. This interface must extend MxClient
com.hp.mx.core.client.WidgetClientImpl.java The implementation of the RMI Client API for the Widget controller. This class must extend MxClientImpl and implement WidgetClient

The WidgetClient interface should exactly mirror all the public methods available on the WdgetControllerIfc interface, but without the MxTransaction parameter and the RemoteException exception removed from the "throws" clause of all the method declarations.

The WidgetClientImpl class will need to have two private data members to save a reference to a MxSessionClientImpl class instance and a WidgetControllerIfc class instance.  It's only constructor should take these two values as parameters and assign them to the private variables.  This class must implement all the methods in the WidgetClient interface by passing the parameters through to the matching WidgetControllerIfc method by referencing it through its private WidgetControllerIfc reference while using the private MxSessionClientImpl reference to get the next MxTransaction object to pass to the controller method.  These method calls must be made within a try/catch block to catch the RemoteException exception and convert it to a MxSessionClosedException runtime exception.  This completely hides the RMI implementation from the user of the Client APIs.  Note: the reason the MxSessionClientImpl reference is passed in instead of the MxSessionClient reference is because the package private "nextTransaction()" method is intentionally left off the MxSessionClient interface since it should never be part of the public client session interface.  It is implementation specific.

Next we must modify the MxSessionClient interface and MxSessionClientImpl class to make the new WidgetClient interface available to users.  We need to add the "getWidgetClient()" method to the interface and the implementation class.  The implementation should be modeled after the existing "get*Client()" methods.  We need to add a "protected WidgetClient myWidgetClient" data member to use to maintain a refernce to the new Client API that is being created and returned.  Within the method we use the "mySessionManager" instance to retrieve a new WidgetControllerIfc instance and use this with the "this" reference to the MxSessionClientImpl as parameters to the new WidgetClientImpl constructor to create an instance of the new Client API assigned to the "myWidgetClient" data member.  The method must catch and throw the correct exceptions as shown by the other methods.

Related Documentation

@see com.hp.mx.core.controllers @see com.hp.mx.core.daemon.MxSessionManagerIfc @see com.hp.mx.core.daemon.MxSessionManagerImpl @see com.hp.mx.portal.ui.MxLoginBean @see com.hp.mx.cli.utilities.MxCLIServiceFacade @since Systems Insight Manager 4.0