Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	e-docs   |   Site Map   |   Search   |   Contact   |   Glossary   |   WebLogic Server Documentation
BEA WebLogic Server Enterprise JavaBeans:   Previous topic   |   Next topic   |   Contents

Overview

New Features

EJB 1.1 compliance

Application assembly support in DeployerTool

DDConverter upgrade utility

Full JNDI support for EJB environment

New resource factory support

Support for EJB home handles

Improved free pool management

Improved manageability for multiple persistence types

WebLogic Query Language (WLQL) supports embedded Java

is-modified-method-name support for bean-managed EJBs

New Java type support for multi-object finders

Changed behavior

EJB deployment

javax.ejb.deployment classes not used

Default transaction properties

XML deployment descriptors

Text descriptor to XML element mapping

Deleted deployment properties

.jar and directory deployment units

Unsupported deployment utilities

Persistence Services

File-based persistence not supported

JDBC-based persistence renamed to RDBMS-based persistence

Entity EJB changes

orderBy not supported in WebLogic Query Language

Primary key changes for container-managed EJBs

Simple and compound primary keys

EJB exception changes

New ejbc syntax

Required changes for EJB 1.1 compliance

Updates for EJB classes and interfaces

General EJB updates

Entity EJB Updates

EJBs using the UserTransaction interface

Deprecated methods from javax.ejb.EJBContext

Updates for EJB Clients

Accessing EJBs

Removing session beans

This section provides an overview of new features and changes introduced in the WebLogic Server Version 5.1 Enterprise JavaBeans implementation.

WebLogic Server Version 5.1 is compliant with the JavaSoft EJB 1.1 specification. The WebLogic Server EJB documentation describes key features of the EJB 1.1 specification that you need to understand in order to use WebLogic Server. However, you should also read the JavaSoft EJB 1.1 specification to familiarize yourself with basic EJB development practices.

See Required changes for EJB 1.1 compliance for a summary of EJB 1.1 changes that may require updates to your EJB classes, interfaces, and client applications.

WebLogic Server includes the new DeployerTool utility, which provides a graphical interface for EJB Application Assemblers. DeployerTool provides an easy way to map new EJB 1.1 application roles, resource references, and EJB references to actual objects available in running servers. DeployerTool also simplifies the process of configuring multiple EJB deployment units and deploying them to one or more WebLogic Servers.

See Deploying EJBs with DeployerTool for complete instructions on using DeployerTool.

The new DDConverter utility provides a quick and easy way to upgrade earlier WebLogic Server EJB deployment descriptors to WebLogic Server Version 5.1. DDConverter takes an existing WebLogic Server text description file and generates the ejb-jar.xml and weblogic-ejb-jar.xml files required for deploying to Version 5.1. DDConverter also automatically generates a weblogic-cmp-rdbms-jar.xml deployment file for entity EJBs that use WebLogic RDBMS-based persistence services.

See Upgrading EJBs to WebLogic Server Version 5.1 for complete instructions on using DeployerTool and upgrading earlier deployment units.

EJBs now access all environment properties using JNDI. To set up environment properties using DeployerTool, see Adding, removing, and changing environment entries. See EJB field-mapping elements for information about how environment entries are defined in the weblogic-ejb-jar.xml deployment file.

WebLogic Server introduces several changes and additions to resource factory support in Version 5.1:

• JDBC connection pools can now be accessed using the javax.sql.datasource resource factory

• New resource factory support is provided for:

  • URL connections

  • Java mail session factories are supported

  • JMS connections

See Resource Factories in The WebLogic Server EJB Container for information on setting up JDBC, URL, and Java mail session resources.

WebLogic Server supports home handles for entity and session EJBs. Using home handles, a client can store a reference to an EJB home over long periods of time, re-creating the reference as needed, without referring to the bean's home name in a JNDI context. See Storing EJB references in home handles for more information.

WebLogic Server Version 5.1 contains a new deployment descriptor that provides increased manageability for the stateless session EJB free pool. Using initial-beans-in-free-pool, deployers can populate the free pool with EJB instances at startup; startup classes are no longer required to create an initial pool of bean instances. Deployers can also enforce hard limits for the number of EJB instances that reside in the free pool by using max-beans-in-free-pool.

Also, WebLogic Server no longer uses the free pool to store instances of stateful session EJBs. See Caching properties for more information.

In WebLogic Server Version 5.1, EJB deployers can easily set up multiple container-managed persistence types for development or testing. The persistence type an EJB actually uses is controlled at deployment time using the persistence-use element. See Persistence Services for more information.

WebLogic Server provides support for embedding Java expressions within WLQL expressions. This enables the EJB developer or EJB deployer to create advanced finder methods for entity EJBs using container-managed persistence. See Using WebLogic Server RDBMS Persistence for more information.

EJB providers can now use is-modified-method-name with bean-managed entity EJBs as well as container-managed EJBs. See Using is-modified-method-name to limit calls to ejbStore() for more information.

EJB providers using JDK 1.2 can now use the java.util.Collection interface to define the collection type for finders that return multiple entity objects. java.util.Enumeration is also supported for users of either JDK 1.1 or JDK 1.2.

See Persistence Services for more information on writing finder methods for WebLogic Server RDBMS-based persistence.

Many of the changes in the WebLogic Server Version 5.1 EJB implementation affect EJB deployment. Both the input files and the tools used to deploy EJBs have changed.

With the EJB 1.1 specification, the javax.ejb.deployment classes are not required. WebLogic Server no longer includes the javax.ejb.deployment package.

If the EJB provider does not specify a transaction attribute in the ejb-jar.xml file, WebLogic Server uses Supports by default. See Setting method transaction attributes for more information.

Text deployment descriptions and their associated .ser files are no longer used to deploy EJBs in WebLogic Server Version 5.1. The EJB 1.1 specification requires the EJB provider to define common EJB properties in an XML file named ejb-jar.xml. This XML file must conform to the DTD provided by JavaSoft in the EJB 1.1 specification.

WebLogic Server Version 5.1 introduces two XML files in addition to the ejb-jar.xml file required by Sun:

• weblogic-ejb-jar.xml specifies deployment properties required for deploying EJBs in WebLogic Server. For example, weblogic-ejb-jar.xml defines timeout, pooling, and clustering behavior for EJBs.

• weblogic-cmp-rdbms-jar.xml defines properties for EJBs that use native WebLogic RDBMS-based persistence services. Other persistence services, such as those provided by an outside vendor such as TOPLINK, may provide different deployment files. Contact your persistence vendor for more information.

Text descriptor to XML element mapping

Tables in this section list the deployment properties used in prior WebLogic Server versions, and show the new XML file locations and associated XML elements that replace those properties.

See XML deployment properties for detailed information on the WebLogic Server XML files and their DTDs. See the JavaSoft EJB 1.1 specification for information about the ejb-jar.xml file.

The following deployment properties are now located in the ejb-jar.xml file:

Old text property	XML element in ejb-jar.xml
accessControlEntries	Role names are converted to role-name elements in the security-role stanzas. See Mapping application roles to WebLogic Server principals to define security roles using DeployerTool. Role assignments are converted to equivalent elements in the method-permission stanzas. See Assigning method permissions for more information.
containerManagedFields	cmp-field (See Configuring container-managed fields)
enterpriseBeanClassName	ejb-class (See Setting EJB class properties)
EntityDescriptor	entity
environmentProperties	env-entry (See Adding, removing, and changing environment entries)
homeInterfaceClassName	home (See Setting EJB class properties)
isReentrant	reentrant (See Setting EJB class properties)
primaryKeyClassName	prim-key-class (See Primary key changes for container-managed EJBs)
remoteInterfaceClassName	remote (See Setting EJB class properties)
SessionDescriptor	session
stateManagementType	session-type
transactionAttribute	trans-attribute (See Setting method transaction attributes)

The following properties are now located in weblogic-ejb-jar.xml:

Old text property	XML element in weblogic-ejb-jar.xml
beanHomeName	jndi-name
clusterProperties	clustering-descriptor
dbIsShared	db-is-shared
delayUpdatesUntilEndOfTx	delay-updates-until-end-of-tx
homeCallRouterClassName	home-call-router-class-name
homeIsClusterable	home-is-clusterable
homeLoadAlgorithm	home-load-algorithm
idleTimeoutSeconds	idle-timeout-seconds
isModifiedMethodName	is-modified-method-name
maxBeansInFreePool	max-beans-in-free-pool
maxBeansInCache	max-beans-in-cache
persistentStoreType	persistence-type, persistence-use
sessionTimeout	trans-timeout-seconds
statelessBeanCallRouter ClassName	stateless-bean-call-router-class-name
statelessBeanIs Clusterable	stateless-bean-is-clusterable
statelessBeanLoad Algorithm	stateless-bean-load-algorithm
statelessBeanMethodsAre Idempotent	stateless-bean-methods-are-idempotent

Properties in the following table are now located in weblogic-cmp-rdbms-jar.xml.

Note: weblogic-cmp-rdbms-jar.xml is generated only for container-managed entity EJBs that use WebLogic RDBMS-based persistence services

Old text property	XML element in weblogic-cmp-rdbms-jar.xml
attributeMap	attribute-map
finderDescriptors	finder-list
isolationLevel	transaction-isolation
poolName	pool-name
tableName	table-name

The following text deployment parameters are no longer used. When you upgrade your existing WebLogic Server deployment file, the DDConverter utility removes these properties:

Obsolete text property	Explanation
ejbObjectClassName	Custom EJBhome and EJBobject implementation classes are no longer supported.
homeClassName	Custom EJBhome and EJBobject implementation classes are no longer supported.
runAsIdentity	Replaced by application role mechanisms in ejb-jar.xml and weblogic-ejb-jar.xml. See Mapping application roles to WebLogic Server principals for more information.
runAsMode	Replaced by application role mechanisms in ejb-jar.xml and weblogic-ejb-jar.xml. See Mapping application roles to WebLogic Server principals for more information.

Java archive (.jar) files replace serialized deployment descriptors as the unit of deployment for EJBs in WebLogic Server. EJB tools such as ejbc and DeployerTool take .jar files as their input, and save modified XML deployment descriptors and container classes in .jar files. See Upgrading EJBs to WebLogic Server Version 5.1 for information about packaging EJB files into a .jar.

You can also deploy EJBs with the weblogic.deploy utility or weblogic.properties file by using an EJB deployment directory. The files and subdirectories contained in the deployment directory must observe the same restrictions as files and subdirectories stored in a .jar file. See Deploying EJBs in WebLogic Server for more information.

The following EJB deployment utilities are no longer supported with WebLogic Server Version 5.1:

• DDCreator

• EJB Deployment Wizard

The DeployerTool utility replaces the EJB Deployment Wizard as the tool for configuring and deploying EJBs.

WebLogic Server Version 5.1 does not provide a DDCreator utility to generate new ejb-jar.xml deployment files. However, you can use DDConverter with an earlier WebLogic Server text deployment description to generate a valid ejb-jar.xml file. In addition, the DeployerTool utility automatically generates the weblogic-ejb-jar.xml and weblogic-cmp-rdbms-jar.xml files as required for deploying to WebLogic Server Version 5.1.

Note: If you are an EJB provider and you need to create a new ejb-jar.xml file from scratch, see the JavaSoft EJB 1.1 specification for instructions.

WebLogic Server no longer supports file-based persistence services. If you have EJBs that use file-based persistence services, you can re-write them to use the CloudScape database included with WebLogic Server. CloudScape provides better performance than the older file-based persistence services, as well as standard RDBMS functionality.

WebLogic Server's native persistence services (previously called JDBC-based container-managed persistence) have been renamed to RDBMS-based persistence services in Version 5.1. The new package name is weblogic.cmp.rdbms, and the associated classes are packaged in /weblogic/lib/persistence/WebLogic_RDBMS.jar.

WebLogic Server Version 5.1 does not support the WLQL orderBy operator. EJB deployers should no longer use this operator in finder methods.

With previous WebLogic Server versions, bean providers were required to wrap primary key fields in a user-defined primary key class. This was required even for single-field primary keys that mapped to a primitive Java object.

For example, if a primary key field existed in the underlying data store as a string object, the bean provider still had to create a user-defined primary key class such as:

public class AccountPK implements java.io.Serializable {
  public String accountId;
}

The 1.0-compliant deployment descriptor then referenced the user-defined class using:

primaryKeyClassName examples.ejb.basic.containerManaged.AccountPK

With the EJB 1.1 specification, primary keys are defined as either simple or compound keys. Simple keys use a single field in the underlying datastore as a primary key, while compound keys use multiple fields.

For simple primary keys, the bean provider does not need to wrap the field in a user-defined primary key class. This type of simple key is defined in the ejb-jar.xml deployment file using only the field name and the associated Java object:

<entity>

  ...

  <prim-key-class>java.lang.String</prim-key-class>

  ...

  <primkey-field>accountId</primkey-field>

  ...

Note: Primary keys that map to a single primitive type, such as int, still require a primary key class wrapper. Define these primary keys as compound primary keys.

Compound primary keys still rely on the bean provider to create a user-defined primary key class. Compound primary keys are defined in ejb-jar.xml by specifying only the user-defined class:

<entity>
  ...
  <prim-key-class>
  examples.ejb.basic.containerManaged.AccountPK
  </prim-key-class>
  ...

Note: For both simple and compound primary keys, the bean provider must set up primary key fields as container-managed fields in ejb-jar.xml.

WebLogic Server no longer rolls back a transaction when an EJB throws an application exception. The WebLogic Server container only rolls back a transaction in response to the EJB calling setRollbackOnly().

If an EJB throws a non-application exception, WebLogic Server rolls back the transaction and discards the EJB instance, as required by the EJB 1.1 specification.

The Version 5.1 ejbc utility provides changed command-line options and a new syntax for specifying source and destination .jar files for EJB deployment units. Furthermore, you can no longer use a serialized deployment descriptor (.ser file) as an input to ejbc. See ejbc for a complete reference to the new ejbc syntax.

The following sections provide a summary of changes in the JavaSoft EJB 1.1 specification that may require updates to existing EJB classes and interfaces. These changes apply to all EJBs based on the 1.0 specification, whether they were previously deployed in WebLogic Server or in another application server.

For more information about these changes, see the EJB 1.1 specification.

Note: The ejbc compiler included with WebLogic Server Version 5.1 automatically checks your EJB source code for compliance with many of these changes. Review this section to address known changes before using ejbc.

The EJB 1.1 specification places new requirements on EJB class declarations, and on methods defined in the EJB's class and remote interface. Check your classes and interfaces to ensure that they meet the following requirements:

• All EJB classes must be declared public, and cannot be declared as final or abstract.

• EJB classes must include a public constructor that takes no parameters. WebLogic Server uses this constructor to create new instances of the EJB.

• EJB classes must define at least one ejbCreate() method that is declared public, and not final or static.

  The ejbCreate() method can throw a RuntimeException, javax.ejb.EJBException, or CreateException. The EJB implementation of ejbCreate() must not throw java.rmi.RemoteException, as this is deprecated in the EJB 1.1 specification.

  Note: Although the EJB implementation of ejbCreate() must not throw java.rmi.RemoteException, the EJB's home interface must declare that create() throws this exception. In EJB 1.1, only the container or server may throw a RemoteException.

• Business methods declared in session or entity EJBs must not be declared final or static.

• Business methods and WebLogic Server-invoked callback methods, such as ejbCreate() and ejbPostCreate(), should not throw java.rmi.RemoteException. Throwing java.rmi.RemoteException from these methods is deprecated in the EJB 1.1 specification. Business methods and callbacks can throw either a RuntimeException or javax.ejb.EJBException.

EJBContext.getEnvironment() Deprecated

WebLogic Server Version 5.1 no longer supports the use of getEnvironment() for accessing EJB environment properties. All EJB clients must obtain environment properties by accessing an environment naming context.

Note: The javac compiler displays deprecation warnings if you compile EJB code that uses the getEnvironment() method.

When you upgrade your EJB 1.0 deployment descriptors, the DDConverter utility places the environment entries in an EJB 1.1-compliant environment context using the env-entry element in ejb-jar.xml. You must update your EJB code to access the new entries.

The following excerpt shows two methods from the TraderBean example EJB that was included with earlier versions of WebLogic Server. This EJB loads environment properties in setSessionContext, using the getEnvironment() method. The value of the tradeLimit property is then accessed in getTradeLimit:

...

private transient SessionContext ctx;

private transient Properties     props;

...

public void setSessionContext(SessionContext ctx) {

this.ctx = ctx;

    props    = ctx.getEnvironment();

} 

...

private int getTradeLimit() {

    return Integer.parseInt((String)props.get("tradeLimit"));

} 

...

The revised version of TraderBean included with WebLogic Server Version 5.1 performs the same steps by accessing a WebLogic JNDI context. Here, the context for the EJB is set up and the tradeLimit property is obtained in the ejbCreate method:

...

private SessionContext ctx;

private int tradeLimit;

...

public void setSessionContext(SessionContext ctx) {

   log("setSessionContext called");

   this.ctx = ctx;

}

...

public void ejbCreate () throws CreateException {

   log("ejbCreate called");

   try {

     InitialContext ic = new InitialContext();

     Integer tl = (Integer) ic.lookup("java:/comp/env/tradeLimit");

     tradeLimit = tl.intValue();

   } catch (NamingException ne) {

     throw new CreateException("Failed to find environment value "+ne);

   }

}

...

Check 1.0-compliant entity EJB classes and their primary key classes to ensure that they meet the following EJB 1.1 requirements:

• Entity EJB classes must define a matching ejbPostCreate() method for each corresponding ejbCreate() method. Like ejbCreate(), ejbPostCreate() must be declared public, and not final or static.

  ejbPostCreate() can throw a RuntimeException or javax.ejb.EJBException, but should not throw java.rmi.RemoteException. Throwing java.rmi.RemoteException is deprecated in the EJB 1.1 specification.

• An entity EJB's primary key class must implement the hashCode() and equals(Object) methods.

• All finder methods for an entity EJB must throw FinderException.

  Finder methods should not throw java.rmi.RemoteException, as this is deprecated in the EJB 1.1 specification. Finder methods can throw a RuntimeException or javax.ejb.EJBException in addition to the required FinderException.

EJBs using the UserTransaction interface

The package name for javax.jts has changed to javax.transaction. If existing EJBs use the javax.jts.UserTransaction interface, change those references to use javax.transaction.UserTransaction.

Refer to the JavaSoft documentation on javax.transaction.UserTransaction for additional details about the exceptions thrown in the revised interface.

The EJB 1.1 specification also restricts the use of javax.transaction.UserTransaction to session EJBs; entity EJBs cannot use the UserTransaction interface. Also, a session EJB cannot use both the javax.transaction.UserTransaction and SessionSynchronization interfaces at the same time.

You can no longer use the getEnvironment() method from the javax.ejb.EJBContext interface, as specified in the EJB 1.1 specification.

The EJB 1.1 specification also deprecates getCallerIdentity() and isCallerInRole(Identity). However WebLogic Server Version 5.1 still supports these methods.

See the JavaSoft documentation for javax.ejb.EJBContext for additional information.

The 1.1 EJB specification makes several changes to the way EJB clients can invoke and remove EJBs. Use the information in the following sections to update existing EJB clients as necessary.

For more information on these changes, see the EJB 1.1 specification. See also Invoking deployed EJBs for general information about accessing EJBs in client code.

Check existing EJB clients to ensure that they observe the EJB access restrictions described in the following sections.

The 1.1 specification requires that client code use javax.rmi.PortableRemoteObject.narrow() to convert the result of getEJBObject() before casting the result to the remote interface type. Using javax.rmi.PortableRemoteObject.narrow() ensures that the code is portable among different EJB containers.

WebLogic Server Version 5.1 supports the use of javax.rmi.PortableRemoteObject.narrow(). However, the narrow() method is not required except when using RMI-IIOP. When RMI-IIOP is not required, client code can use either the narrow() method or standard Java casting conventions to cast the result of getEJBObject().

The EJB implementation in WebLogic Server Version 5.1 enforces strict serialization of method calls to session bean instances. Clients to session EJBs cannot make concurrent method calls to the same instance of the bean. If more than one client attempts to access the same method in the same bean instance, WebLogic Server throws a java.rmi.RemoteException.

Check existing EJB clients ensure that they observe the following restrictions to removing session EJBs.

Stateful session beans cannot be removed when an instance of the EJB is participating in a transaction. If a client attempts to remove a bean involved in a transaction, WebLogic Server throws a java.rmi.RemoteException.

Prior versions of the WebLogic Server documentation indicated that session EJBs used an "implicit" primary key. However, session beans do not have an actual primary key, and clients cannot use javax.ejb.EJBHome.remove(primaryKey) to remove them. Instead, use remove() to remove the current EJB instance or remove(Handle) to remove a specific instance.