Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy
BEA WebLogic Server Enterprise JavaBeans 1.1: Previous topic | Next topic | Contents

EJB Features and Changes in WebLogic Server Version 5.1

Overview

New Features

EJB 1.1 compliance

Application assembly support in EJB Deployer

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

BLOB and CLOB DBMS columns

Entity EJB changes

Primary key changes for container-managed EJBs

Simple and compound primary keys

EJB exception changes(12.6)

New ejbc syntax

Required changes for EJB 1.1 compliance

Updates for EJB classes and interfaces

General EJB updates (6.10)

Entity EJB Updates

EJBs using the UserTransaction interface

Deprecated methods from javax.ejb.EJBContext

Updates for EJB Clients

Accessing EJBs

Removing session beans

Overview

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

New Features

EJB 1.1 compliance

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.

Application assembly support in EJB Deployer

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

See Deploying EJBs with EJB Deployer for complete instructions on using EJB Deployer.

DDConverter upgrade utility

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 EJB Deployer and upgrading earlier deployment units.

Full JNDI support for EJB environment

EJBs now access all environment properties using JNDI. To set up environment properties using EJB Deployer, 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.

New resource factory support

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.

Support for EJB home handles

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.

Improved free pool management

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.

Improved manageability for multiple persistence types

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 Query Language (WLQL) supports embedded Java

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.

Note: Future versions of the WebLogic Server EJB container will use the EJB QL query language (as required by the EJB 2.0 specification). EJB QL does not provide support for embedded Java expressions. Therefore, to ensure easier upgrades to future EJB containers, create entity EJB finders without embedding Java expressions in WLQL.

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

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.

New Java type support for multi-object finders

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.

Changed behavior

EJB deployment

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.

javax.ejb.deployment classes not used

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

Default transaction properties

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.

XML deployment descriptors

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 EJB Deployer. 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 Note: idle-timeout-seconds no longer determines an EJB's passivation time (as it did in previous WebLogic Server releases). See Stateful EJB lifecycle for information about how idle-timeout-seconds functions in WebLogic Server Version 5.1.
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

Deleted deployment properties

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.

.jar and directory deployment units

Java archive (.jar) files replace serialized deployment descriptors as the unit of deployment for EJBs in WebLogic Server. EJB tools such as ejbc and EJB Deployer 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.

Unsupported deployment utilities

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

- DDCreator

- EJB Deployment Wizard

The EJB Deployer 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 EJB Deployer 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.

Persistence Services

File-based persistence not supported

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.

JDBC-based persistence renamed to RDBMS-based persistence

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.

BLOB and CLOB DBMS columns

WebLogic Server cannot support BLOB and CLOB DBMS columns with EJB CMP at this time, until JDBC defines a standard UPDATE mechanism for BLOBs and CLOBs. The small BLOB/CLOB is accessible by JDBC1.x getX/setX methods. However, if the column exceed a certain size (usually 4k), the DBMS will shift to normal BLOB/CLOB semantics which are not supported in CMP.

To work around this, your choices are:

- using BMP with JDBC-specific driver code for UPDATEs

- using CMP with LONG RAW/LONG columns

Entity EJB changes

Primary key changes for container-managed EJBs

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

Simple and compound primary keys

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.

EJB exception changes

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.

New ejbc syntax

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.

Required changes for EJB 1.1 compliance

Updates for EJB classes and interfaces

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.

General EJB updates

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);

       }

    }

    ...

Entity EJB Updates

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.

Deprecated methods from javax.ejb.EJBContext

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.

Updates for EJB Clients

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.

Accessing EJBs

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

Casting the result of getEjbObject() in client code

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().

Concurrent calls to a session EJB instance prohibited

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.

Removing session beans

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

ejbRemove() restriction for stateful beans

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.

remove(primaryKey) not permitted

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.

Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.