# Java Open Application Server (JOnAS): a J2EETM Platform

This document presents the JOnAS J2EE platform. After a short introduction of the J2EE concepts, the JOnAS server architecture and features are presented. For people not familiar with the J2EE, the last section introduces the main principles of this platform. The document is structured as follows:

- Introduction
- JOnAS Features
  - System Requirements
  - Java Standard Conformance
  - Key Features
- JOnAS Architecture
  - Registry service
  - EJB Container service
  - WEB Container service
  - Ear service
  - Transaction service
  - Database service
  - Security service
  - JMS service
  - JCA Resources service
  - JMX service
  - Mail service
- Clustering
- The J2EE Concepts
  - Servlet/JSP
  - The Enterprise JavaBeans Model
  - Transaction Management
  - Persistence Management
  - Security Management
  - Java Messaging Service
  - Java Connector Architecture
  - Class loader hierarchy

## Introduction

The SunTM J2EE specification, together with its related specifications ( EJBTM, JMSTM,...), defines an architecture and interfaces for developing and deploying distributed internet JavaTM server applications based on a multi-tier architecture. This specification intends to facilitate and normalize the development, deployment and assembling of applicative components; such components will be deployable on J2EE platforms. The resulting applications are typically web based, transactional, database-oriented, multi-user, secured, scalable and portable. More precisely, this specification describes two kinds of information:

- The first one is the runtime environment, called J2EE server, which provides the execution environment and the required system services such as the transaction service, the persistence service, the JMS service, the security service ...
- The second one is some kind of programmer's guide and user's guide explaining how an application component should be developed, deployed and used.

Not only will an application component be independent of the platform and operating system (since written in Java), but also of the J2EE platform.

A typical J2EE application is composed of presentation components, also called "web components" (Servlets and JSPsTM), which define the application Web interface, and of enterprise components, the "Enterprise JavaBeans", which define the application business logic and application data. The J2EE server provides containers for hosting web and enterprise components. The container provides the component life cycle management and interfaces the components with the services provided by the J2EE server. There are two kinds of container, the web container handles Servlet and JSP components while the EJB container handles the Enterprise JavaBeans components.

## JOnAS Features

JOnAS is a pure Java open source application server conforming to the J2EE specification. However its high modularity allows to use it

- as a J2EE server, for deploying and running EAR applications (i.e. applications composed of both web and ejb components),
- as an EJB container, for deploying and running EJB components (e.g. for applications without web interfaces or when using JSP/Servlet engines that are not integrated as a JOnAS J2EE container),
- as a Web container, for deploying and running JSPs and Servlets (e.g. for applications without EJB components).

### System Requirements

JOnAS is available for JDK 1.3 or 1.4. It has been used on many operating systems (Linux, AIX, Windows, Solaris, HP-UX, etc.), and with different Databases (Oracle, PostgreSQL, MySQL, SQL server, Access, DB2, Versant, Informix, Interbase, etc.).

### Java Standard Conformance

JOnAS is an implementation of J2EE 1.3. It currently conforms to EJB 2.0. Its current integration of Tomcat or Jetty as Web container insures conformity to Servlet 2.3 and JSP 1.2 specifications. The JOnAS server relies on or implements the following Java APIs: JCATM 1.0, JDBCTM 2.0, JTATM 1.0.1, JMSTM 1.1, JMXTM 1.0, JNDITM 1.2.1, JAASTM 1.0 (coming soon), JavaMailTM 1.3.

### Key Features

In addition to the implementation of all J2EE related standard, JOnAS provides the following advanced and important features:

- Management: JOnAS server management uses JMX and provides a servlet based managment console.
- Services: The service based architecture of JOnAS provides a high modularity and configurability of the server. It allows to apply a component model approach at the middleware level, and makes easy the integration of new modules (e.g. for open source contributors). It also allows to start only the services needed by a particular application, thus saving useless system resources. JOnAS services are manageable through JMX.
- Scalability: JOnAS integrates several optimization mechanisms for increasing the server scalability. This includes pool of stateless session beans, pool of message-driven beans, pool of threads, cache of entity beans, activation/passivation of entity beans, pool of connections (for JDBC and JMS), storage access optimizations (shared flag, isModified).
- Distribution: JOnAS is working with two distributed processing environments, RMI using the Sun proprietary protocol JRMP, or Jeremie, the RMI personality of an Object Request Broker called Jonathan, from Objectweb. Used with Jeremie, JOnAS benefits from transparent local RMI calls optimization.

Three critical J2EE aspects have been early implemented in the JOnAS server:

- JCA: Enterprise Information Systems (EIS) may be easily accessed from JOnAS applications. By supporting the Java Connector Architecture, JOnAS allows to deploy any JCA compliant Resource Adapter (connector) that will make the corresponding EIS available from the J2EE application components. For example, Bull GCOS mainframes may be accessed from JOnAS using their associated Hoox connectors.
- JMS: JMS implementations may be easily plugged into JOnAS. They run as a JOnAS service in the same JVM or in a separate JVM and JOnAS provides administration facilities that hide the JMS proprietary administration APIs. Currently two JMS implementations may be used: the JORAM open source JMS implementation from Objectweb and SwiftMQ.
- JTA: The JOnAS platform supports distributed transactions that involve multiple components and transactional resources. The JTA transactions support is provided by a Transaction Monitor that has been developed on top of an implementation of the CORBA Transaction Service (OTS).

## JOnAS Architecture

JOnAS is architectured in term of services. A service typically provides system resources to containers. Most of the components of the JOnAS application server are pre-defined JOnAS services. However it is possible and easy for an advanced JOnAS user to define its own service and to integrate it into JOnAS. J2EE applications do not necessarily need all services, it is thus possible to define, at JOnAS server configuration time, the set of services that are to be launched at server start.

The JOnAS architecture is illustrated in the figure below, showing web and EJB containers relying on JOnAS services (all services are present on this figure). Two thin clients are also shown on this picture, one of them being the JOnAS administration console (called Jadmin).

### Registry service

This service is used for launching the RMI registry or Jeremie registry depending on the configuration of JNDI. There are different registry launching modes, i.e. in the same JVM or not, automatically if not already running, ...

### EJB Container service

This service is in charge of loading the EJB components and their containers. EJB containers are composed of a set of Java classes implementing the EJB specification and by a set of interposition classes interfacing the EJB components with the services provided by the JOnAS application server. Interposition classes are specific to each EJB component and are generated by the deployment tool called GenIC.

JOnAS configuration allows to specify this service to be launched with a set of ejb-jar files to be loaded. Ejb-jar files may also be deployed at server runtime using the JOnAS administration tools.

### WEB Container service

This service is in charge of running a Servlet/JSP Engine in the JVM of the JOnAS server, and of loading web applications ("war" files) within this engine. Currently this service may be configured to use Tomcat or Jetty. Servlet/JSP engines are integrated within JOnAS as "web containers", i.e. such containers provide the web components with access to the system resources (of the application server) and to EJB components, in a J2EE compliant way.

JOnAS configuration allows to specify this service to be launched with a set of war files to be loaded. War files may also be deployed at server runtime using the JOnAS administration tools.

### Ear service

This service is used for deploying complete J2EE applications, i.e. applications packaged in EAR files (themselves containing ejb-jar files and/or war files). This service will handle the EAR files, and will delegate the deployment of the war files, resp. ejb-jar files, to the WEB Container service, resp. to the EJB Container service. It will take care of creating the appropriate class loaders (as preconised in the J2EE specification) in order for the J2EE application to execute properly.

For deploying J2EE applications, JOnAS must be configured to launch the EAR service, and the set of EAR files to be loaded may be specified. EAR files may also be deployed at server runtime using the JOnAS administration tools.

### Transaction service

This is a Java Transaction Monitor called JOnAS JTM. It is a mandatory service which handles distributed transactions. It provides transaction management for EJB components as defined in their deployment descriptors. It handles two-phase commit protocol against any number of Resource Managers (XA Resources). For J2EE, a transactional resource my be a JDBC connection, a JMS session or a JCA Resource Adapter connection. The transactional context is implicitly propagated with the distributed requests. The JTM may be distributed across one or more JOnAS servers; thus a transaction may involve several beans located on different JOnAS servers. This service implements the JTA 1.0 specification, thus allowing to explicitly start and terminate transactions from application components of from application clients.

### Database service

This service is responsible for handling Datasource objects. A Datasource is a standard JDBC administrative object for handling connections to a database. The Database service creates and loads such datasources on the JOnAS server. Datasources to be created and deployed may be specified at JOnAS configuration time, or they may be created and deployed at server runtime using the JOnAS administration tools. The Database service is also responsible for connection pooling, i.e. it manages a pool of database connections to be used by the application components, thus avoiding many physical connection creations which are time consuming operations.

### Security service

This service implements the authorization mechanisms for accessing EJB components, as specified in the EJB specification. In JOnAS, the security is avalaible with the following restrictions:

- User authentification should be provided by the client of the EJB (e.g. the Web container), which must initiate and propagate the security context with calls to EJB. Security context initialisation and propagation has been implemented for Tomcat.
- There is no mapping concerning the security between JOnAS and the target operational environment. That is to say that the roles defined for JOnAS cannot be mapped to roles of the target operational environment (e.g. groups on Unix)

In a near future this service will be implemented on top of JAAS, and will bring the following functionalities:

- Authentification modules will be provided
- Authorization will be performed using Java security permissions
- Both web and Java clients will be supported
- Security will be dynamically configurable.

### JMS service

For supporting Message-driven Beans, and JMS operations coded within application components, the JOnAS application server relies on a JMS implementation. JOnAS makes use of a third party JMS implementation: currently the Joram opensource software is integrated and delivered with JOnAS, the SwiftMQ product may also be used, other JMS provider implementations may easily be integrated.

The JMS service is in charge of launching (or establishing connection to) the integrated JMS server, that may run in the same JVM as JOnAS or not. It also provides connection pooling. Through this service, JOnAS provides facilities to create JMS administered objects such as the connection factories and the destinations either at server launching time, or at runtime using the JOnAS administration tools.

### JCA Resources service

For accessing Enterprise Information Systems from the application server, J2EE defined the JCA. The role of the JCA Resources service is to deploy JCA compliant Resource Adapters (connectors) on the JOnAS server. Once Resource Adapters are deployed, a connection factory instance is available in the JNDI namespace to be looked up by application components.

### JMX service

The JMX service is needed in order to administrate a JOnAS server from the JOnAS Jadmin administration console. Each server running this service is visible from the administration console. This service is based on JMX. Standard MBeans are defined within the JOnAS application server, they expose the management methods of the instrumented JOnAS server objects. The JMX service runs a JMX server (currently the Sun RI one). The MBeans of the JOnAS server are registered within this JMX server which is accessed from the servlets of the Jadmin application in order to present the managed features within the administration console.

### Mail service

A J2EE application component may read or send e-mails using JavaMailTM. The Mail service of the JOnAS application server provides the necessary resources to such application components. The same way the database service or the JMS service create Datasources or ConnectionFactories and register these objects in the JNDI namespace, the Mail service create mail factories and register these resources in the JNDI namespace. There are two kinds of mail factories: javax.mail.Session and javax.mail.internet.MimePartDataSource.

## Clustering

Clustering for an application server generally brings three features: Load Balancing (LB), High Availability (HA) and Failover. Such mechanisms may be provided at the Web container level (by dispatching requests to several Servlet/JSP engine instances) and at the EJB container level (by dispatching EJB requests to several EJB server instances). A replicated JNDI naming is also necessary.

Work is going on for providing Load Balancing, HA and Failover at the EJB container level in JOnAS and for providing a "clustered aware" replicated JNDI. As JOnAS embeds third party JSP/Servlet engines, it will rely on technologies related to these softwares for providing such clustering features at the JSP/Servlet level. It is thus already possible to provide Load Balancing and HA at the Web container level using the Apache Tomcat mod_jk plug-in, this is illustrated in the figure below.

Apache is used as the font-end HTTP server, Tomcat as the JOnAS web container. The JOnAS servers share the same database. The mod_jk plug-in provides Load Balancing / High Availability at the Servlet/JSP level. Failover will be possible with future HTTP session replication mechanisms. Tomcat may run in the same JVM as the EJB container or not. JOnAS provides some documentation for configuring such an architecture.

## The J2EE Concepts

This section introduces the main concepts needed to understand the J2EE application model, and the way J2EE applications may be created.

### Servlet/JSP

Servlet and JSPTM are technologies for developing dynamic web pages. The Servlet approach allows the development of Java classes (HTTP Servlets) that may be invoked through HTTP requests and that generate HTML pages. Typically Servlets access the information system using Java APIs (as JDBC or the APIs of EJB components) in order to build the content of the HTML page they will generate in response to the HTTP request. The JSP technology is a complement of the Servlet technology. A JSP is an HTML page containing Java code within particular XML-like tags; this Java code is in charge of generating the dynamic content of the HTML page.

Servlets and JSPs are considered as J2EE application components responsible of the application presentation logic. Such application components are able to access resources provided by the J2EE server (as JDBC datasources, JMS connection factories, EJBs, mail factories, ...). As for EJB components, the actual assignment of these resources is performed at component deployment time, and is specified in the deployment descriptor of each component (the component code use logical resources names).

### The Enterprise JavaBeansTM Model

The EJB specification defines a server component model. An Enterprise JavaBean (EB) is a "non visual" software component running on the server part of an application. An EB may be configured at deployment time by editing its properties. The resources needed by an EB are transactional services, storage services, security services, naming services, messaging services, ... Such resources are provided to the bean by the application server. The interface between an EB and the application server is materialized by an architectural component called "container". An EJB container is generated by the tools associated to the application server. The container is in charge of the EB instances life cycle and persistence, and of the interaction with the transaction and security services.

An Enterprise Bean is composed of the following parts, that are to be developed by the Enterprise Bean Provider:

- The "Component Interface" is the client view of the bean. It contains the signatures of all the "business methods" of the bean.
- The "Home Interface" contains the signatures of all the methods for the bean life cycle (creation, suppression) and for instances retrieval (finding one or several beans) used by the client application.
- The bean class, which implements the business methods, and all the methods (described in the EJB specification) allowing the bean to be managed in the EJB container.
- The deployment descriptor, containing the bean properties that may be edited at configuration time.

The Component and Home interfaces may be either remote or local interfaces. Local Interfaces are to be used by a client running in the same JVM as the EJB component.

Three kinds of enterprise beans are defined in the specification:

- Session beans are objects associated to only one client, short-lived (one method call or a client session), that represent the current state of the client session. They can be transaction-aware, stateful or stateless.
- Entity beans are objects that represent data in a database. They may be shared by several clients and are identified by means of a primary key. An EJB container is responsible for managing the persistence of such objects.
- Message-driven Beans are objects that may be considered as message listeners. They execute on receipt of a JMS (Java Message Service) message, they are transaction aware and stateless. They implement some kind of asynchronous EJB method invocation.

### Transaction Management

One of the main advantages of the EJBTM support for transactions is its declarative aspect, which means that transaction control is no longer hard coded in the server application, but is configured at deployment time. This is known as "Container-managed transaction demarcation".With "Container-managed transaction demarcation" the transactional behaviour of an enterprise bean is defined at configuration time, and is part of the deployment descriptor of the bean. The EJB container is responsible for providing the transaction demarcation for the enterprise beans. The container's responsabilities depend on the value of transactional attributes associated to EB methods which can be one of the following:

- `NotSupported:` if the method is called within a transaction, this transaction is suspended during the time of the method execution.
- `Required`: if the method is called within a transaction, the method is executed in the scope of this transaction, else, a new transaction is started for the execution of the method, and committed before the method result is sent to the caller.
- `RequiresNew:` the method will always be executed within the scope of a new transaction. The new transaction is started for the execution of the method, and committed before the method result is sent to the caller. If the method is called within a transaction, this transaction is suspended before the new one is started, and resumed when the new transaction has completed.
- `Mandatory`: the method should always be called within the scope of a transaction, else the container will throw the TransactionRequired exception.
- `Supports:` the method is invoked within the caller transaction scope, if the caller does not have an associated transaction, the method is invoked without a transaction scope.
- `Never`: with this attribute the client is required to call the method without a transaction context else the Container throws the `java.rmi.RemoteException` exception.

Session beans and message-driven beans (and only these two kinds of beans) can be used with "Bean-managed transaction demarcation". In this case the Container is responsible to suspend any transaction that may be associated with the client request and must make the `javax.transaction.UserTransaction` interface available to the session or message-driven bean's business method via the `javax.ejb.EJBContext` interface and under the environment entry `java:comp/UserTransaction.`

### Persistence Management

The EJBTM specification defines three kinds of bean: Session beans, message-driven beans and entity beans. As opposed to sessions beans, an entity bean represents persistent data, i.e. it is an object view of an entity stored in a persistent storage (generally a database). The persistence management of such an object is entirely transparent to the client that will use it, and may be or may not be transparent to the bean provider that will develop it. This conforms to the EJB reference architecture where the client does not see any data access operation, such operations being used on the server side implementation only (in the enterprise bean implementation). An entity bean may be one of the two following categories:

- An enterprise bean with Container-Managed Persistence. In such a case, the bean provider does not develop any data access code, persistence management is delegated to the EJB environment (to the container). Persistence is described by the bean provider in a declarative way (as for the transactional aspects) in the bean descriptor. This description provides the mapping between the fields of the bean and the persistent storage (generally the attributes of a relational table).
- An enterprise bean with Bean-Managed Persistence. In this case, the bean provider writes the database access operations in the methods of the enterprise bean that are specified for data creation, load, store, retrieval, and remove operations (ejbCreate, ejbLoad, ejbStore, ejbFind..., ejbRemove).

In both cases, the data access operations are developed or generated by the EJB environment using JDBCTM to access relational databases, or using other (proprietary) classes for accessing non relational data storages.

### Security Management

The purpose of the security in the EJB™ architecture is to permit or not the access to the methods of an EJB.
All the concepts of security is based on the notion of roles. The methods can be accessed by a given set of roles. In order to access the methods, the user must be at least in one of this set of roles.
These roles and the mapping between roles and methods (permissions) present a simplified security view of the enterprise beans application.
When the EJB is deployed in the target operational environment, the System Administrator has to map the set of security roles to the "specific" roles of the target operational environment, e.g. groups on Unix systems.

The EJB™ specification defines two kinds of security management:

- declarative security management
- programmatic security management

The declarative one is set by the Bean Deployer or the Application Assembler to integrate the security of an EJB component in the target operational environment and the programmatic one is used by the Bean Programmer to enforce security in the code of the EJB itself in the case where the declarative one is not sufficient or not appropriate.

These two kinds of security management are not exclusive: in most "real world" applications, they complete each other to make the EJB architecture more secure.

In case of declarative security management, the Bean Deployer and the Application Assembler use the `security-role` and `method-permission` elements included in the `assembly-descriptor` element of the deployment descriptor to set up access control of the methods of the EJB component.
They're also responsible for binding the security system of the EJB architecture to the target operational environment.

For programmatic security management, the EJB container provides the Bean Programmer with two methods in order to enforce security check in the bean code:

- the `getCallerPrincipal()` method of the `javax.ejb.EJBContext` interface.
- the `isCallerInRole (String roleName)` method of the same interface.

The role names used in the EJB code (in the isCallerInRole method) are in fact references to actual security roles, which makes the EJB code independent of the security configuration described in the deployment descriptor. The programmer makes these role references available to the bean deployer or application assembler by the way of the `security-role-ref` elements included in the `session` or `entity` elements of the deployment descriptor.

### Java Messaging Service

Asynchronous EJB method invocation is possible on Message-driven Beans components, as specified in the EJB 2.0 specification. A Message-driven Bean is an EJB component which may be considered as a JMS (Java Message Service) MessageListener, i.e. which processes JMS messages asynchronously: it implements the onMessage(javax.jms.Message) method, defined in the javax.jms.MessageListener interface. It is associated with a JMS destination, the onMessage method will be activated on the reception of messages sent by a client application to this destination.

It is also possible for any EJB component to send or "synchronously receive" JMS messages, using the JMS API, and this within the scope of a global transaction managed by the application server (this was already specified in EJB 1.1). The bean programmer has the possibility to use resources (by the way of resource references) that may be JDBC (a DataSource) or JMS (a ConnectionFactory) connection factories. Thus, the bean programmer is able to provide JMS code inside of an EJB method, in order to send a message toward a JMS Queue or Topic. These messages will be received by JMS clients, which may be stand alone Java applications, EJB components, the EJB client application...

Details about JMS should be found in the Java Message Service Specification.

### Java Connector Architecture

The Java Connector Architecture (JCA) allows the connection of different Enterprise Information Systems (EIS) to a J2EE application server. It is based on the Resource Adapter (RA), an architecture component comparable to a software driver, connecting the EIS, the application server, and the enterprise application (J2EE components). The RA is generally provided by an EIS vendor, and provides a Java interface (the Common Client Interface or CCI) to the J2EE components for accessing the EIS. The RA also provides standard interfaces for being plugged to the application server, so that they can collaborate to keep all system-level mechanisms (transactions, security, and connection management) transparent from the application components.

The application performs "business logic" operations on the EIS data using the RA client API (CCI), while transactions, connections (including pooling) and security on the EIS is managed by the application server through the RA (system contract).

Sun, Java, and all Java-based trademarks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

### Class loader hierarchy

The introduction of the J2EE support and the local interface support has implied a new class loader hierarchy in JOnAS. Details about this class loader hierarchy should be found at JOnAS class loader hierarchy.