# Java Open Application Server (JOnAS) for EJBTM

This document provides a short introduction to the Enterprise JavaBeansTM (EJBTM) concepts and shows the JOnAS approach for providing an EJB environment. The document is structured as follows:

- Introduction
- The Enterprise JavaBeans Model
- Transaction Management
- Persistence Management
- Security Management
- Java Messaging Service
- Distribution

## Introduction

The SunTM Enterprise JavaBeans specification defines an architecture and interfaces for developing and deploying distributed JavaTM server applications based on a multi-tier architecture. This specification intends to facilitate and normalize the development, deployment and assembling of applicative components (called enterprise beans); such components will be deployable on EJB platforms. The resulting applications are typically transactional, database-oriented, multi-user, secured, scalable and portable. More precisely, this EJB specification describes two kinds of information:

- The first one is the runtime environment, called EJB server, which provides the execution environment together with the transactional service, the distribution mechanisms, the persistence management and the security.
- The second one is some kind of programmer's guide and user's guide explaining how an enterprise bean should be developed, deployed and used.

Not only will an enterprise bean be independent of the platform and operating system (since written in Java), but also of the EJB platform.

## The Enterprise JavaBeansTM Model

The EJBTM 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 EJB server. The interface between an EB and the EJB server is materialized by an architectural component called "container". An EJB container is generated by the tools associated to the EJB 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 "Remote 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 server.
- The deployment descriptor, containing the bean properties that may be edited at configuration time.

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 environment 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.

JOnAS implements the EJB specification, by providing the elements of an EJB Server (Transaction Manager, Persistence Manager, ...) and the tools to generate containers.

## 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 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.`

JOnAS is built on top of the JTM (JavaTM Transaction Manager), which is a Java version of the Bull OrbTP product, an implementation of the CORBA Object Transaction Service. The JTM manages distributed transactions. It handles two-phase commit protocol against any number of Resource Managers. The transactional context is implicitly propagated with the distributed requests. The JTM may be distributed across one or more EJB servers; thus a transaction may involve several beans located on different EJB servers. JTM's transactions may be demarcated explicitly by the client, or by the bean itself; transaction demarcation may also be implicit, i.e. performed by the container according to the transactional attributes values. The figure below shows different distribution architecture cases for three Enterprise Beans involved in the same transaction. JOnAS allows these different architecture configurations; this is very interesting from the performance point of view, when the architecture must be adapted to the resources distribution.

Case 1: The three beans B1, B2 and B3 are located on the same EJB server, which embeds a Java Transaction Monitor.

Case 2: The three beans are located on different EJB servers, one of them running the Java Transaction Monitor, which manages the global transaction.

Case 3: The three beans are located on different EJB servers, the Java Transaction Monitor is running outside of any EJB server.

Case 4: The three beans are located on different EJB servers. Each EJB server is running a Java Transaction Monitor. One of the JTM acts as the master monitor, while the two others are slaves.

Of course, the EJB servers may be located on the same or on different machines. Each EJB server runs in a separate Java Virtual Machine (JVM), as well as the JTM when it runs in a stand alone way (not within an EJB server, as in case 3).

## 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 (or JSQL) to access relational databases, or using other (proprietary) classes for accessing non relational data storages.

With JOnAS, the support of entity beans conforms to the EJB specification and is based on JDBC :

- Bean-Managed Persistence : the bean provider is able to develop entity beans, the states of which are stored in relational databases. The bean provider should develop the data access methods using the JDBC interface.
- Container-Managed Persistence : data storage and access operations (in a relational database) are automatically handled by the EJB environment. The bean provider only needs to provide a bean descriptor containing information about the fields mapping into the database schema and the JDBC DataSource (driver and database URL).

Currently, persistence management is supported via the JDBC interface on most relational databases (Oracle, Informix, Sybase, InstantDb, Postgres, Ingres, Interbase, SQL Server, ...) and also on the Versant Object-Oriented database (this last feature is provided by the Libelis partner). JOnAS supports JDBC 2.0 drivers (with XA interfaces) and thus is able to perform two-phase commit.

JOnAS will evolve towards EJB 2.0 persistence management which includes the support of relationships between entity beans.

## 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 platform 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.

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 server), which must initiate and propagate the security context with calls to EJB. A running example with Tomcat is provided.
- There is no mapping concerning the security between JOnAS and the target operational environment. That is to say that the roles defined for JOnAS can't be mapped to roles of the target operational environment (e.g. groups on Unix)

## Java Messaging Service

For asynchronous EJB method invocation, JOnAS provides Message-driven Beans 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 EJB 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... The EJB Container is able to take into account these JMS operations within a global EJB transaction which may include other resources such as databases.

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

In the JOnAS JMS integration, JOnAS makes use of a third party JMS implementation (currently the Joram opensource is integrated and delivered with JOnAS, the SwiftMQ product may also be used, other JMS provider implementations may easily be integrated). JOnAS provides facilities to automatically create JMS administered objects such as the connection factories and the destinations at server launching time.

## Distribution

The distributed environment in the EJB world is RMI. Currently JOnAS is working on two distributed processing environments:

- RMI using the SunTM proprietary protocol JRMP
- Jeremie: the RMI personality of an Object Request Broker called Jonathan , which also provides a CORBA personality.

Used with Jeremie, JOnAS benefits from local RMI calls optimization.

In the future, JOnAS will support RMI/IIOP, thus providing CORBA interoperability.

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