Implementing Enterprise Java Beans

The sections that follow describe the EJB implementation process, and provide guidance for how to get an EJB up and running in WebLogic Server.

It is assumed that you understand WebLogic Server’s value-added EJB features, have selected a design pattern for your application, and have made key design decisions.

For discussion of design options for EJBs, factors to consider during the design process, and recommended design patterns see Designing Enterprise Java Beans.

Overview of the EJB Development Process

This section is a brief overview of the EJB development process. It describes the key implementation tasks and associated results.

Figure 4-1 illustrates the process of developing an EJB. The steps in the process, and the results of each are described in Table 4-1. Subsequent sections detail each step in the process.

Table 4-1 EJB Development Tasks and Results
Step	Description	Result
Create a Source Directory	Create the directory structure for your source files, deployment descriptors, and files that are generated during the implementation process.	A directory structure on your local drive.
Create EJB Classes and Interfaces	Create the classes that make up your bean. Insert appropriate tags in your source code to enable automatic generation of deployment descriptor elements later in the implementation process.	`.java` file for each class
Compile Java Source	Compile source code.	`.class` file for each class
Generate Deployment Descriptors	Write or generate deployment descriptors that configure the runtime behavior and environment for the bean.	`ejb-jar.xml`, and optionally: `weblogic-ejb-jar.xml`, which contains elements that control WebLogic Server-specific features, and `weblogic-cmp-jar.xml` if the bean is a container-managed persistence entity bean.
Edit Deployment Descriptors	You may need to edit deployment descriptors to ensure they correctly reflect all desired runtime behaviors for your bean. If your source was thoroughly annotated with markup that specifies the optional features the bean uses, and you used EJBGen to generate the deployment descriptors automatically, edits to your deployment descriptor should be minima.	`ejb-jar.xml`, `weblogic-ejb-jar.xml`, which contains elements that control WebLogic Server-specific features, and `weblogic-cmp-jar.xml` if the bean is a container-managed persistence entity bean.
Generate EJB Wrapper Classes, and Stub and Skeleton Files	Generate the container classes used to access the deployment unit, including classes for home and remote interfaces.	Generated classes are added to archive or directory.
Package	Package compiled files, generated files, and deployment descriptors for deployment. If appropriate, you can leave your files unarchived in an exploded directory.	Archive, either a JAR or an EAR
Deploy	Target the archive or application directory to desired Managed Server, or a WebLogic Server cluster, in accordance with selected staging mode.	The deployment settings for the bean are written to `EJBComponent` element in `config.xml`.

Create a Source Directory

BEA recommends a split development directory structure, which segregates source and output files in parallel directory structures. For instructions on how to set up a split directory structure and package your EJB as an enterprise application archive (EAR), see “Overview of the Split Development Directory Environment” in Developing Applications with WebLogic Server.

If you prefer to package and deploy your EJB in a JAR file, create a directory for your class files, and within that directory, a subdirectory named META-INF for deployment descriptor files.

myEJB/

META-INF/

ejb-jar.xml

weblogic-ejb-jar.xml

weblogic-cmp-jar.xml

foo.class

fooHome.class

fooBean.class

Create EJB Classes and Interfaces

The classes required depend on the type of EJB you are developing, as described in Table 2-1.

BEA offers productivity tools for developing class and interface files. The EJBGen command line utility automates the process of creating class and interface files, and also generates deployment descriptor files for the EJB. For more information and instructions for using these tools see EJBGen Reference.

The sections that follow provide tips and guidelines for using WebLogic Server-specific EJB features.

Using WebLogic Server Generic Bean Templates

For each EJB type, WebLogic Server provides a generic class that contains Java callbacks, or listeners, that are required for most EJBs. The generic classes are in the weblogic.ejb package:

GenericEnterpriseBean
GenericEntityBean
GenericMessageDrivenBean
GenericSessionBean

You can implement a generic bean template in a class of your own by importing the generic class into the class you are writing. This example imports the GenericSessionBean class into HelloWorldEJB:

Programming Client Access to EJBs

The following sections provide guidelines for programming client access to an EJB.

Programming Client to Obtain Initial Context

Local clients obtain initial context using the getInitialContext method, similar to the following excerpt.

...
Context ctx = getInitialContexLt("t3://localhost:7001", "user1", "user1Password");
...
static Context getInitialContext(String url, String user, String password) {

   Properties h = new Properties();
   h.put(Context.INITIAL_CONTEXT_FACTORY,
      "weblogic.jndi.WLInitialContextFactory");
   h.put(Context.PROVIDER_URL, url);
   h.put(Context.SECURITY_PRINCIPAL, user);
h.put(Context.SECURITY_CREDENTIALS, password); 

   return new InitialContext(h);

Remote clients obtain an InitialContext from the WebLogic Server InitialContext factory.

Programming Client to Look Up a Home Interface

By following an EJB reference. This approach offers better performance than the alternative, looking up the home interface directly from the Java Naming and Directory Interface, and is a BEA best practice. For instructions on using EJB references, see the following section, Using EJB Links.
Directly from the Java Naming and Directory Interface (JNDI). The container binds the entity bean’s home interface in the global, server-side JNDI name space. For instructions see Programming WebLogic JNDI.

Using EJB Links

Using EJB links is a BEA best practice and WebLogic Server fully supports EJB links as defined in the EJB 2.1 Specification. You can link an EJB reference that is declared in one application component to an enterprise bean that is declared in the same J2EE application.

In the ejb-jar.xml file, specify the link to the EJB using the ejb-link element of the ejb-ref element of the referencing application component. The value of ejb-link must match that of the ejb-name in both ejb-jar.xml and weblogic-ejb-jar.xml of the target EJB. The target EJB can be in any EJB JAR file in the same J2EE application as the referencing application component.

Because ejb-names are not required to be unique across EJB JAR files, you may need to provide the qualified path for the link. Use the following syntax to provide the path name for the EJBs within the same J2EE application.

This reference provides the path name of the EJB JAR file that contains the referenced EJB with the appended ejb-name of the target bean separated from the path by “#”. The path name is relative to the referencing application component JAR file.

Configuring EJBs to Send Requests to a URL

To enable an EJB to open an HttpURLConnection to an external HTTP server using the java.net.URL resource manager connection factory type, specify the URL, or specify an object bound in the JNDI tree that maps to a URL, using the resource-ref element in ejb-jar.xml and the res-ref-name element in weblogic-ejb-jar.xml.

Specifying an HTTP Resource by URL

Specifying an HTTP Resource by Its JNDI Name

To specify an object that is bound in JNDI and maps to a URL, instead of specifying a URL:

Accessing HTTP Resources from Bean Code

Regardless of how you specified an HTTP resource—by its URL or a JNDI name that maps to the URL—you can access it from EJB code in this way:

URL url = (URL) context.lookup("java:comp/env/url/MyURL");
connection = (HttpURLConnection)url.openConnection();

Configuring Network Communications for an EJB

You can control the attributes of the network connection an EJB uses for communications by configuring a custom network channel and assigning it to the EJB. For information about WebLogic Server network channels and associated configuration instructions see “Configure Network Resources” in Configuring WebLogic Server Environments. After you configure a custom channel, assign it to an EJB using the network-access-point element in weblogic-ejb-jar.xml.

Programming and Configuring Transactions

Transaction design decisions are discussed in . The following sections contain guidelines for programming transactions.

Programming Container-Managed Transactions

Container-managed transactions are simpler to program than bean-managed transactions, because they leave the job of demarcation—starting and stopping the transaction—to the EJB container.

You configure the desired transaction behaviors in ejb-jar.xml and weblogic-ejb-jar.xml. For related information see Container-Managed Transactions Elements.

Preserve transaction boundaries—Do not invoke methods that interfere with the transaction boundaries set by the container. Do not use:

The commit, setAutoCommit, and rollback methods of java.sql.Connection
The getUserTransaction method of javax.ejb.EJBContext
Any method of javax.transaction.UserTransaction

Roll back transactions explicitly—To cause the container to roll back a container-managed transaction explicitly, invoke the setRollbackOnly method of the EJBContext interface. (If the bean throws an application exception, typically an EJBException, the rollback is automatic.)
Avoid serialization problems—Many data stores provide limited support for detecting serialization problems, even for a single user connection. In such cases, even with transaction-isolation in weblogic-ejb-jar.xml set to TransactionSerializable, exceptions or rollbacks in the EJB client might occur if contention occurs between clients for the same rows. To avoid such exceptions, you can:

Include code in your client application to catch SQL exceptions, and resolve them appropriately; for example, by restarting the transaction.
For Oracle databases, use the transaction isolation settings described in isolation-level.

Configuring Automatic Retry of Container-Managed Transactions

In this release of WebLogic Server, you can specify that, if a business method that has started a transaction fails because of a transaction rollback that is not related to a system exception, the EJB container will start a new transaction and retry the failed method up to a specified number of times. If the method fails for the specified number of retry attempts, the EJB container throws an exception.

Make sure your bean is a container-managed session or entity bean.

You can configure automatic retry of container-managed transactions for container-managed session and entity beans only. You cannot configure automatic retry of container-managed transactions for message-driven beans because MDBs do not acknowledge receipt of a message they are processing when the transaction that brackets the receipt of the message is rolled back; messages are automatically retried until they are acknowledged. You also cannot configure automatic retry of container-managed transactions for timer beans because, when a timer bean’s ejbTimeout method starts and is rolled back, the timeout is always retried.

Make sure the business methods for which you want to configure automatic retry of transactions are defined in the bean’s remote or local interface or as home methods (local home business logic that is not specific to a particular bean instance) in the home interface; the methods must have one of the following container-managed transaction attributes:

RequiresNew. If a method’s transaction attribute (trans-attribute element in ejb-jar.xml) is RequiresNew, a new transaction is always started prior to the invocation of the method and, if configured, automatic retry of transactions occurs if the transaction fails.
Required. If a method’s transaction attribute (trans-attribute element in ejb-jar.xml) is Required, the method is retried with a new transaction only if the failed transaction was begun on behalf of the method.

For more information on:

Programming interfaces, see Create EJB Classes and Interfaces and Sun documentation.
The trans-attribute element in ejb-jar.xml, see trans-attribute in and Sun documentation.

Make sure the methods for which you want to enable automatic retry of transactions are safe to be re-invoked. A retry of a failed method must yield results that are identical to the results the previous attempt, had it been successful, would have yielded. In particular:

If invoking a method initiates a call chain, it must be safe to reinvoke the entire call chain when the method is retried.
All of the method’s parameters must be safe for reuse; when a method is retried, it is retried with the same parameters that were used to invoke the failed attempt. In general, parameters that are primitives, immutable objects, or are references to read-only objects are safe for reuse. If a parameter is a reference to an object that is to be modified by the method, reinvoking the method must not negatively affect the result of the method call.
If the bean that contains the method that is being retried is a stateful session bean, the bean’s conversational state must be safe to re-invoke. Since a stateful session bean’s state is not transactional and is not restored during a transaction rollback, in order to use the automatic retry of transactions feature, you must first be sure the bean’s state is still valid after a rollback.

Specify the methods for which you want the EJB container to automatically retry transactions and the number of retry attempts you want the EJB container to make in the retry-methods-on-rollback element in weblogic-ejb-jar.xml.

The retry-count subelement to retry-methods-on-rollback can also be modified via the Administration Console.

Programming Bean-Managed Transactions

This section contains programming considerations for bean-managed transactions. For a summary of the distinguishing features of bean-level transactions and a discussion of related design considerations, see Bean-Level Transaction Management.

Demarcate transaction boundaries—To define transaction boundaries in EJB or client code, you must obtain a UserTransaction object and begin a transaction before you obtain a Java Transaction Service (JTS) or JDBC database connection. To obtain the UserTransaction object, use this command:

ctx.lookup("javax.transaction.UserTransaction");

After obtaining the UserTransaction object, specify transaction boundaries with tx.begin(), tx.commit(), tx.rollback().

If you start a transaction after obtaining a database connection, the connection has no relationship to the new transaction, and there are no semantics to “enlist” the connection in a subsequent transaction context. If a JTS connection is not associated with a transaction context, it operates similarly to a standard JDBC connection that has autocommit equal to true, and updates are automatically committed to the datastore.

Once you create a database connection within a transaction context, that connection is reserved until the transaction commits or rolls back. To optimize performance and throughput, ensure that transactions complete quickly, so that the database connection can be released and made available to other client requests. See Features and Design Patterns for more information.

Note:

You can associate only a single database connection with an active transaction context.

Setting transaction isolation level—For bean-managed transactions, you define isolation level in the bean code. Allowable isolation levels are defined on the java.sql.Connection interface. F or information on isolation level behaviors, see isolation-level.

See Listing 4-3 for a code sample.

Listing 4-3 Setting Transaction Isolation Level in BMT

import javax.transaction.Transaction;
import java.sql.Connection
import weblogic.transaction.TxHelper:
import weblogic.transaction.Transaction;
import weblogic.transaction.TxConstants;

User Transaction tx = (UserTransaction)

ctx.lookup("javax.transaction.UserTransaction");

//Begin user transaction

     			tx.begin();

//Set transaction isolation level to TransactionReadCommitted

Transaction tx = TxHelper.getTransaction();
     	tx.setProperty (TxConstants.ISOLATION_LEVEL, new Integer
     	(Connection.TransactionReadCommitted));

//perform transaction work

     tx.commit();

Avoid restricted methods—Do not invoke the getRollbackOnly and setRollbackOnly methods of the EJBContext interface in bean-managed transactions. These methods should be used only in container-managed transactions. For bean-managed transactions, invoke the getStatus and rollback methods of the UserTransaction interface.
Use one connection per active transaction context—You can associate only a single database connection with an active transaction context.

Programming Transactions That Are Distributed Across EJBs

This section describes two approaches for distributing a transaction across multiple beans, which may reside on multiple server instances.

Calling multiple EJBs from a client’s transaction context

The code fragment below is from a client application that obtains a UserTransaction object and uses it to begin and commit a transaction. The client invokes two EJBs within the context of the transaction.

u = (UserTransaction) jndiContext.lookup("javax.transaction.UserTransaction");
u.begin();
account1.withdraw(100);
account2.deposit(100);
u.commit();
...

The updates performed by the account1 and account2 beans occur within the context of a single UserTransaction. The EJBs commit or roll back together, as a logical unit, whether the beans reside on the same server instance, different server instances, or a WebLogic Server cluster.

All EJBs called from a single transaction context must support the client transaction—each beans' trans-attribute element in ejb-jar.xml must be set to Required, Supports, or Mandatory.

Using an EJB “Wrapper” to Encapsulate a Cross-EJB Transaction

You can use a “wrapper” EJB that encapsulates a transaction. The client calls the wrapper EJB to perform an action such as a bank transfer, and the wrapper starts a new transaction and invokes one or more EJBs to do the work of the transaction.

The wrapper EJB can explicitly obtain a transaction context before invoking other EJBs, or WebLogic Server can automatically create a new transaction context, if the wrapper’s trans-attribute element in ejb-jar.xml is set to Required or RequiresNew.

All EJBs invoked by the wrapper EJB must support the wrapper EJB’s transaction context— their trans-attribute elements must be set to Required, Supports, or Mandatory.

Programming the EJB Timer Service

This release of WebLogic Server supports the EJB timer service defined in the EJB 2.1 Specification. The EJB timer service is an EJB-container provided service that allows you to create timers that schedule callbacks to occur when a timer object expires. Timer objects can be created for entity beans, message-driven beans, and stateless session beans. Timer objects expire at a specified time, after an elapsed period of time, or at specified intervals. For instance, you can use the timer service to send out notification when an EJB remains in a certain state for an elapsed period of time.

The WebLogic EJB timer service is intended to be used as a coarse-grained timer service. Rather than having a large number of timer objects performing the same task on a unique set of data, BEA recommends using a small number of timers that perform bulk tasks on the data. For example, assume you have an EJB that represents an employee’s expense report. Each expense report must be approved by a manager before it can be processed. You could use one EJB timer to periodically inspect all pending expense reports and send an email to the corresponding manager to remind them to either approve or reject the reports that are waiting for their approval.

Using Java Programming Interfaces to Program Timer Objects

This section summarizes the Java programming interfaces defined in the EJB 2.1 Specification that you can use to program timers. For detailed information on these interfaces, refer to the EJB 2.1 Specification. This section also provides details about the WebLogic Server-specific timer-related interfaces.

EJB 2.1 Timer-Related Programming Interfaces

The javax.ejb.TimedObject interface, which must be implemented by the enterprise bean class of a bean that will be registered with the timer service for timer callbacks. This interface has a single method, ejbTimeout.
The EJBContext interface, which has a getTimerService method, through which the timer service is accessed.
The javax.ejb.TimerService interface which allows you to create new EJB timers or access existing EJB timers for the EJB.
The javax.ejb.Timer interface which contains information about a particular EJB timer.
The javax.ejb.TimerHandle interface which allows WebLogic Server to obtain a serializable timer handle that can be persisted. Since timers are local objects, a TimerHandle must not be passed through a bean’s remote interface or Web service interface.

For more information on EJB 2.1 timer-related programming interfaces, see the EJB 2.1 Specification.

WebLogic Server-Specific Timer-Related Programming Interfaces

This section describes WebLogic Server-specific interfaces you can use to program timers.

The weblogic.management.runtime.EJBTimerRuntimeMBean, which provides runtime information and administrative functionality for timers from a particular EJBHome. The weblogic.management.runtime.EJBTimerRuntimeMBean interface is shown in Listing 4-4.

Listing 4-4 weblogic.management.runtime.EJBTimerRuntimeMBean Interface

public interface weblogic.management.runtime.EJBTimerRuntimeMBean {

  public int getTimeoutCount(); // get the number of successful timeout notifications that have been made

  public int getActiveTimerCount(); // get the number of active timers for this EJBHome

  public int getCancelledTimerCount(); // get the number of timers that have been cancelled for this EJBHome

  public int getDisabledTimerCount(); // get the number of timers temporarily disabled for this EJBHome

  public void activateDisabledTimers(); // activate any temporarily disabled timers

The weblogic.ejb.WLTimerService interface which extends the javax.ejb.TimerService interface to allow users to specify WebLogic Server-specific configuration information for a timer. The weblogic.ejb.WLTimerService interface is shown in Listing 4-5; for information on the javax.ejb.TimerService, see the EJB 2.1 Specification.

Listing 4-5 weblogic.ejb.WLTimerService Interface

public interface WLTimerService extends TimerService {

  public Timer createTimer(Date initial, long duration, Serializable info,

    WLTimerInfo wlTimerInfo)

    throws IllegalArgumentException, IllegalStateException, EJBException;

  public Timer createTimer(Date expiration, Serializable info,

    WLTimerInfo wlTimerInfo)

    throws IllegalArgumentException, IllegalStateException, EJBException;

  public Timer createTimer(long initial, long duration, Serializable info

    WLTimerInfo wlTimerInfo)

    throws IllegalArgumentException, IllegalStateException, EJBException;

  public Timer createTimer(long duration, Serializable info,

    WLTimerInfo wlTimerInfo)

    throws IllegalArgumentException, IllegalStateException, EJBException;

The weblogic.ejb.WLTimerInfo interface which is used in the weblogic.ejb.WLTimerService interface to pass WebLogic Server-specific configuration information for a timer. The weblogic.ejb.WLTimerInfo method is shown in Listing 4-6

Listing 4-6 weblogic.ejb.WLTimerInfo Interface

public final interface WLTimerInfo {

  public static int REMOVE_TIMER_ACTION  = 1;

  public static int DISABLE_TIMER_ACTION = 2;

  public static int SKIP_TIMEOUT_ACTION  = 3;

/**

   * Sets the maximum number of retry attempts that will be

   * performed for this timer.  If all retry attempts

   * are unsuccesful, the timeout failure action will

   * be executed.

*/

  public void setMaxRetryAttempts(int retries);

  public int getMaxRetryAttempts();

/**

   * Sets the number of milliseconds that should elapse

   * before any retry attempts are made.

*/

  public void setRetryDelay(long millis);

  public long getRetryDelay();

/**

   * Sets the maximum number of timeouts that can occur

   * for this timer.  After the specified number of

   * timeouts have occurred successfully, the timer

   * will be removed.

*/

  public void setMaxTimeouts(int max);

  public int getMaxTimeouts();

/**

   * Sets the action the container will take when ejbTimeout

   * and all retry attempts fail.  The REMOVE_TIMER_ACTION,

   * DISABLE_TIMER_ACTION, and SKIP_TIMEOUT_ACTION fields

   * of this interface define the possible values.

*/

  public void setTimeoutFailureAction(int action);

  public int getTimeoutFailureAction();

The weblogic.ejb.WLTimer interface which extends the javax.ejb.Timer interface to provide additional information about the current state of the timer. The weblogic.ejb.WLTimer interface is shown in Listing 4-7.

Listing 4-7 weblogic.ejb.WLTimer Interface

public interface WLTimer extends Timer {

  public int getRetryAttemptCount();

  public int getMaximumRetryAttempts();

  public int getCompletedTimeoutCount();

Timer Deployment Descriptors

Server Failure and Timers

You cannot migrate a timer object from one server to another; timer objects can only be migrated as part of an entire server. If a server that contains EJB timers goes down for any reason, you must restart the server or migrate the entire server in order for the timers to execute.

Clustering of EJB Timers

WebLogic Server does not support clustering of EJBs that use timers. Timers will only execute on the server on which they are created and are only visible to the beans on that server. If you deploy an EJB to a cluster, and invoke the EJB to create a timer, that call could go to any server on the cluster. Another invocation (for instance, to cancel the timer) could also go to any server on the cluster and will not necessarily go to the same server in which the call to create the timer went. For instance, if the call to create a timer is directed to server1, and the call to cancel it is directed to server2, the EJB on server2 would not see the timer on server1 and would, therefore, fail to cancel it.

Pin the EJB deployment to a single server in the cluster. This causes all calls to the EJB to go to server to which the EJB is pinned and all timers to exist on that same server. The tradeoff to using this approach is that the EJB cannot take advantage of clustering benefits such as load balancing and failover.
Ensure that calls to cancel timers go to all servers in the cluster by using a message-driven bean (MDB) that listens on a JMS topic. The message to cancel the timer can be published to the JMS topic and serviced by an MDB on each server. Then, the MDB on each server can invoke a cancelTimer method on the bean. The tradeoff to using this approach is that it makes your application more complex and attempting to cancel timers on all servers is inefficient.

Declare Web Service References

This release of WebLogic Server complies with the EJB 2.1 requirements related to declaring and accessing external Web Services. Web Service references, declared in an EJB’s deployment descriptor, maps a logical name for a Web Service to an actual Web Service interface, which allows you to refer to the Web Service using a logical name. The bean code then performs a JNDI lookup using the Web Service reference name.

Compile Java Source

For information on the compilation process, see “Compiling Java Code” in Developing Applications with WebLogic Server.

Generate Deployment Descriptors

If you annotate your Bean class file with JDK 1.5 annotations, you can use EJBGen to generate the Remote and Home classes and the deployment descriptor files for an EJB application.

BEA reccommends that you use EJBGen to generate deployment descriptors. For more information, see EJBGen Reference.

Edit Deployment Descriptors

Elements in ejb-jar.xml, weblogic-ejb-jar.xml, and for container-managed persistence entity beans, weblogic-cmp-jar.xml, control the run-time characteristics of your application.

If you need to modify a descriptor element, you can edit the descriptor file with any plain text editor. However, to avoid introducing errors, use a tool designed for XML editing. Descriptor elements that you can edit with the WebLogic Server Administration Console are listed in Table 4-11.

The following sections are a quick reference to WebLogic Server-specific deployment elements. Each section contains the elements related to a type of feature or behavior. The table in each section defines relevant elements in terms of the behavior it controls, the bean type it relates to (if bean type-specific), the parent element in weblogic-ejb-jar.xml that contains the element, and the behavior you can expect if you do not explicitly specify the element in weblogic-ejb-jar.xml.

For comprehensive documentation of the elements in each descriptor file, definitions, and sample usage, refer to:

weblogic-ejb-jar.xml Deployment Descriptor Reference
weblogic-cmp-jar.xml Deployment Descriptor Reference
Your Sun documentation for elements in ejb-jar.xml.

Note:

In the sections that follow, click the element name in the “Element” column to view detailed documentation on the element.

Security Elements

Table 4-2 Security Elements in weblogic-ejb-jar.xml
Element	Description	Default
`security-role-assignment`	Maps security roles in `ejb-jar.xml` file to the names of security principals in WebLogic Server. Required if ejb-jar.xml defines application roles.	none
`security-permission`	Additional Java security permission that is granted to this EJB.	none
`run-as-principal-name`	Security principal name to use as the run-as principal for a bean that has specified a `security-identity` `run-as-role-name` in `ejb-jar.xml`.	none
`iiop-security-descriptor`	Security options for beans that use the RMI-IIOP protocol.	none

Resource Mapping Elements

This table lists the elements in weblogic-ejb-jar.xml that map the names of beans or resources used in source code to their JNDI names in the deployment environment.

Element

Bean Type

Description

Default

jndi-name

All

JNDI name of a resource or reference available in WebLogic Server.

Note:

Assigning a JNDI name to a bean is not recommended. Global JNDI names generate heavy multicast traffic during clustered server startup. See Using EJB Links for the better practice.

none

local-jndi-name

All

JNDI name for a bean's local home. If a bean has both a remote and a local home, then it must have two JNDI names; one for each home.

none

connection-factory-jndi-name

MDB

JNDI name of the JMS connection factory that the bean uses to create queues and topics.

weblogic.
jms.
Message
DrivenBeanConnectionFactory

destination-jndi-name

MDB

JNDI name that associates a message-driven bean with a queue or topic in the JNDI tree.

initial-context-factory

MDB

Initial context factory that the EJB container uses to create connection factories.

weblogic.
jndi.
WLInitial
Context
Factory

jms-client-id

MDB

Client ID for the message-driven bean associated with a durable subscriber topic.

Value of ejb-name

message-destination-descriptor

MDB

Maps a message destination reference in the ejb-jar.xml file to an actual message destination, such as a JMS Queue or Topic, in WebLogic Server.

provider-url

MDB

Specifies the URL provider to be used by the InitialContext.

t3://localhost:7001

Persistence Elements

This table lists elements in weblogic-ejb-jar.xml that specify how the state of a bean is persisted.

Element

Bean Type

Description

Default

type-identifier

Entity

Specifies EJB persistence type. WebLogic Server RDBMS-based persistence uses the identifier, WebLogic_CMP_RDBMS

type-storage

Entity

Defines path, relative to the top level of the EJB’s JAR deployment file or deployment directory, of the file that stores data for this persistence type.

WebLogic Server RDBMS-based persistence generally uses an XML file named weblogic-cmp-jar.xml to store persistence data for a bean. This file is stored in the META-INF subdirectory of the JAR file.

type-version

Entity

Version of the persistence type specified by type-identifier. For WebLogic 2.0 CMP persistence, use the value 2.0.

For WebLogic 1.1 CMP persistence, use the value 1.1.

delay-updates-until-end-of-tx

Entity

If true, the EJB container attempts to delay writing updates to a bean's state to the database until the end of a transaction. However, the container still flushes updates to the database before executing an EJB finder or select query if the include-updates element (in the weblogic-query element of weblogic-cmp-jar.xml) for the query is true.

Applicable to both container-managed persistence and bean-managed persistence beans.

True

finders-load-bean

Entity

Causes beans returned by a finder or ejbSelect method to be loaded immediately into the cache before the method returns.

Note:

Applicable to container-managed persistence beans only.

True

persistent-store-dir

Stateful Session

Directory where state of passivated stateful session bean instances is stored.

is-modified-method-name

Entity

The method called by the container to determine whether or not the bean has been modified and needs to have its changes written to the database.

Applies to bean-managed persistence or EJB 1.1 container-managed persistence beans.

If not specified, bean state is persisted after each method completes.

Clustering Elements

This table lists the elements in weblogic-ejb-jar.xml related to clustering. These elements control failover and load balancing behaviors for clustered beans in a WebLogic Server cluster.

Table 4-5 Clustering Elements in weblogic-ejb-jar.xml
Element	Bean Type	Description	Default
`home-call-router-class-name`	Stateful Session Stateless Session Entity	Custom class to be used for routing home method calls. This class must implement `weblogic.rmi.extensions.CallRouter()`.	None
`home-is-clusterable`	Stateful Session Stateless Session Entity	Indicates whether the bean home can be clustered.	True
`home-load-algorithm`	Stateful Session Stateless Session Entity	Algorithm to use for load-balancing among replicas of the bean home.	Value of `weblogic. cluster. defaultLoad Algorithm`
`idempotent-methods`		Idempotent methods for a clustered EJB. An idempotent method can be repeated with no negative side-effects. Methods of stateless session bean homes and read-only entity bean interfaces do not need to be explicitly identified—they are automatically set to be idempotent.	None
`replication-type`	Stateful Session	Indicates the replication used for stateful session beans in a cluster: `in-memory` or `none`.	`none`
`stateless-bean-call-router-class-name`	Stateless Session	Custom class to be used for routing bean method calls.	None
`stateless-bean-is-clusterable`	Stateless Session	Indicates that the bean is clusterable. Use only for session beans whose `session-type` in `ejb-jar.xml` is `Stateless`.	True
`stateless-bean-load-algorithm`	Stateless Session	Algorithm to use for load-balancing among replicas of the bean.	Value of the property `weblogic. cluster. defaultLoad Algorithm`
`use-serverside-stubs`	Stateless Session	Causes the bean home to use server-side stubs in the server context.	False

Data Consistency Elements

This table lists the elements in weblogic-ejb-jar.xml related to the consistency of the bean instance data and the database. These elements control behaviors such as how and when the database is updated to reflect the values in the bean instance is done.

Container-Managed Transactions Elements

Table 4-7 lists the elements in ejb-jar.xml related to container-managed transactions.

Element

Description

Default

transaction-type

Allowable values are Bean or Container.

None, EJB 2.x requires this attribute to be specified.

trans-attribute

Specifies how the container manages the transaction boundaries when delegating a method invocation to an enterprise bean's business method. Allowable values are:

NotSupported

With the NotSupported value, when an entity bean runs in an unspecified transaction, if a transaction exists, the EJB container suspends the transaction; when an entity bean runs in an unspecified transaction, and no transaction exists, the EJB container takes no action.

Supports

With the Supports value, when an entity bean runs in an unspecified transaction, if a transaction exists, the EJB container uses the current transaction; when an entity bean runs in an unspecified transaction, and no transaction exists, the EJB container takes no action.

Required
RequiresNew
Mandatory
Never

With the Never value, when an entity bean runs in an unspecified transaction, if a transaction exists, the EJB container throws an exception; when an entity bean runs in an unspecified transaction, and no transaction exists, the EJB container takes no action.

Note: In in pre-9.0 releases of WebLogic Server, the EJB container would start a new transaction when no transaction existed and the value of trans-attribute was NotSupported, Supports, and Never. Set entity-always-uses-transaction in weblogic-ejb-jar.xml to True if you want the EJB container to behave as it did in pre-9.0 releasesof WebLogic Server and create a new transaction.

Because clients do not provide a transaction context for calls to an MDB, MDBs that use container-managed transactions must have trans-attribute of Required.

If not specified, the EJB container issues a warning, and uses NotSupported for MDBs and Supports for other types of EJBs.

transaction-scope

This optional element specifies whether an enterprise bean requires distributed transactions for its methods or whether the local transaction optimization may be used.

Allowable values are Local and Distributed.

If not specified, the container assumes that distributed transactions must be used.

Table 4-8 lists the elements in weblogic-ejb-jar.xml related to container-managed transactions.

Performance Elements

Element

Bean Type

Description

Default

allow-concurrent-calls

Stateful Session

Whether multiple clients can simultaneously access a bean without triggering a Remote Exception.

The server throws a RemoteException when a stateful session bean instance is currently handling a method call and another (concurrent) method call arrives on the server.

False

cache-between-transactions

Entity

Causes the container to cache the persistent data of an entity bean between transactions.

False

cache-type

Stateful Session

Order in which stateful session beans are removed from the cache.

NRU

(not recently used)

clients-on-same-server

All

Indicates that all clients of the bean are collocated with the bean on the same server instance. This element is only used if the EJB has a global JNDI name; setting it to true prevents the JNDI name from being replicated.

A value of true can reduce cluster startup time in large clusters.

False

delay-updates-until-end-of-tx

Entity

If true, the EJB container attempts to delay writing updates to a bean's state to the database until the end of a transaction.

However, the container still flushes updates to the database before executing an EJB finder or select query if the include-updates element (in the weblogic-query element of weblogic-cmp-jar.xml) for the query is true.

Applicable to both container-managed persistence and bean-managed persistence beans.

True

dispatch-policy

All

Specifies the thread pool used to handle requests to the bean.

None

enable-call-by-reference

All

Improves performance of method invocation for methods called within the same application, by allowing parameters to be passed by reference.

Note:

Method parameters are always passed by value when an EJB is called remotely.

False

entity-cache-name

Entity

The application-level entity cache, which can cache instances of multiple entity beans that are part of the same application.

Note: Application level caches are declared in the weblogic-application.xml.

None

estimated-bean-size

Entity

Estimated average size, in bytes, of an entity bean instance.

None

finders-load-bean

Entity

Causes beans returned by a finder or ejbSelect method to be loaded immediately into the cache before the method returns.

Note:

Applicable to container-managed persistence beans only.

True

idle-timeout-seconds

Entity

Number of seconds of inactivity after which a bean is passivated.

Note:

This element is not currently used.

600

idle-timeout-seconds

Stateful Session

Number of seconds of inactivity after which a bean is passivated.

600

initial-beans-in-free-pool

Entity

Message-Driven

Stateless Session

Number of instances of an EJB instantiated by the container at startup.

is-modified-method-name

Entity

The method that changes the state of bean. Specifying this method causes WebLogic server to persist the bean state when the method completes.

Note:

Applies to bean-managed persistence or EJB 1.1 container-managed persistence beans.

If not specified, bean state is persisted after each method completes.

jms-polling-interval-seconds

Message-driven

The number of seconds between attempts by the EJB container to reconnect to a JMS destination that has become unavailable.

max-beans-in-cache

Entity

Stateful Session

Maximum number of instances in the cache.

1000

max-beans-in-free-pool

Entity

Stateless Session

Message-Driven

Maximum number of instances in the free pool.

1000

read-timeout-seconds

Entity

The number of seconds between ejbLoad calls on a read-only entity bean. If read-timeout-seconds is 0, ejbLoad is only called when the bean is brought into the cache.

600

Network Communications Elements

This table lists the elements in weblogic-ejb-jar.xml related to network communications.

Table 4-10 Communications Elements in weblogic-ejb-jar.xml
Element	Bean Type	Description	Default
`network-access-point`	all	Assigns a custom network channel to an EJB.	n/a

Generate EJB Wrapper Classes, and Stub and Skeleton Files

Container classes include the internal representation of the EJB that WebLogic Server uses and the implementation of the external interfaces (home, local, and/or remote) that clients use. You can use BEA Workshop for WebLogic Platform 9.2 or appc to generate container classes.

Container classes are generated in according to the descriptor elements in weblogic-ejb-jar.xml. For example, if you specify clustering elements, appc creates cluster-aware classes that will be used for deployment. You can use appc directly from the command line by supplying the required options and arguments. See appc for more information.

The following figure shows the container classes added to the deployment unit when the EAR or JAR file is generated.

appc and Generated Class Name Collisions

Although infrequent, when you generate classes with appc, you may encounter a generated class name collision which could result in a ClassCastException and other undesirable behavior. This is because the names of the generated classes are based on three keys: the bean class name, the bean class package, and the ejb-name for the bean. This problem occurs when you use an EAR file that contains multiple JAR files and at least two of the JAR files contain an EJB with both the same bean class, package, or classname, and both of those EJBs have the same ejb-name in their respective JAR files. If you experience this problem, change the ejb-name of one of the beans to make it unique.

Because the ejb-name is one of the keys on which the file name is based and the ejb-name must be unique within a JAR file, this problem never occurs with two EJBs in the same JAR file. Also, because each EAR file has its own classloader, this problem never occurs with two EJBs in different EAR files.

Package

Packaging Considerations for EJBs with Clients in Other Applications

WebLogic Server supports the use of ejb-client.jar files for packaging the EJB classes that a programmatic client in a different application requires to access the EJB.

Specify the name of the client JAR in the ejb-client-jar element of the bean's ejb-jar.xml file. When you run the appc compiler, a JAR file with the classes required to access the EJB is generated.

Make the client JAR available to the remote client. For Web applications, put the ejb-client.jar in the /lib directory. For non-Web clients, include ejb-client.jar in the client’s classpath.

Deploy

Deploying an EJB enables WebLogic Server to serve the components of an EJB to clients. You can deploy an EJB using one of several procedures, depending on your environment and whether or not your EJB is in production.

Solving Problems During Development

The following sections describe WebLogic Server features that are useful for checking out and debugging deployed EJBs.

Adding Line Numbers to Class Files

If you compile your EJBs with appc, you can use the appc -lineNumbers command option to add line numbers to generated class files to aid in debugging. For information, see appc Reference.

Monitoring Data

WebLogic Server collects a variety of data about the run-time operation of a deployed EJB. This data, which you can view in the Deployments node of the Administration Console, can be useful in determining if an EJB has completed desired processing steps. To access EJB run-time statistics, expand the Deployment node in the Administration Console, navigate to the JAR EAR that contains the bean, and select the Monitoring tab.

For information about the data available, see these pages in Administration Console Online Help:

Creating Debug Messages

WebLogic Server Tools for Developing EJBs

Administration Console

In the Administration Console, you can view, modify, and persist to the descriptor file within the EJB a number of deployment descriptor elements. Descriptors are modified in the Administration Server copy of the EJB as well as in any deployed copies of the EJB (after deployment). When you modify descriptors, changes are made to your (the user’s) original copy of the EJB (prior to deployment).

However, updating these descriptor elements takes place dynamically at runtime without requiring that the EJB be redeployed. The descriptor element that you can change in the Administration Console are limited to only those that may be dynamically changed at runtime, as summarized in Table 4-11.

Table 4-11 Descriptor Elements Available from Administration Console
EJB Type	Editable Elements
Entity	`max-beans-in-cache` `max-beans-in-free-pool` `key-cache-size` `trans-timeout-seconds` `read-timeout-seconds (read-only entity beans only)`
Message-Driven	`max-beans-in-free-pool` `message-selector` `jms-polling-interval-seconds` `trans-timeout-seconds`
Stateless	`max-beans-in-free-pool` `trans-timeout-seconds`
Stateful	`max-beans-in-free-pool` `idle-timeout-seconds` `trans-timeout-seconds`

javac

The javac compiler provided with the Sun Java J2SE SDK provides java compilation capabilities. For information on javac, see http://java.sun.com/docs/.

EJBGen

EJBGen is an EJB 2.x code generator. You can annotate your bean class file with javadoc tags and then use EJBGen to generate the remote and home interface classes and the deployment descriptor files for an EJB application, reducing to one the number of EJB files you need to edit and maintain.

BEA recommends that you use EJBGen to generate deployment descriptors; this is a BEA best practice which allows for easier and simpler maintenance of EJBs. When you use EJBGen, you have to write and annotate only one bean class file, which simplifies writing, debugging, and maintenance. If you use BEA Workshop for WebLogic Platform 9.2 as a development environment, Workshop automatically inserts EJBGen tags for you.

weblogic.Deployer

The weblogic.Deployer command-line tool is a Java-based deployment tool that provides a command line interface to the WebLogic Server deployment API. This tool was developed for administrators and developers who need to initiate deployment from the command line, a shell script, or any automated environment other than Java.

appc

The appc compiler generates and compiles the classes needed to deploy EJBs and JSPs to WebLogic Server. It validates the deployment descriptors for compliance with the current specifications at both the individual module level and the application level. The application-level checks include checks between the application-level deployment descriptors and the individual modules as well as validation checks across the modules.

DDConverter

DDConverter is a command line tool that upgrades deployment descriptors from earlier releases of WebLogic Server. BEA recommends that you always upgrade your deployment descriptors in order to take advantage of the features in the current J2EE specification and release of WebLogic Server.

Comparison of EJB Tool Features

The following table lists BEA tools for EJB development, and the features provided by each.

Programming WebLogic Enterprise JavaBeans

Implementing Enterprise Java Beans

Overview of the EJB Development Process

Create a Source Directory

Create EJB Classes and Interfaces

Using WebLogic Server Generic Bean Templates

Programming Client Access to EJBs

Programming Client to Obtain Initial Context

Programming Client to Look Up a Home Interface

Using EJB Links

Configuring EJBs to Send Requests to a URL

Specifying an HTTP Resource by URL

Specifying an HTTP Resource by Its JNDI Name

Accessing HTTP Resources from Bean Code

Configuring Network Communications for an EJB

Programming and Configuring Transactions

Programming Container-Managed Transactions

Configuring Automatic Retry of Container-Managed Transactions

Programming Bean-Managed Transactions

Programming Transactions That Are Distributed Across EJBs

Calling multiple EJBs from a client’s transaction context

Using an EJB “Wrapper” to Encapsulate a Cross-EJB Transaction

Programming the EJB Timer Service

Using Java Programming Interfaces to Program Timer Objects

EJB 2.1 Timer-Related Programming Interfaces

WebLogic Server-Specific Timer-Related Programming Interfaces

Timer Deployment Descriptors

Server Failure and Timers

Clustering of EJB Timers

Declare Web Service References

Compile Java Source

Generate Deployment Descriptors

Edit Deployment Descriptors

Security Elements

Resource Mapping Elements

Persistence Elements

Clustering Elements

Data Consistency Elements

Container-Managed Transactions Elements

Performance Elements

Network Communications Elements

Generate EJB Wrapper Classes, and Stub and Skeleton Files

appc and Generated Class Name Collisions

Package

Packaging Considerations for EJBs with Clients in Other Applications

Deploy

Solving Problems During Development

Adding Line Numbers to Class Files

Monitoring Data

Creating Debug Messages

WebLogic Server Tools for Developing EJBs

Administration Console

javac

EJBGen

weblogic.Deployer

appc

DDConverter

Comparison of EJB Tool Features