Creating A JBoss Service Archive (SAR) Component

This write up provides a look into the JBoss’ service archive (SAR) mechanism. SAR is based on JBoss’ underlying architecture which is based on the Java Management eXtension (JMX), a standard API designed for hosting manageable Java objects. The article includes a full example that illustrates how to create and deploy your own JBoss service archive components.

The JBoss Service Architecture
The JBoss application server (version 4), is composed of a collection of loosely coupled components that are loaded and function independently. These components provide all operational services necessary to have a functional Enterprise Java application server. These components are packaged and deployed as a Service Archives (or SAR’s). Examples of JBoss service components include the Service Archive Deployer (yes, the component that deploys all other components is itself a service component), servlet container SAR, EJB Deployer SAR, messaging SAR, etc.

JBoss's service archive architecture is based on the Java Extension Management (JMX). In fact, the JBoss microkernel (the bare infrastructure without any of the installed services) is an implementation of the JMX API (see JMX in resources). During the server bootup process, the service archive deployer (SARDeployer) instantiates the JBoss service classes and exposes them as manageable beans through JMX. You can view all of registered JBoss service components in the JBoss JMX Console web application.

Besides JBoss’ built-in components, you can build and deploy your own service archives for JBoss. Creating a service component is a great way to extend the set of functionalities found in the server by introducing your own. For instance, you could develop a service component to monitor the server’s health or one that generates notifications when a value in a database table changes to an undesirable state. This article discusses a full example that illustrates how to develop your own service archive component using the JBoss service API.

Creating a Simple Service Archive
In its simiplest form, a JBoss service is nothing more than a class that implements a JMX standard MBean interface (if you are new to JMX, see the reference section). A standard MBean interface, in turn, is simply an interface with the “*MBean” name pattern. Once you have implemented your interface, it is ready to be deployed as a JBoss service, represented internally as a JMX MBean.

Pre-requisites:

• JBoss Application Server v 4.x

• IDE (Netbeans, Eclipse, IntelliJ, etc)

• Ant (usually included with IDE)

Build-time Library Dependencies

• Jakarta Commons IO

• Jakarta Commons Logging

• jboss-common.jar

• jboss-jmx.jar

• jboss-system.jar

• jboss-xml-binding.jar

Run-time Dependencies

• Jakarta Commons IO

• Jakarta Commons Logging

The steps bellow illustrate how to build the JBoss service archive and its associated components. You can download the full source code for this example (see Resources) to get a better idea how the SAR is built and deployed.

1. Create Project
   Create a Java project in your favorite IDE, then add a service descriptor file to your source directory (src used for this example) in src/META-INF/jboss-service.xml. The figure below shows the list of files that
   
   
   
   

2. Create an interface called DirectoryMonitorMBean and add the following methods:
   - public void setScanRate(long rate) // scan period
   - public void setDirectory(String dir) // directory to scan
   - public void setExtensionList(String list) // list of extensions or *
   
   It is always a good practice to provide life cycle management methods for your services. So, add the following methods to your interface:
   - public void start() // starts service
   - public void stop() // stops service
   - public boolean isStarted() // service status indicator
   
   

NOTE: The JBoss SARDeployer recognizes certain method signatures and automatically invokes them during certain life cycle events. So, if your service interface has public methods create(), start(), stop(), or destroy(), the JBoss SARDeployer will automatically call these methods during the deployment and other control phases of the component. For instance, if your component has a start() method, the SARDeployer will call that method after your component is fully instantiated and registered with the server.

3. Create a new implementation class, DirectoryMonitor, that implements DirectoryMonitorMBean. As prescribed by the standard MBean specs, the implemented class must have the same name as the MBean interface minus the ‘MBean’ suffix. So, DirectoryMonitorMBean interface must be implemented by a class named DirectoryMonitor to be properly exposed as a JMX MBean.
   
   The DirectoryMonitor class scans a specified directory for a given file extension (or list of extensions). For simplicity sake, all necessary logic for scanning is encapsulated within this one class. The meat of the scanner logic is delegated to a separate inner class that creates a thread and continuously loops then sleeps the thread for time = scan rate.

The code snippet above shows the thread’s implementation for the scanner. It uses the Jakarta’s Common IO API to get a list of files using the file’s extension as filters. It loops forever (until the DirectoryMonitor.isStarted() = false). When a file of the specified extension is found, it calls the monitor’s takeAction(Collection) method to handle the files that are found (see source for full listing).

4. Update the service deployment descriptor file META-INF/jboss-service.xml. Add an entry for the new service component that was implemented in step 3:
   
   

In the descriptor snippet, the tag declares a class (service.DirectorMonitor) that implements the MBean service interface that will be deployed as a SAR component. The “name” attribute (for ) specifies a unique JMX-formatted name that is used as an identifier for the component. A JMX name has a the following standard pattern of domain:key0=value0[,keyN=valueN]* where domain is an arbitrary value followed by a colon and a list of key/value pair(s). In this instance the name is service.directory.monitor:service=DirectoryMonitor where service.directory.monitor is the domain.

The tags points to the bean’s accessor methods (get/set ScanRate, Directory, and ExtensionList) and allows default values to be injected into the component at deployment time. For instance, attribute name “Directory” is associated getDirectory() and setDirectory() methods. Note, however, that the name is capitalized which is unlike other bean-driven frameworks (such as Spring) where the bean property name is usually lower case.

5. Build your project and make sure to include the Jakarta Commons library dependencies. The sample code uses an ant build file (build-project.xml) to build the project properly with all necessary dependencies. Once you have the project built, you can deploy the service archive in one of two ways. You can create a jar file with the .sar extension (instead of jar) or you can deploy it as an exploded directory (with the .sar in the name). In either instance, make sure that your sar file or directory contains the necessary jars and java classes to satify the archive's dependencies (the sar’s directory structure should look something like this):
   
   

The Ant build script included with the source code will build either a sar file or create an exploded directory with all necessary artifacts. The script also names the files properly so that all you do is copy it to your JBoss deploy directory for deployment (see next step).

6. The last step is to deploy and verify the service archive. While JBoss is running, drop your sar file (or exploded directory) in the servers’s auto deploy directory. After the service is fully deployed, it will start scanning immediately. This is because the SARDeployer calls the start() method once the component is created. If the specified directory contains files with the correct extensions, you will see the message logged in the takeAction() method:
   
   
   
   Another place to validate the deployment of the service is through JBoss’ JMX console (if you have it installed). Go to the console and your new service should be listed as JMX component on the console.
   
   The service component will be listed under the JMX name that was entered in the service descriptor file, in this case “service.directory.monitor” Since your component is like any another JBoss components in the console, you have the ability to control it (start, stop, etc) directly from the console without restarting the server (hence a service)
   
   Click on the service component from the JMX console to get a detailed view of its MBean attributes and methods. As you can see (below), all the attributes (getters / setters) and the methods of your MBean interface are exposed for management. You can change the values at run time without requiring a restart from the server.
   
   

Using the Directory Scanner Component

Use the JMX console to enter new values for the service component. For instance, change the scan rate and hit button “Apply Changes”. The new value will be displayed. Then stop and start the component so the changes can take effect. Switch to your command line console to verify that your changes have taken effect.

Conclusion

In this article, we've taken an introductory look at JBoss's service archive (SAR) architecture.

SAR is a way to create and deploy autonomous components that allows you to expose system wide services to other components and resources deployed on the server. Similar to all other components in JBoss, a SAR is exposed as an MBean on the JMX microkernel, which is at the core of the JBoss server architecture.

Creating a simple SAR involves creating an interface and implementation class that follows the JMX standard MBean naming pattern. JBoss provides a simple, but rich, vocabulary for creating a SAR deployment descriptor files. Once deployed, your SAR is listed in JBoss' JMX console and can be controlled just like any other JBoss components.

The JBoss Service Archive architecture is remarkably flexible and allows developers to extend the JBoss microkernel however they choose. By creating service archive packages, you can deploy rich components that extend the functionality of the server to fit your business needs. In future article, I will explain how to create a more advanced service components that leverages fully the JBoss service API including the ability to listen and react to server life cycle phases and how to get reference to other components deployed on the server.

Resources

1. JBoss Server Documentation - http://docs.jboss.com/jbossas/guides/installguide/r1/en/html_single/

2. JMX - http://en.wikipedia.org/wiki/JMX

3. Download Example – http://vladimirvivien.com/download/demos/jboss-service.zip