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 a review of WebLogic Server EJB features, see WebLogic Server Value-Added EJB Features.

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

 

Understanding 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

Figure 4-1 EJB Development Process Overview

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 which configure the runtime behavior and environment for the bean. If you used WebLogic Workshop for previous implementation tasks, generation of deployment descriptors is an automatic as a result of the compilation process. ejb-jar.xml, and optionally:

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 tagged with markup that specifies the optional features the bean uses, and generated the deployment descriptors automatically, edits to your deployment descriptor should be minimal.

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.

 

EJB Development Task Guide

The following sections describe the key tasks in the EJB development process, and provide guidelines for accomplishing particular application goals at each point in the process.

 

Create a Source Directory

Create a source directory where you will assemble the EJB.

BEA recommends a split development directory structure, which segregates source and output files in parallel directory structures. This approach offers many advantages - for a description of the split directory approach and for instructions for setting up a split directory structure, see Introducing the Split Development Directory Structure" in Developing WebLogic Server Applications.

Use of the split directory structure requires that you package your EJB as an enterprise application in an .ear file. 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. For example:

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. You can access EJBGen functionality using WebLogic Workshop, a development environment that EJBGen's capabilities with other development aids, and a provides a friendly user interface. For more information and instructions for using these tools see EJBGen Reference and WebLogic Workshop Help.

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

 

Programming Client Access to EJBs

The following sections provide guidelines accessing EJBs from clients.

 

Programming Client to Obtain Initial Context

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

Figure 4-2 Code sample of a local client performing a lookup

...
Context ctx = getInitialContext("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 Clients Look up a Home Interface

A client can look up the entity bean's home interface in one of two ways:

  • By following an EJB reference. This offers better performance, and is the preferred method. 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

WebLogic Server fully supports EJB links as defined in the EJB 2.0 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.

To create an ejb-link:

  1. Specify the link to the EJB using the optional ejb-link deployment descriptor element of the ejb-ref element of the referencing application component.

    The value of the ejb-link element must be the ejb-name 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.

  2. Use the following syntax to provide the path name for the EJBs within the same J2EE application. 
    <ejb-link>../products/product.jar#ProductEJB</ejb-link>

    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 an object bound in the JNDI tree that maps to a URL, as a resource reference in weblogic-ejb-jar.xml.

Specify the URL in the <jndi-name> element:

<resource-description>
     <res-ref-name>url/MyURL</res-ref-name>
     <jndi-name>http://www.rediff.com/<;;/jndi-name>
</resource-description>

WebLogic Server creates a URL object with the jndi-name provided and binds the object to the java:comp/env. Declare the jndi-name resource reference in weblogic-ejb-jar.xml:

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

<resource-description>
     <res-ref-name>url/MyURL1</res-ref-name>
     <jndi-name>firstName</jndi-name>
</resource-description>

where firstName is the object bound to the JNDI tree that maps to the URL. This binding could be done in a startup class. When jndi-name is not a valid URL, WebLogic Server treats it as a object that maps to a URL and is already bound in the JNDI tree, and binds a LinkRef with that jndi-name.

URL specified either directly or via the JNDI object can be accessed in bean code in this way:

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

 

Transaction Programming Topics

Transaction design decisions are discussed in Features and Design Patterns. The following sections contain guidelines for programming transactions.

For information using transactions with entity beans, see Understanding ejbLoad() and ejbStore() Behavior.

 

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.

These are the key programming considerations for container-managed transactions:

  • Preserving 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
  • Rolling Back Transactions Explicitly - To explicitly cause the container to roll back a container-managed transaction, invoke the setRollbackOnly method of the EJBContext interface. (If the bean throws an application exception, typically an EJBException, the rollback is automatic.)
  • Avoiding Serialization Problems - Many datastores 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 instance by restarting the transaction.
    • for Oracle databases, use the transaction isolation settings described in Transaction Isolation Settings for Oracle Databases.

 

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. These are key guidelines for programming a bean-managed transactions:

  • Demarcating Transaction Boundaries - To define transaction boundaries in EJB or client code, 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, isolation level is defined in the bean code, as shown below:

    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 TRANSACTION_READ_COMMITED

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

    //perform transaction work

         tx.commit();

  • Avoiding 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.

      import javax.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 or reside on the same server instance, different server instances, or a WebLogic Server cluster.

      All EJBs called from a single transaction context must both 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 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.

 

Compile Java Source

WebLogic Workshop is the recommended tool for compiling class files. For more information about WebLogic Workshop, see WebLogic Workshop Help. To see what other tools support the compilation process, see Table 4-11.

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

 

Generate Deployment Descriptors

If you have used WebLogic Workshop or EJBGen to annotate your source files with the tags for desired bean features and run-time behaviors, descriptor generation is an automatic process.

These tools automatically generate the necessary deployment descriptors from your class file, as well as home and remote interfaces, from a bean class file.

For more information see:

 

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, you should use a tool designed for the XML editing, such as EJBgen or WebLogic Builder. Descriptor elements that you can edit with the WebLogic Server Administration Console or listed in Table 4-10.

The following sections are a quick reference to WebLogic Server-specific deployment elements. Each section contains the elements related to a particular the type of feature or behavior. The table in each section defines relevant elements terms of: the behavior it controls, the bean type it relates to (if bean type-specific), the parent stanza 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

    Note: In the sections that follow, click the element name in the "Element" column to view detailed documentation on the element in "weblogic-ejb-jar.xml Deployment Descriptor Reference"

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

 

Security Elements

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

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-xml.jar that map the names of bean or resource and resources used on source code to the actual JNDI names in the deployment environment.

Element

Bean Type

Description

Default

jndi-name
JNDI name of a resource or reference available in WebLogic Server

Note: Assigning a JNDI name to an 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
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
provider-url MDB Specifies the URL provider to be used by the InitialContext. t3://localhost:7001

 

Persistence Elements

This table lists the elements in weblogic-ejb-xml.jar related to 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 stanza 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.
l

 

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.

Element

Bean Type

Description

Default

idempotent-methods
Idempotent methods for a clustered EJB. An idempotent method can be repeated with no negative side-effects.

Note: 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
home-call-router-class-name Stateful Session Custom class to be used for routing home method calls. This class must implement weblogic.rmi.extensions.CallRouter(). None
home-is-clusterable Stateful Session Indicates if the bean home can be clustered. True
home-load-algorithm Stateful Session Algorithm to use for load-balancing among replicas of the bean home. Value of weblogic.
cluster.
defaultLoad
Algorithm
replication-type Stateful Session Indicates the replication used for stateful session beans in a cluster: in-memory or none. None
home-is-clusterable Stateless Session Indicates if the bean home can be clustered. True
home-load-algorithm Stateless Session Algorithm to use for load-balancing among replicas of the home. Value of weblogic.cluster.default
LoadAlgorithm
home-load-algorithm Stateless Session Custom class to be used for routing home method calls. None
use-serverside-stubs Stateless Session Causes the bean home to use server-side stubs in the server context. False
stateless-bean-is-clusterable Stateless Session Indicates that the bean is clusterable.

Note: 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
stateless-bean-call-router-class-name Stateless Session Custom class to be used for routing bean method calls. None
home-call-router-class-name Entity Custom class to be used for routing home method calls. None
home-is-clusterable Entity Indicates if the bean home can be clustered. True
home-load-algorithm Entity Algorithm to use for load-balancing among replicas of the home. Algorithm specified by the property weblogic.
cluster.
defaultLoad
Algorithm
l

 

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 a how and when the work of keeping updating the database to reflect the values in the bean instance is done.

Note: For elements related to container-managed persistence, see Entity Bean Pooling and Caching.

Element

Description

Parent

Default

concurrency-
strategy 		Entity How concurrent access to an entity bean that uses a bean-specific cache - a cache that contains instances of single bean - is managed. entity-
cache 		Database
invalidation-target Entity The read-only entity bean to invalidate when this container-managed persistence entity bean is modified.

Note: Only applicable to EJB 2.0 CMP beans.

entity-
descriptor 		None
concurrency-
strategy 		Entity How concurrent access to an entity bean that uses an application-level cache - which caches instances of multiple beans in an application - is managed.

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

entity-
cache-ref 		Database
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 stanza of weblogic-cmp-jar.xml) for the query is true.Applicable to both container-managed persistence and bean-managed persistence beans. persistence True
l

 

Container-Managed Transactions Elements

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

Element

Description

Parent

Default

transaction-type Allowable values are Bean or Container. session or message-
driven, children of the enterprise-
beans stanza 		EJB 2.0 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. Value must be one of:

  • NotSupported

  • Supports

  • Required

  • RequiresNew

  • Mandatory

  • Never

Note: 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.

container-
transaction 		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 that distributed transactions must be used for its methods of whether the local transaction optimization may be used. Allowable values are Local Distributed. entity,
session, or message-
driven, children of the enterprise-
beans stanza. 		If not specified, the container assumes that distributed transactions must be used.

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

Element

Description

Parent

Default

transaction-isolation The transaction isolation level used when method starts a transaction. The specified transaction level is not used if the method inherits an existing transaction. weblogic-ejb-jar The default of the underlying DBMS
trans-timeout-seconds Maximum duration for a transaction transaction-descriptor None

 

Performance Elements

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

Element

Bean Type

Description

Parent

Default

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. weblogic-
enterprise-
bean 		False
dispatch-policy All Specifies the thread pool used to handle requests to the bean. weblogic-
enterprise-
bean 		None
enable-call-by-reference All Improve 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.

weblogic-
enterprise-
bean 		False
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. entity-cache-ref 600
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 stanza of weblogic-cmp-jar.xml) for the query is true.Applicable to both container-managed persistence and bean-managed persistence beans. persistence True
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.

entity-cache-ref None
idle-timeout-seconds Entity Number of seconds of inactivity after which a bean is passivated.

Note: This element is not currently used.

entity-cache 600
max-beans-in-cache Entity Maximum number instances in the entity cache. entity-cache 1000
cache-
between-
transactions 		Entity Causes the container to cache the persistent data of an entity bean between transactions. entity-cache-ref False
estimated-
bean-size 		Entity Estimated average size, in bytes, of an entity bean instance. entity-cache-ref 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.

persistence True
initial-
beans-in-free-pool 		Entity Number of instances of an entity bean instantiated by the container at start up. pool in entity-descriptor 0
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.

persistence

If not specified, bean state is persisted after each method completes.
max-beans-in-free-pool Entity Maximum number of instances in entity bean pool. pool 1000
initial-
beans-in-
free-pool 		Message-driven Number of instances of a message-drive bean instantiated by the container at start up. pool in message-bean-descriptor 0
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. message-bean-descriptor 10
max-beans-in-free-pool Message-driven Maximum number of instances in the message-driven bean pool. pool in message-bean-descriptor 1000
cache-type Stateful Session Order in which stateful session beans are removed from the cache. stateful-session-cache NRU(not recently used)
idle-timeout-seconds Stateful Session Number of seconds of inactivity after which a bean is passivated. stateful-session-cache 600
max-beans-in-cache Stateful Session When stateful session EJBs are removed from the cache. stateful-session-cache 1000
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 stateful-session-descriptor False
initial-
beans-in-
free-pool 		Stateless Session Number of instances of a stateless session bean instantiated at start up. pool in stateless-session-descriptor 0
max-beans-
in-free-pool 		Stateless Session Maximum size of the free pool of stateless session beans. pool in stateful-session-descriptor 1000
l

 

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 WebLogic Workshop 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 appcfor more information.

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

Figure 4-3 Generating EJB container classes


 

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.

Since 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, since each EAR file has its own classloader, this problem never occurs with two EJBs in different EAR files.

 

Package

BEA recommends that you package EJBs as part of an enterprise application. For more information on recommending packaging practices and packaging alternatives, see Creating WebLogic Server Applications" in Developing WebLogic Server Applications.

 

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 appc is run, the a jar file with the classes required to access the EJB will be 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.

Note: WebLogic Server classloading behavior varies, depending on whether or not the client is stand-alone. Stand-alone clients with access to the ejb-client.jar can load the necessary classes over the network. However, for security reasons, programmatic clients running in a server instance cannot load classes over the network.

 

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.

For general instructions on deploying WebLogic Server applications and modules, including EJBs, see Deploying WebLogic Server Applications. For EJB-specific deployment issues and procedures, see Deployment Guidelines for Enterprise Java Beans, in this book - Programming WebLogic Enterprise JavaBeans.

 

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 and ejbc Reference.

 

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

For information about the information available, see..... in Administration Console Online Help.

For instructions, see Monitoring EJBs in Administration Console Online Help...

To access EJB run-time statistics, expand the Deployment node in the Administration Console, navigate to the .jar that contains the bean, and select the Monitoring tab. For example, select:

  • Deployments - >EJB Modules - >jarfile - >Monitoring, or
  • Deployments - >Applications - >earfile - >jarfile - >Monitoring

This data, which you can view on the Deployments-->EJB --> Monitoring --> Entity EJBs can be useful in determining if an EJB has completed desired processing steps. For information about the monitoring information available in the Administration Console, see processing This section defines the underlying run-time counts from which the statistics in Run-Time Statistics for Entity EJBs are calculated. To display the counts on the EJB --> Monitoring --> Entity EJBs tab page, select Customize this View and choose from the list of available data.

 

Creating Debug Messages

For instructions on how to create messages in your application to help you troubleshoot and solve bugs and problems, see Writing Debug Messages" in Using WebLogic Logging Services.

 

WebLogic Server Tools for Developing EJBs

This section describes BEA tools that support the EJB development process. For a comparison of the features available in each tool, see Table 4-11.

 

WebLogic Workshop

WebLogic Workshop is a shared development environment for the BEA WebLogic Platform. Workshop it supports all aspects of EJB development, from code creation through deployment, and is the BEA-recommended tool for EJB development. Key features include:

  • graphical user interface
  • extensible control model for creating Java controls
  • versatile editor for handling a variety of J2EE file types
  • integrated debugger
  • integrated Ant build scripts
  • automatic insertion of EJBGen tags
  • a full function project environment for creating and maintaining EJBs, generating EJBs from database tables, and deploying applications that contain EJBs to WebLogic Server

For information about WebLogic Workshop, see WebLogic Workshop Help.

 

Administration Console

Using the Descriptors tab 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 using WebLogic Builder or a manual editing tool, 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 attributes contained in the Descriptors tab are limited to only those that may be dynamically changed at runtime, as summarized in Table 4-10.

EJB Type

Editable Elements

Entity

  • read-timeout-seconds (read-only entity beans only)
Message-Driven

Stateless

Stateful


 

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 EJG 2.0 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 WebLogic Workshop as a development environment, WebLogic Workshop automatically inserts EJBGen tags for you.

For an example of an application that uses EJBGen, install the WebLogic 8.1 examples, and see WL_HOME\samples\server\examples\src\examples\ejb20\ejbgen. The application is called Bands.

For information on EJBGen, see EJBGen Reference..

 

WebLogic Builder

WebLogic Builder is a visual environment for editing a deployment descriptor files. You can view these XML files as you visually edit them in WebLogic Builder, but you do not need to make textual edits to the XML files.

WebLogic Builder supports these development tasks:

  • Generate deployment descriptor files for a J2EE module
  • Edit a module's deployment descriptor files
  • View deployment descriptor files
  • Compile and validate deployment descriptor files
  • Deploy a module to a server

For more information on WebLogic Builder, see WebLogic Builder Online Help.

 

DDInit

DDInit is a utility for generating deployment descriptors for WebLogic Server applications. DDInit uses information from the class files to create deployment descriptor files.

WebLogic Builder uses DDInit to generate deployment descriptors. For more information, see WebLogic Builder.

For more information, see DDInit" in WebLogic Server Command Reference.

 

WebLogic Server Ant Utilities

WebLogic Server includes Ant utilities to create skeleton deployment descriptors.

The Ant task examines a directory containing an EJB and creates deployment descriptors based on the directory contents. Because the Ant utility does not have information about all desired configurations and mappings for your EJB, the skeleton deployment descriptors the utility creates are incomplete. After the utility creates the skeleton deployment descriptors, you can use a text editor, an XML editor, or WebLogic Builder to edit the deployment descriptors and complete the configuration of your EJB.

For more information, see wldeploy Ant Task" in Deploying WebLogic Server Applications.

 

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.

For more information, see "weblogic.Deployer Utility" in Deploying WebLogic Server Applications.

 

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.

Note: appc replaces the deprecated ejbc utility (see ejbc). BEA recommends using appc instead ejbc.

For more information, see appc and ejbc Reference.

 

DDConverter

The DDConverter is a command line tool that converts earlier versions EJB deployment descriptors into EJB deployment descriptors that conform to current version of WebLogic Server.

BEA recommends that you always convert descriptors when migrating applications to a new WebLogic Server release.

 

Comparison of EJB Tool Features

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

Generate Interfaces and Home Interfaces

Compile Java

Code

Generate Deployment Descriptors

View and Edit Deployment Descriptors

Deploy

WebLogic Workshop X X X
X
appc
X


javac
X


EJBGen X
X X
WebLogic Builder

X X X
DDinit

X

Administration Console


X X
Deployer



X
DDinit

X

DDConverter

X


Skip navigation bar  Back to Top Previous Next