JOnAS Services

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

Target Audience and Rationale

This chapter is dedicated to advanced JOnAS users who need some "external" services to be run together with the EJB server. A service is something that may be initialized, started and stopped. JOnAS itself already defines a set of services, some of them being cornerstones of the EJB Server. The JOnAS pre-defined services are the Registry, Tomcat Service, Transaction Manager, the Security Manager, the Database Service, the JMS Service, the Ejb Service and the JMX Service, all of them being used by most of the EJB applications.

Some EJB application developers may need to access other services for their components. Examples of such services are another Web container, a Versant container, ... Thus, it is important that such services could be run together with the EJB server. To achieve that, you have the possibility to define it as a JOnAS service.

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

Introducing a new Service

The main principle for defining a new JOnAS service is to encapsulate it in a class whose interface is well known by JOnAS. More precisely, such a class allows to initialize, start and stop the service. Then you should make JOnAS aware of such a service by modifying the jonas.properties file.

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

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 initialisation method through a naming context. This naming context is built from properties defined in the jonas.properties file as explained in the section below.

The Service class should look like the following:

package a.b;
import java.naming.Context;
import java.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 = ctx.lookup("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

In the jonas.properties file, you should define your service and specify its initialization parameters. The first step is to choose a name for the service (e.g. "serv1"), and then

This is illustrated below:

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

Using the New Service

The new service has been given a name in jonas.properties. With this name, it is possible to get a reference on the service implementation class by using the ServiceManager method: getService(name). Here after is an example of accessing a 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);
	}
    

Advanced Understanding

The reader may refer to the JOnAS sources for more details about the classes mentionned in this section.

JOnAS built-in services

The JOnAS existing services are the following:

Service name Service class
registry RegistryServiceImpl
tomcat EmbeddedTomcatImpl33
ejb EJBServiceImpl
dbm DataBaseServiceImpl
jms JmsServiceImpl
jmx JmxServiceImpl
jtm TransactionServiceImpl
resource ResourceServiceImpl
security JonasSecurityServiceImpl

If you need all these services they will be launched in the following order: registry, tomcat, jmx, security, jtm, dbm, jms, resource, ejb.
jmx, security, dbm, resource are optional when you are using service ejb.

registry must be launched first.
(Note that for compatibility reasons with previous version of JOnAS if you forget to set registry as first service to launch, JOnAS will automatically launch the registry service.


Note that: dbm, jms,resource and ejb depends on jtm.

It is possible to launch a stand alone Transaction Manager with only the registry and jtm services.
It is possible to launch a JOnAS server with only the registry and tomcat services.

A jonas.properties file now looks like the following:

  .....
  .....

  jonas.services                registry,jmx,security,jtm,dbm,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.xml
  jonas.service.ejb.mdbthreadpoolsize      10

  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.security.class  org.objectweb.jonas.security.JonasSecurityServiceImpl

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

  jonas.service.tomcat.class org.objectweb.jonas.tomcat.EmbeddedTomcatImpl33

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

The ServiceException

For the purpose of Services, the org.objectweb.jonas.service.ServiceException exception is defined. Its type is java.lang.RuntimeException. and it may encapsulate any java.lang.Throwable.

The ServiceManager

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