Sun ONE logo     Previous      Contents      Index      Next     
Sun ONE Application Server 7, Update 1 Administrator's Guide



Configuring J2EE Containers

Sun ONE Application Server provides various J2EE containers in compliance with the J2EE 1.3 specification. Containers provide runtime support for J2EE application components such as Enterprise Java Beans (EJBs) and Message Driven Beans (MDBs). MDBs and EJBs never interact directly with other J2EE application components. They use the protocols and methods of the EJB container for interacting with each other and with platform services, such as the Java Transaction Service. The container is interposed between application components and J2EE services. This allows the container to transparently inject the services defined by the components' deployment descriptors, such as declarative transaction management, security checks, resource pooling, and state management.

Sun One Application Server incorporates the Web Container and the EJB Container.

This module includes the following topics:

About the Web Container

The Web Container is a J2EE container that hosts web applications. The web container extends the web server functionality by providing developers the environment to run servlets and Java Server Pages (JSPs). Servlets provide a component-based, platform-independent method for building web-based applications, without the performance limitations of CGI (Common Gateway Interface) programs. The JSP technology is an extension of the servlet technology, created to support authoring of HTML and XML pages. Servlets or JSPs contained in a web container are capable of invoking bean methods in an Enterprise Java Beans (EJB) container. Bean methods are invoked either through local invocation or remote invocation using an Object Request Broker (ORB).

The web container also provides web applications access to local EJBs that are located using JNDI (Java Naming Directory Interface).

The figure "Web Container within the Sun ONE Application Server Architecture" explains the role and the location of the web container, in the Sun ONE Application Server architecture:

  
Figure shows how the web container is integrated within the Sun ONE Application Server Architecture.
Web Container within the Sun ONE Application Server Architecture

This section covers the following topics:

Understanding the Web Container's Role

The primary role of the web container is to provide a run-time environment for web applications and provide services (database access, security, multi-threading, and so on) to web applications hosted in the container. A web application is a collection of servlets, HTML pages, classes, and other resources that make up a complete application on Sun ONE Application Server.

The following are the elements of a web application:

  • Servlets
  • JSP pages
  • Utility classes
  • Static documents (html, images, sound files, etc.)
  • Client side Java applets, beans, and classes
  • Descriptive meta information which ties all of the above elements together.

Web applications may be deployed in the web containers running in a Sun ONE Application Server.

For more information on how to configure and use the web server plugin with Sun ONE Application Server, see "Configuring the Web Server Plugin".

Web Application Configuration

You can also configure web containers to deploy web applications within virtual servers. The web container can be configured to contain more than one virtual server. Each virtual server can be configured to host any number of web applications. Web applications are scoped within the context of a virtual server. For more information about virtual servers, see "Using Virtual Servers."

The following topics are covered in this section:

Virtual Server Attributes

You can specify values for certain configurable attributes for a virtual server. A virtual server can have more than one web application associated with it. A user needs to sign on to a web application.

If the attribute for single sign on, sso-enabled, is set to the default value true in the server.xml file, a user can sign on to any one of the web applications associated with the specific virtual server. The user's identity is then recognized by all other web applications running on the same virtual server. If the value for sso-enabled is set to false, then single sign on is disabled for all web applications in this virtual server.

The sso-enabled attribute is dynamically configurable and does not require a server restart to enable effect.

More information about single-sign on is provided in the section "Single Sign-on Facility".

Web-module Attributes

The Sun ONE Application Server-specific deployment descriptors are specified in a file called sun-web.xml, which can be found in the WEB-INF directory of a given web application.

Usually, there is a sun-web.xml file configured for each web application. However, the web container does not require that every web application have an sun-web.xml file. In the absence of the sun-web.xml file, the web container assumes default values for all Sun ONE Application Server-specific attributes.

The context-root Attribute

This attribute defines the context root at which the web application is installed. If this attribute is an empty string then this web application is designated to be the default web application for the virtual server. The default web application for a virtual server responds to all requests that cannot be resolved to other web applications deployed to the virtual server. Every virtual server has a default web application.

For the default web application, the value of this field should be an empty string "".

The location Attribute

The input for this attribute should be a valid directory path, which indicates the location of the default web application. During the installation process, the location of the default web application is set to the modules/default-web-app/ directory.

The location attribute is required and can be either a fully qualified or relative path to the directory in which the contents of the WAR (Web ARchive) file have been extracted. If the path specified is relative, then it needs to be relative to the application root directory defined at the virtual server level.

For example:

location="applications/<ear name>/<war-module name>/"

location="modules/<war-module name>"

location="/u/myapps/<war-module name>"

location="/u/myapps/<ear-name>/<war-module name>"

The enabled Attribute

The default value for this attribute is true, indicating that a web application is enabled to service requests. By setting the value of the enabled attribute to false, you can temporarily disable the web application from servicing requests. However, the contents of the web application (as stored in your hard-disk) are not removed.

Web Application Deployment

The web container deploys web applications from a Web ARchive (WAR) file or from a directory containing an exploded view (WEB-INF/lib,WEB-INF/classes, and so on) of the WAR file. You do not need to restart the server to deploy an application.

The web container deploys a "default" web application on each virtual server. The default location (directory) is in the modules/default-web-app/ subdirectory of the app root directory for the virtual server. This default web application responds to all requests that cannot be resolved to other web applications deployed to the virtual server. This web application consists of an invoker servlet to handle requests to /servlet/* and a JSP servlet to serve JSP pages. The default web application can access EJBs as long the user denotes the EJB references in the web.xml and sun-web.xml files.

The default web application is defined in the server.xml of a virtual server looks as follows:

<web-module context-root="" location="modules/default-web-app/">

Dynamic Re-deployment and Hot Deployment

Dynamic redeployment is the ability to redeploy an existing application without a server restart. Dynamic redeployment happens when an application's configuration (contents of its xml files) and certain classes change. Dynamic re-deployment results in behavior identical to that of dynamic reloading the entire application's classes. In addition, dynamic re-deployment involves creating new application contexts (web and ejb) and getting rid of the old application contexts. Thus, dynamic re-deployment results in a brand new instance of the application (except for existing session data). This feature is also supported in development mode only and can result in exceptions similar to those for dynamic reloading. Also, configuration changes that require server restarts do not take effect until this restart happens. Dynamic reloading is activated only for applications and unshared standalone modules whose central configuration specifies it.

When a web application is reloaded, all existing session information is automatically saved and restored, regardless of whether a persistence mechanism was configured for the session manager.

Hot deployment is the ability to deploy an application at server runtime, without requiring a server restart. This feature uses the same infrastructure as is used for dynamic redeployment. However, since there is no state left over from a previous incarnation, this feature is supported at production time.

Single Sign-on Facility

As long as the user accesses only unprotected resources in any of the web applications on a specific virtual server, the user is not challenged to authenticate himself.

When the user accesses a protected resource in any web application associated with a specific virtual server, the user will be challenged to authenticate himself using the login method defined for the web application currently being accessed.

Once authenticated, the roles associated with the user will be utilized for access-control decisions across all of the associated web applications. The user is then not required to authenticate himself individually to each web application.

When a the user logs out of a web application the user's sessions in all web applications will be invalidated. Any subsequent attempt to access a protected resource in any application will require the user to authenticate himself again.

The single sign-on feature utilizes HTTP cookies to transmit a token that associates each request with the saved user identity, so it can only be utilized in client environments that support cookies.

Logging the Web Container

You can control the default logging behavior of the web container and any applications that are hosted in a virtual server, by setting different log levels. Note that the logging behavior doesn't affect the application's own logging.

Specifying a log level controls the type of messages that will be logged. For example, if you specify that only messages that bear the log level FATAL be logged, then the messages "higher" log level than this value will be silently ignored. Only messages logged with an explicit log level are compared to this value.

Messages logged with no explicit log level are logged unconditionally. The default behavior is to log all warning, error and fatal messages.

To set log levels for the web container, perform the following tasks:

  1. In the left pane of the Administration interface, expand the Sun ONE Application Server instance tree to find the web container configuration you want to modify.
  2. Expand the Containers tab, and select Web Container from the list of J2EE containers that are displayed. You will see the page displayed in "Logging the Web Container," in the right pane of the Administration interface.

   Logging the Web Container
Figure shows the Web Container log level setting.

  1. Select the log level you want, from the Log Level drop-down list. For a listing of all the log levels and their definitions, see "Using Logging."
  2. Click save to save your settings

To create additional properties for the web container, click the Properties button.

About the EJB Container

Enterprise Java Bean container is a runtime environment that controls the enterprise beans and provides them with important system level services. An EJB is a component that executes within an EJB container, which in turn executes within an EJB server. The following system level services are provided to the beans:

  • Transaction Management
  • Security
  • Life cycle Management
  • Remote connectivity
  • Database connection pooling
  • Naming Service

Enterprise beans are server components written in Java that contain business logic. The EJB Container provides the remote access to the bean. EJBs always work within the context of a container, which serves as a link between the EJBs and the server that hosts them. The EJB container enables distributed application building using your own components and components from other suppliers.

Through the EJB container, Sun ONE Application Server provides high-level transaction, state management, multi-threading, and resource pooling wrappers, thereby shielding you from having to know the low-level API details. This container provides all standard container services denoted by the 2.0 EJB Specification, and also provides additional services specific to the Sun ONE Application Server.

Passivation and activation processes are used by the container to manage bean activity to ensure scalability.

This section covers the following topics:

Understanding the EJB Container's Role

The EJB container provides the following standard services:

  • Passivation
  • The process of transferring an EJB from memory to secondary storage. Passivation allows a bean's resources to be released without destroying the bean. In this way, a bean is made to be persistent, and can be recalled without the overhead of instantiation.

  • Activation
  • The process of transferring an EJB from secondary storage to memory. The container contract establishes the relationship between an EJB and its container, and is completely transparent to a client. This relationship includes:

    • Life cycle
    • For session beans, this includes the javax.ejb.SessionBean and javax.ejb.SessionSynchronization interface implementations. For entity beans, this includes the javax.ejb.EntityBean interface implementation. For message-driven beans, this includes the javax.ejb.MessageDriven interface implementation.

    • Session context
    • A container implements the javax.ejb.SessionContext interface to pass services and information to a session bean instance when the bean instance is created.

    • Entity context
    • A container implements the javax.ejb.EntityContext interface to pass services and information to an entity bean when the bean instance is created.

    • Message context
    • A container implements the javax.ejb.MDBContext interface to pass services and information to a message-driven bean when the bean instance is created.

    • Environment
    • A container implements java.util.Properties and makes these properties available to its EJBs.

    • Service information
    • A container makes its services available to its EJBs.

The Sun ONE Application Server services include remote access, naming, security, concurrency, transaction control, and database access.

The EJB container is responsible for:

  • Creating the implementation object (EJBObject) that allows remote connectivity.
  • Creating the home implementation object that allows for creation of the EJBObject.
  • Binding the home implementation object to the naming service so that clients can look up the home object.
  • Ensuring that only authorized clients invoke the bean methods (through the EJBObject).
  • Ensuring that business methods are invoked in the appropriate transactions.
  • Managing the life cycle of the beans. Managing the life cycle of beans include:
    • Pooling the beans
    • Calling the appropriate callback methods (such as ejbActivate/ejbPassivate)
    • Managing a pool of database connections so that the applications use and reuse the connections more efficiently.

Actual implementation details are part of the container, based on a standard prescribed interface between a container and its EJBs. You are not required to know or to handle platform-specific implementation details. Instead, you can create generic, task-focused EJBs to be used with any vendor's products that support the EJB standard.

It is useful to understand the types of EJBs that are used by Sun ONE Application Server.

Types of Enterprise Java Beans

An EJB is an object that represents one of the following:

  • A session with a particular client, which automatically maintains state across multiple client-invoked methods.
  • A persistent entity object, possibly shared among multiple clients.
  • A stateless service, such as message handling.

Entity beans are primarily used to handle data access using the Java Database Connectivity (JDBC) API, while session beans provide transient application objects and perform discrete business tasks. There are three kinds of EJBs, as discussed in the following topics:

About Session Beans

A session bean implements business rules or logic for a particular client request.

Session beans are intended to represent transient objects and processes, such as a single database record, a document copy for editing, or specialized business objects for individual clients. That is, a session bean is a private resource used only by the client that creates it. Because these objects are only available to a single client, session beans can maintain client-specific session information, called the conversational state.

For example, you might create an EJB to simulate an electronic shopping cart. Each time a user logs in to an application, the application creates the shopping cart session bean to hold purchases for that user. After the user logs out or finishes shopping, the session bean is released.

Session beans have the following characteristics:

  • Session beans execute in relation to a single client.
  • Session beans are relatively short lived.
  • Session beans do not always survive a server crash.
  • Session beans are removed if the EJB container crashes.
  • Session beans also handle transaction management according to property settings. This is optional.
  • Session beans update shared data in an underlying database. This is optional.
  • A session bean can be either stateless or stateful.

Stateless Session Beans. A stateless session bean encapsulates a temporary piece of business logic needed by a specific client for a limited time span. Stateless session beans do not maintain the conversational state.

Stateful Session Beans. A stateful session bean is transient, but maintains a conversational state to preserve information about its contents and values between client calls. The conversational state enables the bean's container to maintain information about the session bean state and to recreate the state at a later point in program execution when needed.

About Entity Beans

Entity beans commonly represent persistent data which is maintained directly in a database or accessed through an Enterprise Information System (EIS) application as an object. The server that hosts EJBs and an EJB container provides a scalable runtime environment for concurrently active entity EJBs.

A simple example of an entity bean is one defined to represent a single row in a database table, where each bean instance represents a specific row. A more complex example is an entity bean designed to represent complicated views of joined tables in a database, where, for example, each bean instance represents the contents of a single shopping cart.

Entity beans have the following characteristics:

  • Entity beans provide an object view of data in the EIS resource, usually a database.
  • Entity beans can be accessed by all users.
  • Entity beans transparently survive server crashes.
  • Entity beans use transactions that are either container-managed or bean-managed.

Entity beans represent persistent data, either as container-managed persistence or bean-managed persistence. An entity bean's persistence can either be managed by the bean or the container.

Bean-managed persistence. When an entity bean manages its own persistence. The bean developer implements persistence code (such as JDBC calls) directly in the EJB class methods. The possible downside is portability loss if a proprietary interface is used, and the risk in associating the bean to a specific database.

Container-managed persistence. When entity bean persistence is managed by the container. Because the container transparently manages the persistence state, you do not need to implement any data access code in the bean methods. Not only is this method simpler to implement, but it makes the bean fully portable without any ties to a specific database.

An entity bean that uses container-managed persistence is essentially an auto-generated (by the container) version of an entity bean that uses bean-managed persistence.

For more information on building and using Entity beans, see the Sun ONE Application Server Developer's Guide to Enterprise JavaBeans Technology.

About Message-driven Beans

A message-driven bean is an EJB that allows J2EE applications to process messages asynchronously. A message-driven bean is driven by the arrival of Java Message Service messages.

From its creation until destruction, a message-driven bean instance lives in a message-driven bean container. The container provides security, transaction, concurrent processing of messages, life cycle management of the message-driven bean instances, and other services for the message-driven bean. The server that hosts EJBs and an EJB container provides a scalable runtime environment for concurrently active message-driven beans.

The Java Message Service API in the J2EE 1.3 platform specifies the following:

  • Application clients, EJB components, and web components can send or synchronously receive a Java Message Service message. In addition, application clients can use Java Message Service messages asynchronously.
  • The message-driven beans enable the asynchronous consumption of messages. A Java Message Service provider may optionally implement concurrent processing of messages by message-driven beans.

A message-driven bean represents a stateless service; it is essentially an asynchronous message consumer that is completely anonymous and has no client-visible identity. A message-driven bean has neither a home nor a component interface. A client accesses a message-driven bean through Java Message Service by sending messages to the Java Message Service destination (queue or topic) for which the message-driven bean class is the MessageListener.

Only message-driven beans can asynchronously receive messages. A session or entity beans is not permitted to be a Java Message Service MessageListener.

Message-driven beans have the following characteristics:

  • Execute upon receipt of a single client message.
  • Are asynchronously invoked.
  • Are relatively short lived.
  • Do not directly represent shared data in the database, but may access and update this data.
  • Are removed if the EJB server crashes.
  • Are stateless.
  • Optionally, are transaction-aware.

Configuring the EJB Container

You can configure the log level for the EJB container, and also enable monitoring. The EJB container handles both EJBs and MDBs. Using the Administration interface, you can configure settings for the EJBs and the MDBs that the container manages. This section covers the following topics:

Performing General Configuration

You configure the following aspects of the EJB container:

  • Logging
  • Monitoring
  • Transaction Attributes

To set log levels for the EJB container, to enable monitoring and to set transaction attributes, perform the following tasks:

  1. In the left pane of the Administration interface, open the Sun ONE Application Server instance tree, for the EJB container configuration you want to modify.
  2. Expand the Containers tab, and select EJB Container from the list of J2EE containers that are displayed. You will see the window as shown in "EJB Container - General Configuration" in the right pane of the Administration interface.

   EJB Container - General Configuration
Figure shows how to set the log level from the EJB Container.

  1. Mark the checkbox against Monitoring Enabled, to enable monitoring of the EJB Container. You've now enabled monitoring for the EJB container of this specific instance of Sun ONE Application Server. For a list of the monitorable aspects of the EJB container, see the table "Monitoring Statistics for EJB Container."
  2. Select the log level you want, from the Log Level drop-down list. For a listing of all the log levels and their definitions, "Using Logging." Specifying a log level controls the type of messages that will be logged. For example, if you specify that only messages that bear the log level FATAL be logged, then the messages "higher" log level than this value will be silently ignored. Only messages logged with an explicit log level are compared to this value.
  3. Messages logged with no explicit log level are logged unconditionally. The default behavior is to log all warning, error and fatal messages.

  4. From the Commit Option drop down list, select the Commit Option you want to use for the EJB Container.
  5. A transaction can end in two ways: with a commit or a rollback. When a transaction commits, the data modifications made by its statements are saved. When you design an enterprise bean, you determine if the commit is a container-managed or a bean-managed transaction. The options in the UI are therefore, B for bean-managed commit, and C for container-managed commit.

  6. Click the Properties button to create new properties for the EJB container.
  7. Click OK to save your settings.

The following table displays the attributes of the EJB container that can be monitored:

   Monitoring Statistics for EJB Container

Statistic Name

Data Type & units

Range of values

Comments

minBeansInPool

 

Integer

 

0-MAXINT

 

The preferred minimum number of beans in the pool (applies to stateless session beans

 

initialBeansInPool

 

Integer

 

0-MAXINT

 

The initial number of beans in the pool (applies to stateless session beans).

 

maxBeansInPool

 

Integer

 

0-MAXINT

 

Maximum number of beans in the pool. (applies to stateless session beans).

 

beanIdleTimeoutInSeconds

 

Integer

 

0-MAXLONG

 

Idle timeout in seconds beyond which the bean will be destroyed.

 

numBeansCreated

 

Integer

 

0-MAXINT

 

Number of beans so far created.

 

numBeansDestroyed

 

Integer

 

0-MAXINT

 

Number of beans so far destroyed.

 

numThreadsWaitaing

 

Integer

 

0-MAXINT

 

Number of threads waiting for free beans

 

numBeansInPool

 

Integer

 

0-MAXINT

 

Number of beans available in pool. (If this is greater than zero, then numThreadsWaitaing must be 0)

 

maxBeansInCache

 

Integer

 

0-MAXINT

 

The maximum number of beans in the cache (applies to entity and stateful beans).

 

minBeansInCache

 

Integer

 

0-MAXINT

 

The preferred minimum number of beans in the cache (applies to entity and stateful beans).

 

cacheFaultsPercentage

 

Double

 

 

Number of cache misses that resulted in activating from backup store.

 

Configuring EJB Settings

Using the Administration interface, you can configure the default pool and bean cache settings for the EJBs managed by the EJB container, as discussed in the following topics:

To Configure EJB Pool Settings

To configure EJB pool settings, perform the following tasks:

  1. In the left pane of the Administration interface, open the Sun ONE Application Server instance tree, whose EJB settings you want to modify.
  2. Expand the Containers tab, and select EJB Container from the list of J2EE containers that are displayed. You will see the window as shown in "Configuring EJB Pool Settings" in the right pane of the Administration interface.

   Configuring EJB Pool Settings
Figure shows how to set the log level from the EJB Container.

  1. In the Steady Pool Size field, specify the minimum number of beans in the pool. This applies to stateless session beans.
  2. In the Max Pool Size drop down list, specify the maximum number of beans you want in the pool, at any given point in time. This setting applies to stateless session beans
  3. In the Pool Resize Quantity field, specify the number of beans to be removed from the pool, if the beans are idle for more than the time specified in the idle-timeout-in-seconds tag.
  4. In the Idle Timeout (secs) field, specify the period, in seconds, that a bean can remain idle. When the idle-timeout period elapses and the bean is still idle, it will be destroyed.
  5. Click Save to save your changes.

To Configure EJB Cache Settings

To configure EJB cache settings, perform the following tasks:

  1. In the left pane of the Administration interface, open the Sun ONE Application Server instance tree, whose EJB settings you want to modify.
  2. Expand the Containers tab, and select EJB Container from the list of J2EE containers that are displayed. You will see the window as shown in "Configuring EJB Pool Settings" in the right pane of the Administration interface.

   Configuring EJB Cache Settings
Figure shows how to set the log level from the EJB Container.

  1. In the Max Cache Size field, specify the maximum number of beans to be maintained in the cache. The default value for this attribute is as specified in the idle-timeout-in-seconds attribute.
  2. In the Cache Resize Quantity field, specify the number of beans to be selected for destruction, if the number of beans in the pool exceeds the quantity specified in the Max Cache Size attribute.
  3. In the Removal Timeout (secs) field, specify the amount of time that a bean that is idle in the backup store can remain passivated. If a bean is not accessed by a client beyond the value specified in the removal-timeout-in-seconds attribute, then the bean will be removed from the backup store and therefore will not be accessible to the client.
  4. From the Victim Selection Policy drop-down list, select the victim selection algorithm that must be employed to select victim beans to be removed from the pool.
  5. In the Idle Timeout (secs) field, specify the period for which a bean is allowed to be idle in the cache. After this period elapses, the bean is passivated. The period for which the bean remains passivated (in the idle backup store), is controlled by the removal-timeout-in-seconds parameter.
  6. Click Save to save your changes.

Configuring MDB Pool Settings

Using the Administration interface, you can configure the default pool settings for the MDBs managed by the EJB container. To configure default pool settings for MDBs, perform the following tasks:

  1. In the left pane of the Administration interface, open the Sun ONE Application Server instance tree, whose MDB container configuration you want to modify.
  2. Expand the Containers tab, and select EJB Container from the list of J2EE containers that are displayed. You will see the window shown in "Configuring MDB Pool Settings" in the right pane of the Administration interface.

   Configuring MDB Pool Settings
Figure shows default pool settings configuration for the MDBs managed by the EJB container.

  1. Click MDB Settings. In the Steady Pool Size text field, specify the minimum number of beans in the pool. This applies to stateless session beans.
  2. In the Max Pool Size field specify the maximum number of beans you want in the pool, at any given point in time.
  3. In the Pool Resize Quantity field, specify the number of beans to be removed from the pool, if the beans are idle for more than the time specified in the idle-timeout-in-seconds tag.
  4. In the Idle Timeout (secs) field, specify the period, in seconds, that a bean can remain idle. When the idle-timeout period elapses and the bean is still idle, it will be destroyed.
  5. Click Save to save your settings.

Previous      Contents      Index      Next     
Copyright 2003 Sun Microsystems, Inc. All rights reserved.