Creating a New JOnAS Service

The content of this guide is the following:

1. Target Audience and Rationale
2. Introducing a new Service
3. Advanced Understanding

Target Audience and Rationale

This chapter is intended for advanced JOnAS users who require that some "external" services run along with the JOnAS server. A service is something that may be initialized, started, and stopped. JOnAS itself already defines a set of services, some of which are cornerstones of the JONAS Server. The JOnAS pre-defined services are listed in Configuring JOnAS services.

J2EE application developers may need to access other services, for example another Web container or a Versant container, for their components. Thus, it is important that such services be able to run along with the application server. To achieve this, it is possible to define them as JOnAS services.

This chapter describes how to define a new JOnAS service and how to specify which service should be started with the JOnAS server.

Introducing a new Service

The customary way to define a new JOnAS service is to encapsulate it in a class whose interface is known by JOnAS. More precisely, such a class provides a way to initialize, start, and stop the service. Then, the jonas.properties file must be modified to make JOnAS aware of this service.

Defining the Service class

A JOnAS service is represented by a class that implements the interface org.objectweb.jonas.service.Service, and, thus should implement the following methods:

• public void init(Context ctx) throws ServiceException;
• public void start() throws ServiceException;
• public void stop() throws ServiceException;
• public boolean isStarted();
• public String getName();
• public void setName(String name);

It should also define a public constructor with no argument.

These methods will be called by JOnAS for initializing, starting, and stopping the service. Configuration parameters are provided to the initialization method through a naming context. This naming context is built from properties defined in the jonas.properties file as explained in the following section.

The Service class should look like the following:

package a.b;
import javax.naming.Context;
import javax.naming.NamingException;
import org.objectweb.jonas.service.Service;
import org.objectweb.jonas.service.ServiceException;
.....
public class MyService implements Service {
    private String name = null;
    private boolean started = false;
    .....
    public void init(Context ctx) throws ServiceException {
        try {
            String p1 = (String) ctx.lookup("jonas.service.serv1.p1");
            .....
        } catch (NamingException e) {
            throw new ServiceException("....", e);
        }
        .....
    }
    public void start() throws ServiceException {
        .....
        this.started = true;
    }
    public void stop() throws ServiceException {
        if (this.started) {
            this.started = false;
            .....
        }
    }
    public boolean isStarted() {
        return this.started;
    }
    public String getName() {
        return this.name;
    }
    public void setName(String name) {
        this.name = name;
    }
}
    

Modifying the jonas.properties file

The service is defined and its initialization parameters specified in the jonas.properties file. First, choose a name for the service (e.g. "serv1"), then do the following:

• add this name to the jonas.services property; this property defines the set of services (comma-separated) that will be started with JOnAS, in the order of this list.
• add a jonas.service.serv1.class property specifying the service class.
• add as many jonas.service.serv1.XXX properties specifying the service initialization parameters, as will be made available to the service class via the Context argument of the init method.

This is illustrated as follows:

  jonas.services                   .......,serv1
  jonas.service.serv1.class        a.b.MyService
  jonas.service.serv1.p1           value
    

Using the New Service

import org.objectweb.jonas.service.ServiceException;
import org.objectweb.jonas.service.ServiceManager;

    MyService sv = null;

        // Get a reference on MyService.
        try {
            sv = (MyService) ServiceManager.getInstance().getService("serv1");
        } catch (ServiceException e) {
            Trace.errln("Cannot find MyService:"+e);
        }
    

Adding the class of the new service to JOnAS

Package the class of the service into a .jar file and add the jar in the JONAS_ROOT/lib/ext directory.
All the libraries required by the service can also be placed in this directory.

Advanced Understanding

Refer to the JOnAS sources for more details about the classes mentioned in this section.

JOnAS built-in services

The existing JOnAS services are the following:

If all of these services are required, they will be launched in the following order: registry, jmx, security, jtm,dbm,mail,jms,resource,ejb, ws, web, ear.
jmx, security, dbm, mail, resource are optional when you are using service ejb.

registry must be launched first.
(Note that for reasons of compatability with previous versions of JOnAS, if registry is unintentionally not set as the first service to launch, JOnAS will automatically launch the registry service.)

A jonas.properties file looks like the following:

  .....
  .....

  jonas.services                registry,jmx,security,jtm,dbm,mail,jms,ejb,resource,serv1 

  jonas.service.registry.class  org.objectweb.jonas.registry.RegistryServiceImpl
  jonas.service.registry.mode        automatic

  jonas.service.dbm.class       org.objectweb.jonas.dbm.DataBaseServiceImpl
  jonas.service.dbm.datasources Oracle1

  jonas.service.ejb.class       org.objectweb.jonas.container.EJBServiceImpl
  jonas.service.ejb.descriptors ejb-jar.jar
  jonas.service.ejb.parsingwithvalidation  true
  jonas.service.ejb.mdbthreadpoolsize      10

  jonas.service.web.class        org.objectweb.jonas.web.catalina.CatalinaJWebContainerServiceImpl
  jonas.service.web.descriptors        war.war
  jonas.service.web.parsingwithvalidation  true

  jonas.service.ear.class       org.objectweb.jonas.ear.EarServiceImpl
  jonas.service.ear.descriptors j2ee-application.ear
  jonas.service.ear.parsingwithvalidation  true

  jonas.service.jms.class       org.objectweb.jonas.jms.JmsServiceImpl
  jonas.service.jms.mom         org.objectweb.jonas_jms.JmsAdminForJoram
  jonas.service.jms.collocated  true
  jonas.service.jms.url         joram://localhost:16010

  jonas.service.jmx.class       org.objectweb.jonas.jmx.JmxServiceImpl

  jonas.service.jtm.class       org.objectweb.jonas.jtm.TransactionServiceImpl
  jonas.service.jtm.remote      false
  jonas.service.jtm.timeout     60

  jonas.service.mail.class        org.objectweb.jonas.mail.MailServiceImpl
  jonas.service.mail.factories  MailSession1

  jonas.service.security.class  org.objectweb.jonas.security.JonasSecurityServiceImpl

  jonas.service.resource.class        org.objectweb.jonas.resource.ResourceServiceImpl
  jonas.service.resource.resources         MyRA

  jonas.service.serv1.class     a.b.MyService
  jonas.service.serv1.p1        John
    

The ServiceException

The org.objectweb.jonas.service.ServiceException exception is defined for Services. Its type is java.lang.RuntimeException. and it can encapsulate any java.lang.Throwable.

The ServiceManager

The org.objectweb.jonas.service.ServiceManager class is responsible for creating, initializing, and launching the services. It can also return a service from its name and list all the services.