User: starksm
Date: 01/04/02 16:30:37
Modified: src/docs basicconfiguration.xml howtombeans.xml
Log:
First complete draft of the custom services integration via mbeans howto.
Revision Changes Path
1.8 +1 -1 manual/src/docs/basicconfiguration.xml
Index: basicconfiguration.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/basicconfiguration.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- basicconfiguration.xml 2001/04/02 21:33:24 1.7
+++ basicconfiguration.xml 2001/04/02 23:30:37 1.8
@@ -215,7 +215,7 @@
</para>
- <para>The jboss.jcml file is loaded by the
org.jboss.configuration.ConfigurationService MBean. This service acts much like the
standard JMX MLet class in that it loads and configures MBeans. The dependencies
between MBeans are managed by the org.jboss.util.ServiceControl MBean. The
ServiceControl MBean listens for REGISTRATION_NOTIFICATION and
UNREGISTRATION_NOTIFICATION JMX events to determine which MBeans are available. The
order of rgistration determines the order of initialization and startup. The
ServiceControl expects that MBeans which require depdendency management to conform to
the org.jboss.util.Service interface. This interface allows for the ordered
initialization, starting, stopping and destorying of MBeans. The ordering is based on
the order in which MBeans are specified in the jboss.jcml file. See <xref linkend =
"howto.mbeans"/> for the details of creating an MBean with depedencies on other
MBeans.</para>
+ <para>The jboss.jcml file is loaded by the
org.jboss.configuration.ConfigurationService MBean. This service acts much like the
standard JMX MLet class in that it loads and configures MBeans. The dependencies
between MBeans are managed by the org.jboss.util.ServiceControl MBean. The
ServiceControl MBean listens for REGISTRATION_NOTIFICATION and
UNREGISTRATION_NOTIFICATION JMX events to determine which MBeans are available. The
order of registration determines the order of initialization and startup. The
ServiceControl expects that MBeans which require depdendency management to conform to
the org.jboss.util.Service interface. This interface allows for the ordered
initialization, starting, stopping and destorying of MBeans. The ordering is based on
the order in which MBeans are specified in the jboss.jcml file. See <xref linkend =
"howto.mbeans"/> for the details of creating an MBean with depedencies on other
MBeans.</para>
</listitem>
<listitem>
<para id =
"jboss.dependencies-file">jboss.dependencies</para>
1.3 +39 -6 manual/src/docs/howtombeans.xml
Index: howtombeans.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/howtombeans.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- howtombeans.xml 2001/04/02 21:33:24 1.2
+++ howtombeans.xml 2001/04/02 23:30:37 1.3
@@ -1,7 +1,7 @@
<?xml version = "1.0" encoding = "UTF-8"?>
<section id = "howto.mbeans">
- <title>How to Integrate Custom MBeans</title>
- <para>
+ <title>How to Integrate Custom Services via MBeans</title>
+ <para>Author:
<author>
<firstname>Scott</firstname>
<surname>Stark</surname>
@@ -11,18 +11,19 @@
<section>
<title>Introduction</title>
<para>The best way to add services to the JBoss server is to write
your own JMX MBeans. An MBean is a Java object which implement resources and their
instrumentation interfaces as defined in the Java Management Extensions(JMX)
specification. Once written they are added to JBoss using the jboss.jcml which is used
to configure the core JBoss MBeans. The best way for your EJBs to access your new
services is to make them accessible via JNDI.</para>
- <para>There are two classes of MBeans; those that are independent of
JBoss services and those that are dependent on JBoss services. MBeans that are
independent of JBoss services are the trival case and can be written per the JMX
specification and added to a JBoss server by adding their MLET tag to the jboss.conf
file. Writing an MBean that relieas on a JBoss service like naming requires one to
follow the JBoss service pattern.</para>
+ <para>There are two classes of MBeans; those that are independent of
JBoss services and those that are dependent on JBoss services. MBeans that are
independent of JBoss services are the trival case and can be written per the JMX
specification and added to a JBoss server by adding their MLET tag to the jboss.conf
file. Writing an MBean that relies on a JBoss service like naming requires one to
follow the JBoss service pattern. Before describing how to write such an MBean, let's
go over the two JBoss services that manage the configuration and depdendencies of
MBean services; ConfigurationService and ServiceControl.</para>
<section>
<title>The ConfigurationService MBean</title>
- <para>JBoss manages dependencies between its MBeans via a
custom MBean that loads an xml variation of the standard MLet configuration file. This
custom MBean is implemented in the org.jboss.configuration.ConfigurationService class.
The ConfigurationService MBean is loaded when JBoss starts up by the JMX MLet due to
its entry in the jboss.conf file. The jboss.jcml configuration is then loaded by
invoking loadConfiguration() on the ConfigurationService MBean. The loadConfiguratoin
method performs the following steps:</para>
+ <para>JBoss manages configuration its MBean services via a
custom MBean that loads an xml variation of the standard MLet configuration file. This
custom MBean is implemented in the org.jboss.configuration.ConfigurationService class.
The ConfigurationService MBean is loaded when JBoss starts up by the JMX MLet due to
its entry in the jboss.conf file. The jboss.jcml configuration is then loaded by
invoking loadConfiguration() on the ConfigurationService MBean. The loadConfiguratoin
method performs the following steps:</para>
<procedure>
<step>
<para>Parse the jboss.jcml file and
instantiate all MBeans</para>
</step>
<step>
+ <para>Parse the optional jboss-auth.jcml</para>
<substeps>
<step>
- <para>Parse the optional
jboss-auth.jcml file and instantiate any MBeans that were not created by the parser of
the jboss.jcml file.</para>
+ <para>If jboss-auth.jcml
exists, parse the file and instantiate any MBeans that were not created by the parse
of the jboss.jcml file.</para>
</step>
<step>
<para>Apply the MBean
attribute settings from the jboss-auto.jcml file.</para>
@@ -34,9 +35,41 @@
</step>
</procedure>
</section>
+ <section>
+ <title>The ServiceControl MBean</title>
+ <para>JBoss manages dependencies between MBeans via the
org.jboss.util.ServiceControl custom MBean. . The ServiceControl MBean is also loaded
by the JMX MLet on JBoss startup. It implements the
javax.management.NotificationListener interface to receive
AttributeChangeNotification, MBeanServerNotification.REGISTRATION_NOTIFICATION and
MBeanServerNotification.UNREGISTRATION_NOTIFICATION JMX events.
AttributeChangeNotification are simply logged to the JBoss server log. The
REGISTRATION_NOTIFICATION and UNREGISTRATION_NOTIFICATION are used to determine which
MBeans are candidate JBoss service MBeans. The order of MBean registration is used as
the order of service initialization and startup. The ServiceControl MBean has four key
methods: init, start, stop and destroy.</para>
+ <section>
+ <title>The init Method</title>
+ <para>The ServiceControl <function>init</function>
method is called by the JBoss server main entry point after the jboss.jcml
configuration has been loaded. The process of loading the jboss.jcml file will have
caused the names of all loaded MBeans to have been registered with the ServiceControl
MBean due to the registration events posted by the MBeanServer. The
<function>init</function> method makes a copy of curent list of MBean names and then
proceeds to invoke the <function>init</function> method on each MBean. If successful,
the ServiceControl MBean then registers as an NotificationListener on the MBean's name
to receive AttributeChangeNotification from the MBean. The order of initialization is
the order of registration which is the same as the ordering of mbean entries in the
jboss.jcml file.</para>
+ </section>
+ <section>
+ <title>The start Method</title>
+ <para>The ServiceControl <function>start</function>
method is called by the JBoss server main entry point after the
<function>init</function> method. The <function>start</function> method makes a copy
of curent list of MBean names and then proceeds to invoke the
<function>start</function> method on each MBean.</para>
+ </section>
+ <section>
+ <title>The stop Method</title>
+ <para>The <function>stop</function> method is invoked
by the by the JBoss server shutdown process which is managed by the
org.jboss.util.Shutdown MBean. The <function>stop</function> method makes a copy of
the current list of MBean names and then invokes the <function>stop</function> method
on each MBean in reverse order.</para>
+ </section>
+ <section>
+ <title>The destroy Method</title>
+ <para>The <function>destroy</function> method is
invoked by the by the JBoss server shutdown process after the
<function>stop</function> method. The <function>destroy</function> method makes a copy
of the current list of MBean names and then invokes the <function>destroy</function>
method on each MBean in reverse order.</para>
+ </section>
+ </section>
</section>
<section>
<title>Writing JBoss MBean Services</title>
- <para/>
+ <para>Writing a custom service that integrates into the JBoss server
requires the use of the org.jboss.util.Service interface pattern if the custom service
is depdendent on other JBoss services. This means that you cannot perform any JBoss
service dependent intialization in any of the javax.management.MBeanRegistration
interface methods. Instead, you must do this in the Service interface
<function>init</function> and/or <function>start</function> methods. You need to do
one of the following:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Add any of the Service methods that you want
called on your MBean to your MBean interface.</para>
+ </listitem>
+ <listitem>
+ <para>Have your MBean interface extend the
org.jboss.util.Service interface.</para>
+ </listitem>
+ <listitem>
+ <para>Have your MBean interface extend the
org.jboss.util.ServiceMBean interface. This is a subinterface of
org.jboss.util.Service that adds <function>String getName()</function>, <function>int
getState()</function>, and <function>String getStateString()</function> methods.</para>
+ </listitem>
+ </itemizedlist>
+ <para>Which approach you choose depends on whether or not you want to
be associated with JBoss specific code. If you don't, then you would use the first
approach. If you don't mind, then the simplest approach is to have your MBean
interface extend from org.jboss.util.ServiceMBean and your MBean implementation class
extend from the abstract org.jboss.util.ServiceMBeanSupport class. This class
implements the org.jboss.util.ServiceMBean interface except for the <function>String
getName()</function> method. ServiceMBeanSupport provides implementations of the init,
start, stop and destroy methods that integrate logging and JBoss service state
management. Each method delegates any subclass specific work to initService,
startService, stopService, and destroyService methods respectively. When subclassing
ServiceMBeanSupport you would override one or more of the initService, startService,
stopService, and destroyService methods in addition to getName as required.</para>
</section>
</section>
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-development
