User: andreas
Date: 00/09/09 20:34:22
Added: . JMX.Connector.Howto.html
Log:
JMX Connector HowTo: First Draft
Revision Changes Path
1.1 jbossweb/JMX.Connector.Howto.html
Index: JMX.Connector.Howto.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>JMX Connector Introduction and HowTo</TITLE>
<STYLE type="text/css">
BODY {
background-color:#99cc66;
}
DIV.page {
background-color:white;
margin-left:0.25in;
margin-right:0.25in;
border:solid 1px;
}
DIV.para {
font:normal 12pt 'times new roman',serif;
margin-left:0.5in;
margin-top:1em;
margin-bottom:1em;
margin-right:o.5in;
background-color:white;
}
DIV.footer {
font:normal 12pt 'times new roman',serif;
margin-left:0.1in;
margin-top:1em;
margin-bottom:1em;
margin-right:o.1in;
background-color:lightskyblue;
}
DIV OL {
font:normal 12pt 'times new roman';
margin-left:0.5in;
margin-top:1em;
margin-bottom:1em;
margin-right:o.5in;
background-color:khaki;
}
DIV UL {
font:normal 12pt 'times new roman';
margin-left:0.5in;
margin-top:1em;
margin-bottom:1em;
margin-right:o.5in;
background-color:lightgreen;
}
DIV B {
font-weight:bold;
background-color:lightcoral;
}
H1 {
font-size:28pt;
text-align:center;
}
H2 {
font-size:24pt;
margin-left:0.1in;
}
H3 {
font-size:20pt;
margin-left:0.3in;
}
H4 {
font-size:16pt;
margin-left:0.5in;
}
</STYLE>
</HEAD>
<BODY>
<DIV class="page">
<H1>JMX Connector Description and HowTo</H1>
<H2>Introduction</H2>
<H3>JMX Spec from Sun</H3>
<DIV class="para" ALIGN="left">
Sun release recently the final specification, API and Reference Implemenation
to the <A HREF="http://java.sun.com/products/JavaManagement/index.html">Java
Management Extention (JMX)</A>.
The idea behind this is to provide an API to which the component vendors can make
their components manageable and the management tools vendor can use this API to
manage these components.
</DIV>
<BR>
<DIV class="para" ALIGN="left">
Therefore the whole JMX is separated into 3 parts:
<OL>
<LI>
Components implement a certain API to offer their management API to the JMX world.
There are 3 ways: through an Interface, through a API descriptions (Open MBean) and
through a Model MBean (but for this have a look at the spec).
</LI>
<LI>
JMX Agent which contains a MBean Server, certain services like dynamic download,
timers,
releations etc. and at least one Connector or Adaptor.
</LI>
<LI>
Management Tool usings a Connector or Adaptor to manage the components of the JMX
Agent
the tool is connected to.
</LI>
</OL>
</DIV>
<H3>JMX Implementation in jBoss</H3>
<DIV class="para" ALIGN="left">
At the moment (8th of September 2000) jBoss uses the final release JMX API for its
services
defined in the jboss.conf file (in there you see that also HTML Adaptor and the JMX
Connector
are manageable components). In addition jBoss use the MBean Server implementation
and the
HTML adaptor from the JMX-RI. The JMX Connector also follows the JMX final spec and
API.
</DIV>
<BR>
<DIV class="para" ALIGN="left">
You use JMX first when you start jBoss because the Main class loads the MLET tags
from the
jboss.conf file and hand it over to the MBeanServer which loads the MBean
dynamically (MLET
is the tag to dynamically load a MBean by the MBeanServer). Afterwards it went
through the
loaded MBeans and starts all the loaded MBeans.
</DIV>
<DIV class="para" ALIGN="left">
Afterwards you can use JMX either trough the JMX HMTL Adaptor on port 8082 or
through the new
JMX Connector. The JMX HTML Adaptor is provided by the JMX-RI and the source code is
not
available (it is part of Sun's JDMK which you have to buy when you want to get the
source
as far as I know). The JMX Connector is part of the jBoss code and should be
considered as first
draft because the Connector is mentioned within the spec by not further specified.
</DIV>
<DIV class="para" ALIGN="left">
Finally JMX is used within the shutdown hook to terminate all the services before
jBoss is
terminated itself (whatever this means) by going through all available MBeans and
send them the
stop signal (call the appropriate method).
</DIV>
<H2>Design of the JMX Connector</H2>
<H3>Introduction</H3>
<DIV class="para" ALIGN="left">
According to the JMX spec the Connector should allow a management tool to work on a
MBeanServer
and its MBeans from another JVM which can be on the same computer or a remote
computer. One
particular Connector is bound to its protocol it supports but a MBeanServer can
offer more than
one (a JMX agent has to offer at least an Adaptor or a Connector) supporting
different protocols.
Because the spec does not say much about Connectors I take the freedom and
implemented the actual
Connector within jBoss to lay the base for a remote jBoss management which is a
little bit more
comfortable than the HTML Adaptor.
</DIV>
<DIV class="para" ALIGN="left">
By the way I will take this opportunity to thanks Rickard Oeberg for his support.
</DIV>
<H3>Goals</H3>
<DIV class="para" ALIGN="left">
These are my goals for a JMX Connector:
<UL>
<LI>
Ease of use
</LI>
<LI>
From the user perspective the Connector should appear like a local MBeanServer
</LI>
<LI>
Unsupported methods throw an execption
</LI>
<LI>
Supports remote notification handling
</LI>
<LI>
First draft supports RMI protocol
</LI>
</UL>
According to the spec the JMX Connector should offer the client a Proxy for a remote
MBean but
then the MBean proxy must be available at compile time and this compite with the JMX
agent
requirements that an JMX agent has to support dynamic loading of MBeans therefore
this is
not supported now.
</DIV>
<H3>Design</H3>
<DIV class="para" ALIGN="left">
The JMX Connector is separated into 4 parts:
<OL>
<LI>
Server-side implementation
</LI>
<LI>
Client-side implementation
</LI>
<LI>
Connector Factory to lookup servers and protocols (optional)
</LI>
<LI>
Test client
</LI>
</OL>
</DIV>
<H4>Server-side implementation</H4>
<DIV class="para" ALIGN="left">
The server-side implementation is loaded and started by the MBeanServer which should
become
available for remote management. For this we have the necessary MBean service
classes, the
Connector implementation and an Object Handler class.
</DIV>
<DIV class="para" ALIGN="left">
The Object Handler class is a serializable class allowing the remote client to deal
with
remotely instantiated classes. This eliminates problems with not serializable
classes and
with the unique identification of serialized classes (on a round trip you get a copy
of
the origanal instance). The Object Handler is also used to avoid troubles with not
serializable
classes used as a Handback object in the Notification handling.
<B>This class allows the client to work on the JMX Connector as he would work on a
local
MBeanServer.</B>
</DIV>
<H4>Client-side implementation</H4>
<DIV class="para" ALIGN="left">
The client-side implementation can either be used directly by instantiating the
<B>RMIClientConnectorImpl</B> or by using the Connector Factory. The client-side
Connector
is more or less a MBeanServer which sends the request over the supported protocol to
the
server-side connector and returns the returned object back to the caller. There are
a few
methods which cannot be supported and therefore throw a unsupported operation
exception.
</DIV>
<DIV class="para" ALIGN="left">
To make it clear and also for documentation purpose the client-side connector
implements
the <B>JMXConnector</B> Interface. At the moment I want still keep this interface
even when
MBeanServer is now an interface too because which all good programming techniques it
is
(at least at the moment) not possible to make it 100% transparent (but see later
under
limitations).
</DIV>
<H4>Connector Factory</H4>
<DIV class="para" ALIGN="left">
When I started with the JMX Connector I had a management tool in mind like the
network
administration tool from CA or the proposed AppCenter from Inprise. Therefore I want
to
make it as easy as possible for the client to connector as many remote MBeanServers
as
he/she wants and which any protocol available. The client should never have to worry
about the protocol or to know which classes are behind. That's why I created the
Connector
Factory which allows the client to search for all the remote available MBeanServers
and
their supported protocols. The user only has to select a server and then a protocol
and
the Connector Factory returns the appropriate instance of the JMXConnector interface.
</DIV>
<H4>Test Client</H4>
<DIV class="para" ALIGN="left">
The JMX Connector Test Client is first a test tool that the JMX Connector is working
and second a demonstration how to use it. The test tool first starts a local
MBeanServer
and register the Connector Factory as first and then only MBean. Now the test client
ask the Connector Factory for all available, remote MBeanServers and let the user
select
one, then it asks the Connector Factory for all available Connectors or more precise
all
the supported protocols of the available Connectors. Now the user can select the
protocol
and the Test Client loads and starts the appropriate Connector (if avaialable) and
register
it as a new MBean at the local MBeanServer. Afterwards it asks the Connector for all
available MBeans on the remote server, displays it wit all the attributes and
operations
on this remote MBean. At the end it will try to register to all remote MBeans a
notification
listener which will inform the client about notification send by the MBean. That's
why the
test client will still run after finishing. When the user terminates the Test Client
it will
remove all the notification listeners from the remote MBeanServer and terminate the
Test
Client.
</DIV>
<H2>How To use the JMX Connector</H2>
<DIV class="para" ALIGN="left">
You need the following to use the JMX Connector:
<UL>
<LI>
Connector.jar (from client directory)
</LI>
<LI>
jnp-client.jar (from client directory)
</LI>
<LI>
jmxri.jar (from lib directory)
</LI>
<LI>
jndi.properties (from conf directory) which you propably have to adjust
</LI>
</UL>
</DIV>
<H3>Client how knows the server and protocol</H3>
<DIV class="para" ALIGN="left">
<OL>
<LI>
Instantiate the <B>RMIClientConnectorImp</B>.
</LI>
<LI>
Use either instance or its interface <B>JMXConnector</B> or <B>MBeanServer</B>. If
you got
back an instance you can now work on the remote MBeanServer like it would be a local
one.
</LI>
<LI>
Look up for the available MBeans, its attributes and operations. You can now
retrieve and
set the attributes or perform an operation on the remote MBean.
</LI>
<LI>
If you register a Notification Listener then <B>stop this instance</B> before
terminating
the program otherwise the remote MBeanServer will throw an exception when this
Notification
Listener is called.
</LI>
</OL>
</DIV>
<H3>Client how do not know the server and protocol</H3>
<DIV class="para" ALIGN="left">
<OL>
<LI>
Instantiate a local MBeanServer (MBeanServerImpl)
</LI>
<LI>
Load and start the ConnectorFactory MBean
</LI>
<LI>
Look for the list of servers and within a server for the list of protocols
</LI>
<LI>
Create a connection to the selected Connector
</LI>
<LI>
Use the new Connector MBean on the local MBeanServer to get and set the attributes
and perform
operation on the choosen MBeans on the remote MBeanServer.
</LI>
<LI>
Register a Notification Listener on a remote MBean and wait for notification events
sent from
the remote MBean. But when you terminate the connector you have to <B>stop</B> the
MBean Connector
on the local MBeanServer to remove all the Notification Listener from the remote
MBeanServer.
</LI>
</OL>
</DIV>
<H2>ToDo List</H2>
<DIV class="para" ALIGN="left">
This list contains all the stuff to be done to make the JMX Connector full fledged:
<UL>
<LI>
Implement the server lookup in the Connector Factory to work with JNDI
</LI>
<LI>
Implement the protocol lookup in the Connector Factory to work with JNDI
</LI>
<LI>
Test all to make sure that it works from any other JVM that the jBoss VM
</LI>
</UL>
</DIV>
<DIV class="para" ALIGN="left">
This list contains all the stuff to be done around JMX
<UL>
<LI>
Initiate and start full fledged JMX Agent project
</LI>
<LI>
Design and implement Relation Service for the JMX Agent
</LI>
<LI>
Design and implement graphic management tool for jBoss
</LI>
</UL>
</DIV>
<DIV class="footer" ALIGN="left">
I anything is wrong or not correct please contact me at
<A HREF="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A>.
Also if you want to know more in detail or have a request for changes in the JMX
Connector.
</DIV>
</DIV>
</BODY>
</HTML>
