# Java Open Application Server (JOnAS): Architecture and Design

Last modified at 2005-04-22, JOnAS 4.3

This document provides an overview of the JOnAS platform architecture design. The content of this document is the following:

- Introduction
- JOnAS Service based Architecture
  - Design Principles
  - Communication and Naming service
  - EJB Container service
  - WEB Container service
  - Ear service
  - Transaction service
  - Database service
  - Security service
  - Messaging service
  - JCA Resources service
  - Management service
  - Discovery Service
  - Mail service
  - WebServices service
- JOnAS Management Architecture
- Clustering and Performance

## Introduction

This document presents the internal architectural design of the JOnAS application server. It contains many links toward the JOnAS documentation, for detailed descriptions of some aspects.

## JOnAS Service based Architecture

### Design Principles

JOnAS's service-based architecture provides for high modularity and configurability of the server. It allows to apply a component-model approach at the middleware level, and makes the integration of new modules easy (e.g. for open source contributors). It also provides a way to start only the services needed by a particular application, thus saving valuable system resources. JOnAS services are manageable through JMX.

JOnAS is designed with services in mind. 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 a service and to integrate it into JOnAS. Because J2EE applications do not necessarily need all services, it is 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 following figure, showing WEB and EJB containers relying on JOnAS services. Two thin clients are also shown in this figure, one of which is the JOnAS administration console (called JonasAdmin).

All these services correspond to JOnAS components. The JOnAS Service principle is described in detail within the JOnAS documentation, in the Creating a New JOnAS Service section of the Advanced Topic chapter. Please read this document to understand the JOnAS components wrapping within services. Generally, a JOnAS service Serv1 implementation may be found in the package org.objectweb.jonas.serv1, where an interface of the service may be found, Serv1Service, with an implementation, Serv1ServiceImpl, and an MBean for the service management purpose (as described below in the JOnAS Management Architecture section), Serv1ServiceImplMBean class.

An application server such as JOnAS must provide a complex class loading scheme, which is described in the JOnAS classloader hierarchy section of the J2EE Application Programmer's Guide of the JOnAS documentation.

The following of this section describes the existing JOnAS services.

### Communication and Naming Service

This service (also called "Registry") is used for launching the RMI registry, the CosNaming and/or the CMI registry depending on the JOnAS configuration (CAROL configuration, which specifies which communication protocols are to be used). There are different registry launching modes: in the same JVM or not, automatically if not already running. CAROL enables multi-protocol runtime support and deployment, which avoids having to redeploy components when changing the communication protocol.

JOnAS may run several distributed processing environments, thanks to the integration of the CAROL (Common Architecture for RMI ObjectWeb Layer) ObjectWeb project, which allows simultaneous support of several communication protocols:

- RMI using the Sun proprietary protocol JRMP
- RMI on IIOP
- CMI, the "Cluster aware" distribution protocol of JOnAS

This service provides the JNDI API to application components and to other services in order to bind and lookup remote objects (e.g. EJB Homes) and resource references (JDBC DataSource, Mail and JMS connection factories, etc.).

### EJB Container Service

This service is in charge of loading the EJB components and their containers. EJB containers consist of a set of Java classes that implement the EJB specification and a set of interposition classes that interface the EJB components with the services provided by the JOnAS application server. The role of the interposed classes is to manage transactions, security, ... Interposition classes are specific to each EJB component and are generated by the deployment tool called GenIC. This tool is developed using the Velocity template based generation tool.

For each EJB component XXX, GenIC generates the following classes:

- JOnASXXXBean = bean instance
- JOnASXXXHandle = handle
- JOnASXXXHome = Home implementation
- JOnASXXXLocalHome = LocalHome implementation
- JOnASXXXRemote = implements the bean Remote interface
- JOnASXXXLocal = implements the bean Local interface

These files are generated with Velocity from templates located in org.objectweb.jonas_ejb.genic (*.vm). Moreover, stubs and skeletons are generated, depending on the specified protocol (jrmp/iiop), several protocols may be specified, in this case several stubs/skeletons will be generated. CAROL is used to hide the differencies between protocols.

For implementing Container-Managed Persistence of EJB 2.0 and EJB 2.1 (CMP2), JOnAS relies on the ObjectWeb JORM (Java Object Repository Mapping) and MEDOR (Middleware Enabling Distributed Object Requests) frameworks. JORM supports complex mappings of EJBs to database tables, as well as several types of persistency support (relational databases, object databases, LDAP repositories, etc.). JORM is responsible for bean persistence. MEDOR is used to evaluate ejb-ql queries.

Generic objects used for entity beans are derived to be used by JORM:

- JEntitySwitch implements PBinding (JORM), and is responsible for Database accesses
- The bean instance implements the PAccessor interface.

Typically, the PBinding uses the PAccessor to set and get field values in the bean instance.

The lock policy is enforced in the JEntitySwitch class. Actually, this class is specialized depending on the lock policy used:

- JEntitySwitchCS = container serialized
- JEntitySwitchCRC = container read committed
- JEntitySwitchCRU = container read uncommitted
- JEntitySwitchDB = database
- JEntitySwitchRO = read only

The detailed picture of the JOnAS CMP architecture is provided below:

Each jar file is implemented in a separate Container. Each Container has a swapper that is used to periodically write bean instances

on disk, and release memory instances from the cache when JOnAS needs more memory.

For Message driven beans, the factory implements ServerSessionPool interface. For each instance, an object (JMessageDrivenBean) is created : It implements ServerSession, MessageListener, Runnable, and MessageDrivenContext interfaces.

JOnAS configuration provides a means for specifying a set of ejb-jar files to be loaded at server startup by the EJB container service. Ejb-jar files can also be deployed at server runtime using the JOnAS administration tools.

JOnAS also implements the Timer Service features as specified in EJB 2.1.

### 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 can 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 provides a means for specifying that this service be launched during JOnAS initialization. Additionally, JOnAS configuration provides a means for specifying a set of war files to be loaded at JOnAS startup. War files may also be deployed at server runtime using the JOnAS administration tools. User management for Tomcat/Jetty and JOnAS has been unified. The class-loading delegation policy (priority to the Webapp classloader or to the parent classloader) can be configured.

The web container service is implemented by using an abstract class (AbsJWebContainerServiceImpl) which needs to be extended to implement the specific Tomcat or Jetty part.
The interface of this service defines common methods like starting, stopping the embedded server, or deploy/undeploy war files. Also, these public methods are available through an MBean.
The class for Catalina 5.0 is named CatalinaJWebContainerServiceImpl and for Jetty 5.5 it is JettyJWebContainerServiceImpl. For Catalina 5.5, the name of the package is `org.objectweb.jonas.web.catalina55` instead of `org.objectweb.jonas.web.catalina50`.
To integrate a new web container, a new package `org.objectweb.jonas.web.xxx` should be added and the service class should extend AbsJWebContainerServiceImpl class.

For Tomcat, there are wrapper classes to use a specific classloader (Tomcat Classloader) instead of using the default classloader of all services running in JOnAS which is commons classloader.

Common tools to unpack wars, used by all implementations are in the package org.objectweb.jonas.web.lib

There is another package for all the stuff concerning the parsing and the handling of web deployment descriptors. This is the package org.objectweb.jonas_web.deployment which is composed of api package (used by web container service) and the other subpackages are only used internally for parsing and managing the XML files.
The only import which should occur within a web container service implementation should be the api package and not the other subpackages. This allows to change the implementation of parsing/analyzing XML files without changing the services code.

### Ear Service

This service is used for deploying complete J2EE applications, i.e. applications packaged in EAR files, which themselves contain ejb-jar files and/or war files. This service handles the EAR files and delegates the deployment of the war files to the WEB Container service and the ejb-jar files to the EJB Container service. It handles creating the appropriate class loaders, in order for the J2EE application to execute properly.

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

This service is implemented by the EarServiceImpl class. This class is linked to other services which should be started. The ear service needs an EJB service and a WebContainer service to allow to send EJBs of an EAR to the EJB service and to send web components to the web container service.
This service is pretty simple, it unpacks EAR, resolves "Class-Path:" entries of MANIFEST files and ejb-link elements, and set up JACC security. Once everything is correctly setup, it send components to each service (ejb or web) which will deploy them by using information provided by the Ear service.

As explained in web container service, all the parsing/handling of XML deployment descriptors is done in another package which is for Ear service the org.objectweb.jonas_ear.deployment package.

### Transaction Service

This service encapsulate a Java Transaction Monitor called JOTM (a project from ObjectWeb). 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 may be a JDBC connection, a JMS session, or a J2EE CA Resource Adapter connection. The transactional context is implicitly propagated with the distributed requests. The Transaction Monitor can be distributed across one or more JOnAS servers; thus a transaction may involve several components located on different JOnAS servers. This service implements the JTA 1.0.1 specification, thus allowing transactions from application components or from application clients to be explicitly started and terminated. Starting transactions from application components is only allowed from Web components, session beans, or message-driven beans (only these two types of beans, which is called "Bean-managed transaction demarcation").

The Transaction service may be found in the org.objectweb.jonas.jtm package.

### 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 can be specified at JOnAS configuration time, or they can be created and deployed at server runtime using the JOnAS administration tools. The Database service is also responsible for connection pooling; 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.

The database service should now be replaced by the JDBC Resource Adapter, to be deployed by the J2EE CA Resource Service (see below), which additionally provides JDBC PreparedStatement pooling.

The Database Service is implemented in the org.objectweb.jonas.dbm package.

### Messaging 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 open source software is integrated and delivered with JOnAS, the SwiftMQ product has also been used in previous versions of JOnAS, and other JMS provider implementations can easily be integrated. JORAM provides several noteworthy features: in particular, reliability (with a persistent mode), distribution (transparently to the JMS client, it can run as several servers, thus allowing load balancing), and the choice of TCP or SOAP as communication protocol for transmitting messages.

The JMS service is in charge of launching (or establishing connection to) the integrated JMS server, which may or may not run in the same JVM as JOnAS. It also provides connection pooling and thread pooling (for Message-driven Beans). 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.

This service is implemented in the org.objectweb.jonas.jms package.

Note that the same function of JMS implementation integration should now be achieved through a Resource Adapter, to be deployed by the J2EE CA Resource Service (see below). Such a Resource Adapter (J2EE CA 1.5) is provided for JORAM. The Messaging service will become deprecated.

### J2EE CA Resource Service

The J2EE Connector Architecture (J2EE CA) 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, which connects 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 (this can also be a specific Java interface). The RA also provides standard interfaces for plugging into the application server, allowing them to 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 are managed by the application server through the RA (system contract).

The JOnAS Resource service is in charge of deploying J2EE CA-compliant Resource Adapters (connectors), packaged as RAR files, on the JOnAS server (such connectors will be loaded in the Application classloader). RAR files can also be included in EAR files, in which case the connector will be loaded by classloader of the EAR. Once Resource Adapters are deployed, a connection factory instance is available in the JNDI namespace to be looked up by application components.

The Resource Service is implemented in the org.objectweb.jonas.resource package.

A J2EE CA 1.5 Resource Adapter for JDBC is available with JOnAS. It can replace the current JOnAS database service for plugging JDBC drivers and managing connection pools. It also provides JDBC PreparedStatement pooling.

A J2EE CA 1.5 Resource Adapter for JMS is available with JOnAS. It can replace the current JOnAS Messaging service for plugging JORAM.

### Security Service

This service implements the authorization mechanisms for accessing J2EE components, as specified in the J2EE specification.

In JOnAS, the mapping between roles and user identification is done in the user identification repository. This user identification repository can be stored either in files, in a JNDI repository (such as LDAP), or in a relational database. This is achieved through a JOnAS implementation of the Realm for each Web container and through the JAAS login modules for Java clients. These Realms use authentication resources provided by JOnAS, which rely either on files, LDAP or JDBC. These realms are in charge of propagating the security context to the EJB container during EJB calls. JAAS login modules are provided for user authentication of Web Container and Java clients. Certificate-based authentication is also available, with CRLLoginModule login module for certificate revocation.

JOnAS also implements the Java Authorization Contract for Containers (JACC 1.0) specification, allowing authorizations to be managed as java security permissions, and providing the ability to plug any security policy provider.

More details about security handling within JOnAS is provided within the Configuring Security section of the JOnAS Configuration Guide.

There are 3 major packages for implementing the security in JOnAS.

1. The first package is org.objectweb.security which is composed of two important classes. A SecurityContext class which contains Principal names, J2EE roles, etc. and the SecurityCurrent which manages the current SecurityContext of each J2EE component. SecurityContext object is associated to a ThreadLocal object. There is an exception for the client container: In this case, the SecurityContext is available for all the JVM and not only for one thread. This allows to have multi-thread applications like swing/awt applications to have always a SecurityContext object.
2. The second package is org.objectweb.jonas.security.
   This package contains the implementation of the security service, the JAAS login modules (and the JAAS callbacks) provided by JOnAS. The classes used to interact with external authentication like Datasource/LDAP/Files are present in the realm subpackage. It contains also RMI interceptors for JOnAS protocols like rmi/jrmp, rmi/iiop. For IIOP protocol, this package contains CSIv2 interceptors to allow security propagation over iiop which is required for J2EE 1.4. (org.objectweb.jonas.security.iiop).
   To be compliant with J2EE 1.4, JOnAS setup the JACC provider with classes which are in the package org.objectweb.jonas.security.jacc. Note that this package doesn't contains the JACC provider, but only the classes to configure the JACC provider which is set by JOnAS administrator. The last subpackage and not the least is the subpackage implementing the specific Realm for Tomcat or Jetty by relying on existing JOnAS classes. It consists in simple wrapper classes. These classes are in package `org.objectweb.jonas.security.realm.web.xxx` where xxx is catalina50, catalina55, jetty50, etc.
3. The third package is the org.objectweb.jonas_lib.security package.
   This package contains the JACC provider which is used by default. Users can use their own JACC provider by setting properties at the JVM startup. The classes in this package implement/extend classes defined by the JSR 115

### Management Service

The Management service is needed to administrate a JOnAS server from the JOnAS 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 such as services, containers, the server itself. These MBeans implements the management model as specified in the J2EE Management Specification. The Management service runs a JMX server , and is implemented in the org.objectweb.jonas.jmx package. The MBeans of the JOnAS server are registered within this JMX server. The JOnAS administration console is a Struts-based Web application (servlet/JSP) that accesses the JMX server to present the managed features within the administration console. Thus, through a simple Web browser, it is possible to manage one or several JOnAS application servers. The administration console provides a means for configuring all JOnAS services (and making the configuration persistent), for deploying any type of application (EJB-JAR, WAR, EAR) and any type of resource (DataSources, JMS and Mail connection factories, J2EE CA connectors), all without the need to stop or restart the server. The administration console displays information for monitoring the servers and applications, such as used memory, used threads, number of EJB instances, which component currently uses which resources, etc.. When Tomcat is used as Web Container, the Tomcat Management is integrated within the JOnAS console. A Management EJB (MEJB) is also delivered, providing access to the management features, as specified in the J2EE Management Specification.

### Discovery Service

The discovery service is used to support domain management. A JOnAS management domain is composed of a set of JOnAS servers that are running under the same management authority and are identified by a domain name. The servers in a domain may be administred by a management application running on one server in the domain; this is the master server. The managed servers are slaves. The discovery service is based on a mutlicast communication infrastructure allowing message broadcasting in order to publish the connector-server addresses and state changes of the servers in the domain. The master servers listen to these discovery messages. Moreover, they are able to broadcast messages asking the servers in the domain to identify themselves

### Mail Service

A J2EE application component can send e-mail messages using JavaMailTM. The Mail service of the JOnAS application server provides the necessary resources to such application components. The Mail service creates mail factories and registers these resources in the JNDI namespace in the same way that the database service or the JMS service creates Datasources or ConnectionFactories and registers these objects in the JNDI namespace. There are two types of mail factories: javax.mail.Session and javax.mail.internet.MimePartDataSource.

The Mail service is implemented in the org.objectweb.jonas.mail package.

### WebServices Service

This service is implemented on top of AXIS and is used for the deployment of Web Services. Only a very small part of the deployment work is done during the installation time: most of the work is done offline with a tool like GenIC, WsGen.

#### Offline ws processing (WsGen)

WsGen is the offline tool that is responsible of all generation operations for a given archive. It can process EjbJar, WebApp, AppClient and Ear. It will unpack the input archive if needed (ear/war case), read the deployment descriptor of the given component and will generate artifact accordingly. 3 types of artifacts can be generated:

- axis specific deployment descriptor (*.wsdd) for client and server side
- java classes representing client WS Stubs and some Helper classes for complex types
- new archives: a configured webapp for each EjbJar with WS, and an Ear that wraps EjbJar + generated WebApp

WsGen will build server side artifacts if a webservices.xml descriptor is found in the archive (can be an EjbJar or a WebApp):

- If the processed archive is an EjbJar, a WebApp will be generated and its web.xml customized for Axis, a Wrapping Ear will be generated too (only if the EjbJar is not part of an application yet)
- a server side axis deployment descriptor is generated accordingly to the WSDL, Mapping file and Service Endpoint Interface

Client side artifacts are generated only if WsGen find some service-ref elements in web.xml, ejb-jar.xml or application-client.xml:

- Service implementation + Stub(s) implementation of the SEI(s) are generated from WSDL + mapping file (we use EWS: a specialized WSDL2Java tool that looks inside jaxrpc mapping file)
- client side axis deployment descriptor is generated for JAX-RPC Handler setup and operations descriptions
- for each serialized bean, an Helper class is built to help during ser/deser process

#### Runtime processing

- Webservice service

This JOnAS service is used to set some Axis property at JOnAS startup and is in charge of some webservice specific deployment operations:

- Endpoint URL creation from hostname, HTTP port and webapp configuration
- WSDL Publication with WSDLHandler: J2EE server are required to publish all WSDL definitions of exposed components, from now, JOnAS can publish the WSDLs in the file system or inside a registry (jUDDI, ...). Notice that Registry publication is a minimalist implementation

- component context update

Each component that want to be client of a webservices has to declare a dependency on that webservice using service-ref (like ejb-ref, ...). At deploy time, each container (web, ejb and client) is responsible to create and fill the Context of each deployed component. Each container has a createCompponentContext() method (web, ejb, client) that have been updated to handle service-ref.
Each service-ref is bound in the Component Context as a Reference configured to permit the javax.xml.rpc.Service creation (using an ObjectFactory) when the client performs the lookup.

- WSDL publication by URL

Besides WSDL publication done by the ws service with WSDLHandler, Axis give us an elegant way to obtain the service WSDL with just a simple URL: you just have to append to the endpoint URL the String ?WSDL to retrieve the desired WSDL.
In JOnAS, this idea has been reused and enhanced for allowing handling of import/include of WSDL definition to other XML Document (WSDL or Schema) and this, recursivly ! Append ?JWSDL (Notice the J !) to your endpoint URL and you'll see the WSDL packaged inside your webapp (no runtime generation) with some updates (URL endpoints + imports/includes).

2 main packages:

1. org.objectweb.jonas_ws: contains all XML descriptors handling code (deployment/xml deployment/api + deployment/lib) and WsGen code
2. org.objectweb.jonas.ws: contains runtime classes WSService + Axis glue for JOnAS

Webservices related documentation :

- Webservices Service configuration
- Introduction to J2EE WebServices in JOnAS
- Tutorial

## JOnAS Management Architecture

As previously explained, JOnAS Management is based on JMX. Standard MBeans are defined within the JOnAS application server; they expose the management methods of the instrumented JOnAS server objects such as services, containers, the server itself. They are registered within the JMX server embedded within the JOnAS Management Service, and may then be accessed by any JMX client.

Related documentation:

Domain Management in JOnAS (explain the domain management feature of JOnAS, available from JOnAS 4.4 only)

Discovery Service Configuration (description of the discovery service, used for domain support, available from JOnAS 4.4 only)

JSR160 Support in JOnAS (explain the principles to remotely access to the JOnAS MBeans server, e.g. for remote management, used by the domain management features)

Administration Guide (JonasAdmin console principles, MEJB description)

Working with Management Beans (key and short document to understand JOnAS management principles)

JOnAS and JMX, registering and manipulating MBeans (contributed document explaining how to register applicative MBeans within the JOnAS JMX server)

## Clustering and Performance

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

JOnAS provides Load Balancing, HA, and Failover at the WEB container level using the Apache Tomcat mod_jk plugin and an HTTP in memory session-replication mechanism provided with Tomcat. The plugin dispatches HTTP requests from the Apache web server to Tomcat instances running as JOnAS web containers. Server fluctuations are automatically taken into account. This plugin supports round-robin and weighted round-robin load-balancing algorithms, with a sticky session option.

Load balancing and HA are provided at the EJB container level in JOnAS. Operations invoked on EJB Home interfaces (EJB creation and retrieval) are dispatched on the nodes of the cluster. The mechanism is based on a "clustered-aware" replicated JNDI registry using a Clustered remote Method Invocation protocol (CMI). The stubs contain the knowledge of the cluster and implement the load-balancing policy, which may be random, round-robin and weighted round-robin. Failover at the EJB level will be provided by implementing a stateful session bean state replication mechanism.

The JOnAS clustering architecture is illustrated in the following figure.

JOnAS provides documentation for configuring such an architecture, the JOnAS Clustering Document.

The use of the C-JDBC ObjectWeb project offers load balancing and high availability at the database level. The use of C-JDBC is transparent to the application (in our case to JOnAS), since it is viewed as a standard JDBC driver. However, this "driver" implements the cluster mechanisms (reads are load-balanced and writes are broadcasted). The database is distributed and replicated among several nodes, and C-JDBC load balances the queries between these nodes. An evaluation of C-JDBC using the TPC-W benchmark on a 6-node cluster has shown performance scaling linearly up to six nodes.

In addition to clustering solutions, JOnAS provides many mechanisms, intrinsic to the JOnAS server, for being highly scalable and efficient. This includes the following:

- A pool of stateless session bean instances
- A pool of entity bean instances, configurable for each entity bean within its deployment descriptor
- Activation/passivation of entity beans, passivation can be controlled through the management console
- Pools of connections, for JDBC, JMS, J2EE CA connectors. For database connection pooling, many tuning capabilities are provided: see the section JDBC connection pool configuration of the Configuring JDBC DataSource section of the JOnAS configuration guide.
- A pool of threads for message-driven beans
- Session bean timeout can be specified at deployment
- A "shared" flag in the specific deployment descriptor of an entity bean indicates whether the persistent representation of this entity bean is shared by several servers/applications, or whether it is dedicated to the JOnAS server where it is loaded. In the latter case, the optimization performed by JOnAS consists of not reloading the corresponding data between transactions.
- The usual EJB 1.1 "isModified" (or "Dirty") mechanism is available for avoiding storage of unmodified data.
- An optimization called "Data Prefetching" provides JDBC resultsets re-use by the EJB container (this optimization reduces the number of SQL statements executed by the EJB container)
- Adapting the entity bean lock policy to the application, the following policies are available: container-serialized, container-read-committed, container-read-uncommitted, database, read-only.

Optimizations related to entity beans are described in the Tuning Container for Entity Bean Optimizations section of the JOnAS documentation. More details about available CMP tuning features are provided below.

### CMP Tuning Features

JOnAS provides many CMP tuning features, which may be specified through server specific deployment elements, at the entity bean level (so that one policy per component may be defined).

1) Lock Policy (Concurrent Access)

The <lock-policy> elements may have the following value:

1. Container-serialized (default): The container ensures the transaction serialization. This policy is suitable for most entity beans, particularly if the bean is accessed only from this container (shared = false).
2. Container-read-committed: This policy is similar to container-serialized, except that accesses outside transaction do not interfere with transactional accesses. This can avoid deadlocks in certain cases, when accessing a bean concurrently with and without a transactional context. The only drawback of this policy is that it consumes more memory (2 instances instead of 1).
3. Container-read-uncommitted: all methods share the same instance (like container-serialized), but there is no synchronization. For example, this policy is of interest for read-only entity beans, or if the bean instances are very rarely modified. It will fail if 2 or more threads try to modify the same instance concurrently.
4. Database: Let the database deal with transaction isolation. With this policy, you can choose the transaction isolation in your database. This may be of interest for applications that heavily use transactional read-only operations, or when the flag shared is needed. It does not work with all databases and is not memory efficient.
5. Read-only: The bean is never written to database. If the bean is shared, the bean state is read from database regularly.

Note: If you deploy CMP1 beans, you should use the default policy only (container-serialized), unless your beans are "read-only". In this latter case, you can use container-read-uncommitted.

2) Database dedicated access

JOnAS can do some data access optimization if the persistent state of an entity bean is accessed only by the JOnAS server. The optimization consists in not re-reading the bean state before starting a new transaction if the bean is already in memory. Indeed, as nobody else can modify the state of the bean on the persistent support, it is not necessary to re-read it. This may be specified to JOnAS by using the <shared> element and setting it to false. If the <shared> element is set to true, it means that the bean persistent state can be accessed outside the JOnAS Server, and then the optimization cannot be done. The default value is false if lock-policy is container-serialized, and true in the other cases.

3) Data pre-fetching

The <prefetch> element is a CMP2-specific option. The default is false. This can be set to true if it is desirable to have a cache managed after finder methods execution, in order to optimize further accesses, inside the same transaction.

Important notes:

- The prefetch is not be used for methods that have no transactional context.
- It is impossible to set the prefetch option if the lock policy is container-read-uncommitted.

4) Instances pooling / caching

Four elements allow specifying entity beans instances management.

- The first one, <max-cache-size>, is an integer value that represents the maximum number of instances in memory. The purpose of this value is to keep JOnAS scalable. The default value is "no limit". To save memory, this value should be set very low if you know that instances will not be reused.

- The second one, <min-pool-size>, is an integer value representing the number of instances that will be created in the pool when the bean is loaded. This will improve bean instance creation time, at least for the first instances. The default value is 0.

- The third one, <passivation-timeout>, allows tuning the entity bean instances passivation activity (saving memory by sending instances on the persistent support), in accordance with the previous persistence tuning elements. Entity bean instances are passivated at the end of each transaction and reactivated at the beginning of the next transaction, when the shared flag has been set to true. In case shared has been set to false, a passivation will occur only if max-cache-size has been reached. In the event that these instances are accessed outside a transaction, their state is kept in memory to improve performance. However, a passivation will occur in three situations:

1. When the bean is unloaded from the server, at least when the server is stopped.
2. When a transaction is started on this instance.
3. After a configurable timeout. If the bean is always accessed with no transaction, it may be prudent to periodically store the bean state on disk.

- The fourth one is <inactivity-timeout>: Bean passivation sends to persistent storage the state of the bean and removes from memory only the bean instance objects holding this state. All container objects handling bean access (remote object, interceptors ...) are kept in memory so that future access will work, only requiring a reload operation (getting the state). You may want to save more memory and completely remove the bean instance from memory, this may be achieved through the <inactivity-timeout> element. This element is used to save memory when a bean has not been used for a long time. After the time specified, in seconds, and if the bean has not been used meanwhile, all its container objects are removed from the server. If a client has kept a reference on a remote object, it will get an exception if it tries to use it.

5) Db Connections pooling

For database access, JOnAS provides a sophisticated connection pools management. See the Configuring JDBC Datasource section of the JOnAS Configuration Guide (available soon for the JDBC connector). Connection pooling saves the high cost of physical connection creation by maintaining a pool of such connections. Connection pools may be tuned using the following properties:

- Conmaxage: number of minutes a connection can be kept in the pool. After this time, the connection will be closed, if minconpool limit has not been reached.
- Maxopentime: Maximum time (in mn) a connection can be left busy. If the caller has not issued a close() during this time, the connection will be closed automatically.
- Minconpool: Minimum number of connections in the pool. Setting a positive value here ensures that the pool size will not go below this limit during the datasource lifetime.
- Maxconpool: Maximum number of connections in the pool. Limiting the max pool size avoids errors from the database.
- Samplingperiod: Sampling period for JDBC monitoring. nb of seconds between 2 measures.
- Maxwaittime: Maximum time (in seconds) to wait for a connection in case of shortage. Valid only if maxconpool has been set.
- Maxwaiters: Maximum of concurrent waiters for a JDBC Connection. Valid only if maxconpool has been set.

6) PreparedStatement pooling

The JOnAS JDBC connector manages pools of JDBC PreparedStatements.

##

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