svn commit: r1393623 - /karaf/trunk/manual/src/main/webapp/users-guide/jmx.conf

[cm...@apache.org]

Author: cmoulliard
Date: Wed Oct  3 17:15:10 2012
New Revision: 1393623

URL: http://svn.apache.org/viewvc?rev=1393623&view=rev
Log:
KARAF-1891: Document karaf manual for registering its own MBeans

Modified:
    karaf/trunk/manual/src/main/webapp/users-guide/jmx.conf

Modified: karaf/trunk/manual/src/main/webapp/users-guide/jmx.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/jmx.conf?rev=1393623&r1=1393622&r2=1393623&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/jmx.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/jmx.conf Wed Oct  3 17:15:10 2012
@@ -1,7 +1,7 @@
 
 h1. Monitoring and Administration using JMX
 
-Apache Karaf provides a large set of MBeans that allow you to fully monitore and administrate Karaf using any JMX client
+Apache Karaf provides a large set of MBeans that allow you to fully monitor and administrate Karaf using any JMX client
 (like jconsole for instance).
 
 You can find more or less the same actions that you can do using the shell commands on the JMX layer.
@@ -40,4 +40,79 @@ Apache Karaf provides the following MBea
 * org.apache.karaf:type=system to shutdown the Karaf container itself
 * org.apache.karaf:type=web to get information about the Web bundles (installed with the war feature)
 * org.apache.karaf:type=http to get information about the HTTP servlet
-* org.apache.karaf:type=obr to manipulate the OBR layer (installed with the obr feature)
\ No newline at end of file
+* org.apache.karaf:type=obr to manipulate the OBR layer (installed with the obr feature)
+
+h1. Registering its own MBean(s)
+
+The Karaf container exposes a MBeanServer as an OSGI service. This server is created when Karaf boots and can be used to registers its own MBeans. The processus is really simple as it only
+requires that the bean/pojo of the project extend the javax.management.StandardMBean class and implements an interface where the name of the class MUST contain the extension MBean.
+
+Here is an example based on Karaf WebMBean
+
+1. Interface definition
+
+As mentioned before, remark that we have added MBean after Web word.
+{code}
+/**
+ * Describe the web MBean.
+ */
+public interface WebMBean {
+...
+}
+{code}
+
+2. Implementation
+
+The class must extend the javax.management.StandardMBean class and implements the interface
+{code}
+/**
+ * Implementation of the web MBean.
+ */
+public class Web extends StandardMBean implements WebMBean {
+
+    private WebContainerService webContainerService;
+
+    public Web() throws NotCompliantMBeanException {
+        super(WebMBean.class);
+    }
+...
+{code}
+
+3. Blueprint file
+
+The blueprint file will contain definition of the beans to be instantiated and OSGI services to look up or register. Basically, 2 things should be done : lookup to retrieve
+the MBeanServer and next registers its Mbean using the MBeanRegister of Karaf
+{code}
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
+
+    <!-- Reference to the MBean Server -->
+    <reference id="mbeanServer" interface="javax.management.MBeanServer">
+        <reference-listener ref="mbeanRegistrer" bind-method="registerMBeanServer" unbind-method="unregisterMBeanServer"/>
+    </reference>
+
+    <!-- Web MBean -->
+    <bean id="webMBean" class="org.apache.karaf.management.mbeans.web.internal.WebMBeanImpl">
+        <property name="bundleContext" ref="blueprintBundleContext"/>
+    </bean>
+
+    <!-- MBean Registrer -->
+    <bean id="mbeanRegistrer" class="org.apache.karaf.management.MBeanRegistrer" init-method="init" destroy-method="destroy">
+        <property name="mbeans">
+            <map>
+                <entry value="org.apache.karaf:type=web,name=${karaf.name}" key-ref="webMBean"/>
+            </map>
+        </property>
+    </bean>
+
+</blueprint>
+{code}
+
+Remark : Next versions of Karaf 3.x will simplify this process as you can see here after
+
+{code}
+    <service ref="webMBean" auto-export="interfaces">
+        <service-properties>
+            <entry key="jmx.objectname" value="org.apache.karaf:type=web,name=${karaf.name}"/>
+        </service-properties>
+    </service>
+{code}
\ No newline at end of file