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.
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.
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: |
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: |
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. |
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:
MxNodeManager
interface includes
a special "exclusive modification" lock API to insure only one
client can modify a MxNode
object. This is NOT implemented
in Systems Insight Manager 4.1)MxEventListener
" interface on each Client
API interface class to be automatically notified when objects managed by
through that client have been added, modified, or removed. The MxEvent
object will contain the type of operation that occurred and a copy of the
affected object as its payload. (This is very useful if you do
local caching of objects of interest and want to automatically keep them
up-to-date)modify*()
"
method on the client that manages that specific object type.
set*()
",
"add*()
", or "remove*()
"
methods on that object are only made to the local copy. To commit
the changes to the database you need to call the corresponding
client's "modify*()
" method.MxGUID
" instance stored in the object you retrieved
for modification is used to match your local copy with the object in the
database to be modified with your changes during the client's
"modify*()
" method call.MxUserClient.modifySessionUser()
, is
provided to allow non-trusted session users to update the attributes of
their own MxUser
session user object. This method
does not allow modification of the login name or trusted user privilege.MxObjectID
" objects, which
contain the name and MxGUID referencing the database object.MxObjectID
" objects, or
just the names of the objects. So, use the best method that fits
the needs of your application.MxJobClient
job results and target results objects and the
MxNodeClient
MxNode
objects.)MxTargetStatus
"
object. This is a compound object that contains an instance of the
"MxTargetOutput
" object. The "MxTargetOutput
"
object can be very large for SSA and MSA tools which are of command type
"stdout". The "MxTargetOutput
"
object is only used when a user requests that detailed information be
displayed about a task target. So, to optimize the performance of
queries for the "MxTargetStatus
" object and for a
list of "MxTargetStatus
" objects two special
things are done:
MxTargetOutput
"
object is set to "null
" before the "MxTargetStatus
"
object(s) are returned by the MxJobClient
methods
"getTargetStatus(String taskID, MxObjectID nodeID)
"
and "getTargetStatusList(String taskID)
".MxTargetOutput
" object for a
task target you need to call a special MxJobClient
method,
"getTargetOutput(String taskID, MxObjectID nodeID)
".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.
MxLoginBean
establishes the client session and has public methods available to provide the various client
interfaces to other JavaBeans and to JSP pages to directly access client APIs within the web
server session.