This Blog entry is the first part of a two part series. I wanted to share knowledge gained on my current project. The project required that the application be written utilizing JBoss service technology. A JBoss service is a JMX (Java Management Extensions) compliant MBean. JBoss uses JMX as its component bus. JMX is a standard for managing and monitoring all varieties of software and hardware components from Java. An MBean is a Java object that implements one of the standard MBean interfaces and follows the associated design patterns. Enough background, let’s write a simple JBoss service. I’ll be using Eclipse 3.1 to create the service.

Create an Eclipse Project
As with any Eclipse project, we need to create a Java Project: blog-example. The project will be organized with the following directory structure:
· \src – Note: use src as the project's source directory.
· \dist
· \lib
· \resources\META-INF

Create Project Packages
Create the following project package under the src directory:
· blog.example.services

Create Support Files
The project will utilize Apache Ant (http://ant.apache.org/) to build and deploy the project. You will need an Ant build.properties file in the blog-example directory. The file sets the jboss.home and jboss.config parameters. My JBoss installation is located at C:/jboss-4.0.3SP1. Also, I use the default JBoss server configuration (C:\jboss-4.0.3SP1\server\default). Therefore, my build.properties file looks like this:

jboss.home=C:/jboss-4.0.3SP1
jboss.config=default

Next, create an Ant build.xml file in the blog-example directory. Copy the build.xml text from Appendix A.

Finally, create a jboss-service.xml file under the blog-example\resources\META-INF directory. For now, the file should just include the following text:

<?xml version="1.0" encoding="UTF-8"?>
<server>

</server>

Library Files
There are several libraries that we will import into the project. Once copied, we will add the jar files into the project. First, copy jboss-system.jar, jboss-jmx.jar, and commons-logging.jar files from the jboss.home\lib to the blog-example\lib directory. Next, copy the scheduler-plugin.jar from jboss.home \server\default\lib to the blog-example\lib directory. Finally, use the blog-example project properties dialog to add the jar files that were copied into the blog-example\lib into the Java Build Path for the project.

============================================
Tip: Remember to refresh your project before you modify the project properties. Otherwise, the jar files will not be available to add to the project’s build path
============================================

Create an MBean Interface
Now it is time to create the MBean interface. Select the blog.example.services package and create an interface called BlogExampleServiceMBean that extends the abstract interface org.jboss.system.ServiceMBean. The ServiceMBean interface is located in the jboss-system.jar file. This interface exposes the lifecycle methods, and a couple of other informational attributes for state and name.

Create a ServiceMBeanSupport Class
After the MBean interface is coded, create a class, in the blog.example.services package, called BlogExampleService that extends org.jboss.system.ServiceMBeanSupport and implements the MBean interface you just created: BlogExampleMBean.  Finally, use Eclipse to add the unimplemented methods. The following methods will be added:

getName()
getState()
getStateString()
jbossInternalLifecycle(String arg0)
create()
start()
stop()
destroy()
preRegister(MBeanServer arg0, ObjectName arg1)
postRegister(Boolean arg0)
preDeregister()
postDeregister()

To discover the lifecycle calls for the service, we will use log statements within the implemented methods. Add the following class definition to the BlogExampleService class:

private static Log _log = LogFactory.getLog(BlogExampleService.class.getName());

Now add logging information to all the methods like follows:

_log.info("BlogExampleService ============ methodName()");

==============================================
Warning: If the service class (ServiceMBeanSupport) is called <servicename>, the interface must be called <servicename>MBean. Otherwise, you will receive a Class does not expose a management interface exception.
==============================================

Modify the jboss-service.xml file
It is time to add the BlogExampleService description in the jboss-service.xml. The file is located under the blog-example\resources\META-INF directory. Add the following entry within the <server> tags:

 <mbean code="blog.example.services.BlogExampleService"
  name="blog.example:service=BlogExampleService">
 </mbean>

The code value is the full service class name. The name is a reference to the service. This reference will be show up in the JMX-Console once we deploy the SAR file into the JBoss Application Server.

Set the Name of the Service
We must override the getName() method for the service class…

public String getName() {
     _log.info("BlogExampleService ============ getName()");
     return "blog.example:service=BlogExampleService";
 }

This name must match the name attribute set in the jboss-service.xml.

Start JBoss Applicaiton Server
Before the service is deployed, start JBoss

Create and Deploy the SAR File
The project file needs to be complied and archived into a SAR File.
The JBoss documentation describes the SAR File:

A SAR file is essentially a jar file which gets interpreted by JBoss in a slightly different manner. This file should have all the source code for your MBean and the service (it may also contain references to other jar files in its META-INF) and a jboss-service.xml file inside META-INF directory. The jboss-service.xml file should have all the information about the service and required attributes.

Fortunately, the ANT build.xml file automates compiling, creating, and deploying the SAR File. Run the deploy target, you should see the following output in the Eclipse console:

Buildfile: C:\psBlogs\blog-example\build.xml
compile:
    [mkdir] Created dir: C:\psBlogs\blog-example\build
    [javac] Compiling 2 source files to C:\psBlogs\blog-example\build
dist:
     [copy] Copying 1 file to C:\psBlogs\blog-example\build
      [jar] Building jar: C:\psBlogs\blog-example\dist\blog_example.sar
deploy:
     [copy] Copying 1 file to C:\jboss-4.0.3SP1\server\default\deploy
BUILD SUCCESSFUL
Total time: 3 seconds

Test the Service
Once the SAR is deployed.  The JBoss console displays the following output fragment from the log output added to each method:

BlogExampleService ================= preRegister()
BlogExampleService ================= postRegister()
BlogExampleService =============== jbossInternalLifecycle()
BlogExampleService =============== jbossInternalLifecycle()
BlogExampleService ================= getState()

Start the JBoss Console
Enter http://localhost:8080/ in the browser. Select the jmx-console hyperlink under the JBoss Management category. The JMX Agent View page will display the registered service domains; including the blog.example domain.

Select the service=BlogExampleService link under the blog.example domain. Once selected, the JBoss console will display the following output fragment for the log output added to each method:

BlogExampleService =================== getStateString()
BlogExampleService ======================= getState()
BlogExampleService ====================== getName()

Finally, select the Invoke Button under the start() operation to execute the start method of the BlogExampleService. The JBoss console will display the log output from the start() method of our service:

BlogExampleService ========================= start()

What’s Next?
In Part I of this Blog, we created a simple JBoss service and invoked service methods from the JBoss JMX-Console. In Part II, we will extend this service to use other JBoss services.

Appendix A – Ant build.xml file

<?xml version="1.0"?>

<project name="blog_example" default="deploy" basedir=".">
<property file="build.properties"/>

<path id="classpath">
   <pathelement location="build"/>
   <fileset dir="${basedir}/lib">
       <include name="*.jar"/>
   </fileset>
   <fileset dir="${jboss.home}/lib">
      <include name="*.jar"/>
   </fileset>
   <fileset dir="${jboss.home}/server/${jboss.config}/lib">
      <include name="*.jar"/>
   </fileset>
   <fileset dir="${jboss.home}/server/${jboss.config}/deploy">
      <include name="*.jar"/>
      <include name="*.sar"/>
   </fileset>
</path>

<path id="client.classpath">
   <path refid="classpath"/>
</path>

<target name="compile" description="Compile the source">
   <mkdir dir="build"/>
   <javac destdir="build"
          debug="on"
          deprecation="on"
          optimize="on"
          classpathref="classpath">
      <src path="src"/>
   </javac>
</target>

<target name="dist" depends="compile" description="Package the application">
   <copy todir="build">
      <fileset dir="resources"/>
   </copy>

   <mkdir dir="dist"/>
   <jar jarfile="dist/${ant.project.name}.sar" basedir="build"/>
</target>

<target name="deploy" depends="dist" description="Deploy the application">
   <copy todir="${jboss.home}/server/${jboss.config}/deploy">
      <fileset dir="dist"/>
   </copy>
</target>

<target name="undeploy" description="Undeploy the application">
   <delete file="${jboss.home}/server/${jboss.config}/deploy/${ant.project.name}.sar"/>
</target>

<target name="clean" depends="undeploy" description="Cleanup">
   <delete dir="dist"/>
   <delete dir="build"/>
</target>
</project>