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

WebLogic Server deployment files

Roles and responsibilities

Deployer projects

Developer projects

Requirements

.jar file

WebLogic Servers

Getting started

DeployerTool basics

Menu bar

Tool bar

Object panel

Top-level categories

Edit panel

Message panel

Starting DeployerTool

Setting up DeployerTool servers and preferences

Editing WebLogic Server connections

Changing DeployerTool preferences

Working with EJB deployment units

Loading a .jar file

Viewing the contents of a .jar

Setting .jar file display properties

Creating a new .jar file

Configuring basic EJB properties

Setting EJB class properties

Setting method transaction attributes

Assigning method permissions

Default method permissions in WebLogic Server

Changing method permissions

Adding, removing, and changing environment entries

Configuring WebLogic Server deployment properties

Setting cache and performance properties

Setting clustering properties

Mapping EJB references

Mapping application roles to WebLogic Server principals

Mapping EJB references

Mapping resource factory references

Configuring persistence properties for entity EJBs

Configuring container-managed fields

Configuring WebLogic Server RDBMS-based persistence

Specifying the table and connection for RDBMS operations

Mapping container-managed fields to database columns

Editing EJB finder method expressions

Validating deployment units

Validating deployment properties

Checking for compliance with EJB 1.1

Compiling and deploying EJBs

Compiling EJB container classes

Deploying .jar files to WebLogic Server

The WebLogic Server DeployerTool provides a graphical interface that Application Assemblers can use to deploy EJBs to one or more WebLogic Servers. DeployerTool simplifies the process of configuring EJB deployment properties and mapping EJB references to actual resource factories, roles and other EJBs available on a server.

DeployerTool provides many services related to EJB deployment. You can use it to:

• Examine all EJBs in a .jar file and change their WebLogic Server deployment properties

• Validate EJB interfaces and classes to ensure that they are compliant with the EJB 1.1 specification

• Map EJB references, resource references, and security roles to actual EJBs, resource factories, and roles available in a WebLogic Server

• Generate WebLogic Server EJB implementation classes

• Deploy EJBs to one or more servers

For general information about deploying EJBs on WebLogic Server, or for information on using hot deployment features, see Deploying EJBs in WebLogic Server.

When you modify deployment properties with DeployerTool, the utility updates and saves information in the XML deployment files, ensuring that the XML is correct for its associated DTD. DeployerTool can modify certain properties in ejb-jar.xml. It can also create the weblogic-ejb-jar.xml and weblogic-cmp-rdbms-jar.xml files if they are not available in the .jar.

weblogic-ejb-jar.xml contains properties that define the caching, clustering, and performance behavior of EJBs. It also contains properties that map available WebLogic Server resources to EJBs. WebLogic Server resources include security role names, data sources such as JDBC pools and JMS connection factories, other deployed EJBs, and container-managed persistence services available in the server.

Properties in weblogic-ejb-jar.xml are linked to EJB names in ejb-jar.xml, resource names in a running WebLogic Server, and to persistence type data defined in weblogic-cmp-rdbms-jar.xml (for entity EJBs using RDBMS persistence). This figure shows the relationship among these components:

See XML deployment properties if you want to edit the XML deployment files manually, outside of the DeployerTool utility.

DeployerTool is designed primarily for:

• Deployers who are configuring EJBs to run in the WebLogic Server container

• Application Assemblers who are linking multiple EJBs and EJB resources to create larger web application systems

• EJB developers who are creating and configuring new EJB .jar files

To satisfy the requirements of these roles, DeployerTool provides complete controls for managing multiple EJB .jar files and WebLogic Servers, and for configuring WebLogic Server deployment properties and resources. Roles are designated by two primary types of DeployerTool projects: deployer projects and developer projects.

Deployer projects enable EJB deployers and application assemblers to configure EJB deployment properties and deploy EJB .jar files to WebLogic Server. Using deployer, you can automatically create the required weblogic-ejb-jar.xml file with valid deployment properties, and you can attach EJB and resource factory references to actual resources in a running server. Deployer projects enable you to work with EJB .jar files without knowing the details of the EJB code.

If you open a .jar file and find that you cannot edit all of the deployment parameters you want to, try opening the file as a developer project.

Developer projects provide all the capabilities of a deployer project. Developer projects also enable you to modify EJB deployment properties that may require some knowledge of the EJB implementation code.

Note: Although a developer project enables you to configure some basic properties defined in the ejb-jar.xml deployment file, it is the responsibility of the Bean Provider to create this file and package it with the compiled EJB classes and interfaces. WebLogic Server provides the DDConverter utility to generate an ejb-jar.xml file from an existing WebLogic Server-compatible text descriptor. See Upgrading EJBs to WebLogic Server Version 5.1 for more information.

To use DeployerTool, you must have:

• a .jar file containing the EJB deployment unit

• one or more running WebLogic Servers

.jar file

An EJB deployment unit in DeployerTool consists of a Java archive (.jar) file. The .jar file must contain all of the compiled classes for your EJB home interface, remote interface, and implementation class. It must also have a META-INF subdirectory that contains, at minimum, a valid ejb-jar.xml deployment file. The .jar file may contain classes and deployment descriptors for one or more distinct EJBs.

Note: You do not need to include a MANIFEST file in the .jar file, as was required with the EJB 1.0 specification. See the JavaSoft EJB 1.1 specification for more information.

Optionally, the .jar file can contain the weblogic-ejb-jar.xml and weblogic-cmp-rdbms-jar.xml files, which define deployment properties for WebLogic Server and WebLogic RDBMS-based persistence services. If the .jar does not contain these files, DeployerTool creates them as necessary during the deployment process.

The following shows the contents of a simple .jar file that can be loaded into DeployerTool:

$ jar tf ejb_basic_beanManaged.jar

META-INF/

META-INF/MANIFEST.MF

examples/ejb/basic/beanManaged/

examples/ejb/basic/beanManaged/Account.class

examples/ejb/basic/beanManaged/AccountBean.class

examples/ejb/basic/beanManaged/AccountHome.class

examples/ejb/basic/beanManaged/AccountPK.class

examples/ejb/basic/beanManaged/ProcessingErrorException.class

META-INF/ejb-jar.xml

META-INF/weblogic-ejb-jar.xml

Note: Classes in the .jar file must reside in directories that match their Java package hierarchy. See Step 2: Package EJB Classes and Interfaces in Upgrading EJBs to WebLogic Server Version 5.1 for more information.

DeployerTool connects to one or more servers during the deployment process, enabling you to map references in the deployment description files to actual WebLogic Server resources.

For each WebLogic Server you want to use, make sure you have:

• the host name of the machine running the server

• the WebLogic Server listen port number

• a valid system password for the server

Getting started

To begin using DeployerTool:

1. Read DeployerTool basics to learn how to work with the DeployerTool user interface.

2. Start DeployerTool using the instructions in Starting DeployerTool

3. Set up a new WebLogic Server profile using the instructions in Setting up DeployerTool servers and preferences.

4. Load the .jar file you want to deploy using the instructions in Working with EJB deployment units.

5. Read additional sections as necessary for:

   • Configuring WebLogic Server deployment properties

   • Mapping EJB references

   • Validating deployment units

6. Deploy the .jar file to WebLogic Server using the instructions in Compiling and deploying EJBs.

The DeployerTool program window is divided into the following main components:

• Menu bar

• Tool bar

• Object panel

• Edit panel

• Message panel

The figure below illustrates these components:

The menu bar contains several menus for:

• opening, creating, and saving .jar files

• editing DeployerTool preferences and deploying EJBs

• getting help for DeployerTool

Tool bar

Icons in the tool bar provide quick access to selected DeployerTool menu options. Hold your cursor over an individual icon to learn its function.

The object panel provides a hierarchical view of the .jar files, EJBs, and EJB properties you have opened. Clicking the + symbol next to an object expands the object, listing the nested objects or properties it contains. Clicking the - symbol collapses the object, hiding its nested properties.

Clicking directly on an object or property name displays its details and editable fields in the edit panel, described below.

The top-level categories in the object panel represent DeployerTool Projects and Servers. DeployerTool Projects can contain Deployer projects or Developer projects. Developer projects allow you to configure properties that require some knowledge of the EJB code. Deployer projects allow EJB deployers or application assemblers to deploy EJBs on WebLogic Server without knowing the details of the EJB code.

The Servers category lists all WebLogic Servers to which DeployerTool can connect and deploy. See Setting up DeployerTool servers and preferences for information on configuring servers.

The edit panel displays detailed information about the selected .jar, EJB, or EJB property, and allows you to edit certain property fields. The contents of the edit panel differs depending on the object or property you have selected in the object panel. For example, if you click on a .jar file name in the object panel, the edit panel shows display characteristics for the .jar file. If you expand the .jar file and select the Security object, the edit panel displays the file's application role definitions.

Many, but not all, of the fields displayed in the edit panel can be modified. To modify the contents of a field, you can either:

• click on the field and type in a new value,

• click on the field and select an appropriate value from a drop-down list, or

• double-click on the field to bring up a dialog box with editable fields

The sections that follow provide details about how to edit fields to perform EJB configuration tasks.

The message panel displays informational and error messages as you perform tasks in DeployerTool. The message panel has three separate displays, indicated by the tabs at the bottom of the panel: Messages, Problems, and Console.

The Messages display (active by default) shows current progress and error messages for the task you are performing. For example, when you check EJB classes for compliance with the EJB1.1 specification, DeployerTool displays any non-compliance messages in the Messages display.

The Problems display lists deployment errors for the object you have selected in the object panel. If you select a .jar file in the Object panel, the Problems display lists all errors associated with deployment properties in the .jar. If you select a single EJB in the object panel, only the errors for that bean are displayed.

Deployment property errors can occur because of undefined or incorrectly defined deployment values. The text of each error message indicates the field to enter or modify in order to correct the error. See Validating deployment properties for more information about addressing deployment errors.

The Console display lists any DeployerTool or Java errors that would normally appear in the command shell you used to start DeployerTool.

To start DeployerTool, first use the setEnv.cmd or setEnv.sh script to set your environment for WebLogic Server Version 5.1:

% setenv

Use the following command to start DeployerTool:

% java -ms24m -mx24m weblogic.EJBDeployerTool

If you installed WebLogic Server under Windows NT, you can also start DeployerTool using the Start menu.

DeployerTool loads and displays an empty program window:

DeployerTool enables you to connect and deploy to one or more WebLogic Server products. DeployerTool manages multiple servers in the Servers category of the object panel; each server entry defines the connection properties for a particular WebLogic Server. You must configure at least one new server to begin deploying EJBs.

You can optionally configure DeployerTool and ejbc options to customize the behavior and appearance of the utility, as described in Changing DeployerTool preferences.

To create, modify, or delete a DeployerTool Server entry:

1. Start DeployerTool using the instructions in Starting DeployerTool.

2. Select the Servers category in the object panel.

3. Click the Add button in the edit panel. DeployerTool creates a blank server entry in the edit panel:

4. Fill in the fields of the new server entry as follows:

   • Name: Enter the name to use for this WebLogic Server within DeployerTool.

   • Protocol: Select the protocol to use for connecting to the WebLogic Server

   • Host: Enter the host name of the machine on which the WebLogic Server is running.

   • Listen port: Enter the WebLogic Server listen port for this server.

   • System password: Enter a valid password for the server's System account.

   • Default: Select this box to have DeployerTool use this server as the default for deployment.

5. To modify an existing server profile, expand the Server category in the object panel, and click on the name of the server entry to modify. Then edit the server entry fields as necessary.

6. To delete an existing server profile, expand the Server category in the object panel and click the name of the server entry to delete. Click the Remove button.

You can modify DeployerTool preferences to specify the Java compiler that ejbc uses during compilation. DeployerTool preferences also affect the location of temporary files and the window size and location for the utility.

To change DeployerTool preferences:

1. Start DeployerTool using the instructions in Starting DeployerTool.

2. Select Tools->Preferences... to display the WebLogic EJB Deployer Properties dialog:

3. To change DeployerTool environment preferences, click on the environment category and edit the properties as follows:

   • saveWindowLocations: Select true to maintain the same size and position of DeployerTool windows through multiple sessions. saveWindowLocations also determines whether DeployerTool re-loads the current .jar files the next time it starts.

   • tmpdir: Enter the directory in which DeployerTool stores temporary files, or click Choose... to select the directory.

   • home: Enter the home directory in which DeployerTool stores preference information or click Choose... to select the directory. This directory is also the initial directory that DeployerTool looks in when you open a new .jar file.

4. To change ejbc compiler options, click on the ejbc category and edit the properties as follows:

   • compiler: Enter the full path of the Java compiler to use with ejbc, or click Choose... to select a compiler. By default, ejbc uses javac as a compiler. For faster performance, specify a different compiler, such as Symantec's sj.

   • keepgenerated: Select true to save the intermediate Java files that ejbc creates during compilation, or false to discard them.

5. Click OK to save the current options.

This section provides basic instructions for:

• loading an EJB deployment unit into DeployerTool

• using DeployerTool controls to:

  • view and change .jar file properties

  • view and change EJB properties

Loading a .jar file

DeployerTool can import multiple EJB .jar files for editing or deploying to servers.

Note: Before importing a .jar file, make sure the file meets the requirements described in .jar file.

To load a .jar deployment unit:

1. Start DeployerTool using the instructions in Starting DeployerTool.

2. Select File->Open...

3. Type in the complete path to the .jar file you want to import, or navigate to select the file.

4. Click Open to open the selected .jar file. DeployerTool places the new .jar file in the Deployer category:

Once you have loaded a .jar file, follow these steps to view the file's contents:

1. Expand the .jar file contents by clicking the + sign next to its filename in the object panel.

2. Select the Files item to display details about the class files the .jar contains:

   Columns in the Files display show the name, date modified, size, and relative directory of class files and XML deployment files contained in the .jar. You cannot edit the information stored in these columns.

Once you have loaded a .jar file, follow these steps to edit the file's display name or description within DeployerTool:

1. Select the name of the .jar file in the object panel to display basic file properties:

2. Edit fields in the edit panel as necessary:

   • Source JAR file: This field lists the full path and filename of the .jar file. You cannot modify this entry.

   • Display name: Enter the name DeployerTool uses to represent this .jar in the object panel.

   • Small icon file: If your .jar file contains icon files, use the drop-down list to select the small icon file to use for display within DeployerTool.

   • Large icon file: If your .jar file contains icon files, use the drop-down list to select the large icon file to use for display within DeployerTool.

   • Client JAR file: Enter the name of a client .jar file.

   • Description: Enter text to describe the contents of this .jar file.

DeployerTool can help you create a new EJB .jar file from scratch, if you have not yet created one using the jar tool included in your JDK. To create a new .jar file from scratch:

1. Select File->New... to open the New Jar File dialog:

2. Type in the full path and filename of the new .jar file to create, or use the Select path... button to navigate to an existing location.

3. Click Finish when you have specified the new .jar file. DeployerTool adds an entry for the new .jar file to the Developer category.

4. Select the name of the new .jar file in the object panel.

5. Select Project->Edit file set... to begin adding files to the .jar. DeployerTool displays the Add or remove project files dialog:

6. Click the Add files... button to select the class files and XML deployment files to add. Navigate to the individual directories or files you want to add, and click OK.

   Note: If you select a directory, DeployerTool adds all subdirectories and files the directory contains. This helps to preserve the package structure of EJB class files within the new .jar.

7. Return to step 6 and continue adding files to the .jar as necessary. Click OK when you are finished.

8. The contents of the new .jar file must observe the requirements described in .jar file. If you need to modify any of the basic EJB properties, follow the steps below in Setting EJB class properties.

The following sections explain how to change basic EJB class and method properties. The deployment properties described in this section are all part of the ejb-jar.xml file defined in the JavaSoft EJB 1.1 specification.

Follow these steps to view or change the basic home, remote, and EJB class information in an EJB deployment unit:

1. Start DeployerTool and load the EJB .jar file if you have not already done so. See Starting DeployerTool and Loading a .jar file if you need instructions.

2. Select the + sign next to the .jar file name to display its contents.

3. Select the + sign next to the Beans object to display available EJBs in the .jar file.

4. Select the name of the EJB you want to view or modify. DeployerTool shows the EJB display name and icon files (if applicable) in the edit panel.

5. Select the Classes tab in the edit panel to display basic EJB class information:

6. To edit basic EJB class information, click the desired field in the edit panel and type the new value. Editable values include:

   • Bean class: Enter the class name of the EJB implementation class.

   • Home interface class: Enter the class name of the EJB's home interface class.

   • Remote interface class: Enter the class name of the EJB's remote interface class.

     Note: Classes and interfaces in the .jar file must reside in directories that match their Java package hierarchy. See Step 2: Package EJB Classes and Interfaces in Upgrading EJBs to WebLogic Server Version 5.1 for more information.

   • Home JNDI name: Enter the JNDI name that clients will use to look up the EJB's home interface.

   • Maintains conversational state: (Session EJBs only) Check this box to designate a stateful session bean, or leave the box unchecked for stateless session beans.

   • Manages its own transactions: (Session EJBs only) Check this box if the EJB uses bean-managed transactions. Un-check the box to have WebLogic Server manage the bean's transactions.

   • Supports reentrant transactions: Check this box to specify a reentrant EJB. This corresponds to the reentrant element in the ejb-jar.xml file, as described in the EJB 1.1 specification.

   • Uses bean-managed persistence: Check this box if the entity EJB manages its own persistent storage. Leave the box unchecked if you want to use WebLogic RDBMS-based persistence services or a third-party persistence type.

7. Select File->Save to save your changes to the .jar file.

Follow these steps to create or change the transaction attributes for EJB methods:

1. Start DeployerTool and load the EJB .jar file if you have not already done so. See Starting DeployerTool and Loading a .jar file if you need instructions.

2. Select the + sign next to the .jar file name to display its contents.

3. Select the .jar file's Method transactions object. If you have already assigned method transaction attributes for the EJB, each collection of attributes is listed as "tx-n" where n is the collection number.

   If no method transactions are available, click the Add button to create a new "tx-0" transaction attribute. DeployerTool highlights the new attribute collection in red to indicate that you have not yet assigned attributes to methods.

4. Select the + sign next to the Method transactions object to display available transactions.

5. Select the transaction attribute name that you want to view or edit. DeployerTool displays the transaction attribute assignments in the edit panel:

6. Choose the transaction attribute you want to apply by selecting it from the Transaction attribute drop-down menu. Valid attributes are:

   • Mandatory: The caller must start a transaction before invoking the method.

   • Supports: If the EJB client has an active transaction context, WebLogic Server executes the method within the same transaction. If the client does not have a transaction context, WebLogic Server does not create one for invoking the method.

     Note: If the EJB provider does not specify a transaction attribute in the ejb-jar.xml file, WebLogic Server uses Supports by default.

   • Never: The EJB method does not participate within a transaction context. If the client calling the method has an active transaction context, WebLogic Server throws a java.rmi.RemoteException.

   • RequiresNew: WebLogic Server starts and ends a new transaction with each call to the EJB method. If the caller already has an active transaction, WebLogic Server suspends it during the method's invocation.

   • NotSupported: The EJB method does not participate within a transaction context. If the client calling the method has an active transaction context, WebLogic Server suspends the client transaction during the invocation of the the method.

   • Required: The EJB method requires an active transaction. If the client has an active transaction context, the EJB method is executed from within that context. If the client does not have a transaction context, WebLogic Server starts a new transaction for the invoking the EJB method.

7. In the Methods portion of the edit panel, use the + signs to expand the bean and interface name(s) that contains the methods you want to configure.

8. Check the selection boxes next to listed methods in the home and remote interfaces to apply the selected attribute.

9. If you want to apply a different transaction attribute to a different selection of methods, return to step 3 and create a new collection.

10. Select File->Save to save your changes to the .jar file.

The steps that follow describe how to limit access to individual EJB method calls by assigning method-level permissions.

If you specify no method-level permissions for an EJB (there is no method-permission stanza in ejb-jar.xml), WebLogic Server provides "guest" access to all EJB methods in the .jar file. This ensures that EJB methods have some default access permission when deployed on WebLogic Server.

If you want to specify method-level permissions you must do so for all methods in all EJBs stored in the .jar file. If you specify method permissions for even a single EJB method, WebLogic Server denies access for any methods that do not have permissions defined in the ejb-jar file.

To change an EJB's method-level permissions:

1. Start DeployerTool and load the EJB .jar file if you have not already done so. See Starting DeployerTool and Loading a .jar file if you need instructions.

2. If the .jar file does not yet contain an application role, follow the instructions in Mapping application roles to WebLogic Server principals to create one.

3. Select the + sign next to the .jar file name to display its contents.

4. Select the .jar file's Method permissions object. If you have already assigned method permissions for the EJB, each collection of permissions is listed as "perm-n" where n is the collection number.

   If no method permissions are available, click the Add button to create a new "perm-0" permission. DeployerTool highlights the new permission in red to indicate that you have not yet assigned an application role to the EJB methods.

   Note: If you choose to specify method-level permissions, you must do so for all methods in all EJBs in the .jar file. Otherwise, WebLogic Server denies access for methods that have no assigned permissions.

5. Select the + sign next to the Method permissions object to display available permissions.

6. Select the permission name you want to view or edit. DeployerTool displays the current application role assignments in the edit panel:

7. In the Methods portion of the edit panel, use the + signs to expand the bean and interface name(s) that contains the methods you want to configure.

8. Use the Methods check boxes to select each method to which you want to assign an application role.

9. Use the Can invoke check boxes to specify which application roles can invoke the selected methods.

10. Return to step 4 and assign method permissions for all other EJB methods in the .jar file that must be available to clients.

To configure an EJB's environment entries or values, follow these steps:

1. Start DeployerTool and load the EJB .jar file if you have not already done so. See Starting DeployerTool and Loading a .jar file if you need instructions.

2. Select the + sign next to the .jar file name to display its contents.

3. Select the + sign next to the Beans object to display all available EJBs in the .jar file.

4. Select the + sign next to the EJB name you want to view or modify.

5. Select the Environment entries item to display the environment properties for the selected EJB. DeployerTool shows the Name, Type, and Value for environment entries in the edit panel:

6. To edit an existing environment entry, double-click an existing Name, Type, or Value box. Then type in or select a new entry as described below:

   • Name: Type in a new name for the EJB environment entry. This is the name that a deployed EJB uses to look up the environment value.

   • Type: Select a Java primitive type from the drop-down menu. The Java type must be compatible with the specified environment value.

   • Value: Type in a new value for the environment property. The new value must be compatible with the specified Java primitive type.

7. To add a new environment entry, click the Add button to display the New environment entry dialog. Specify a new Name, Type, Value, and optional Description for the entry and click OK:

8. To delete an existing environment entry, click once in the row of the entry you want to delete, then click the Remove button.

9. Select File->Save to save your changes to the .jar file.

WebLogic Server uses deployment properties defined in the weblogic-ejb-jar.xml file to specify an EJB's caching, performance, and clustering properties. Use the following instructions to set or change any of these WebLogic Server-specific properties.

1. Start DeployerTool and load the EJB .jar file if you have not already done so. See Starting DeployerTool and Loading a .jar file if you need instructions.

2. Select the + sign next to the .jar file name to display its contents.

3. Select the + sign next to the Beans object to display all available EJBs in the .jar file.

4. Select the + sign next to the EJB name you want to view or modify.

5. Select the Optimizations item to display the caching and performance properties for the selected EJB. DeployerTool displays the current property values in the edit panel:

6. Edit the displayed property values as necessary:

   • Call by reference: Determines whether or not parameters to EJB methods are copied (passed by value). See enable-call-by-reference for more information.

   • Max beans in free pool (stateless session EJBs only): WebLogic Server maintains a free pool of stateless session EJBs instances for every bean class. This optional element defines the maximum number of pooled instances. See Initializing and using EJB instances in The WebLogic Server EJB Container for more information.

   • Initial beans in free pool (stateless session EJBs only): Specifies the number of EJB instances that WebLogic Server adds to the free pool on startup.

   • Max beans in cache (stateful EJBs only): Maximum number of instances of this stateful EJB class that are allowed in memory. See Initializing and using EJB instances in The WebLogic Server EJB Container for more information.

   • Idle timeout seconds (Stateful session EJBs only): After this number has been reached, inactive stateful EJBs may removed if space is needed in the cache. See EJB Lifecycle in WebLogic Server in The WebLogic Server EJB Container for more information.

   • Cache strategy (Entity EJBs only): Specifies the cache strategy for entity EJBs in a WebLogic Server cluster. See Entity EJBs in a cluster for more information.

   • Read timeout seconds (Entity EJBs only): Determines ejbLoad() behavior for read-only entity EJBs in a WebLogic Server cluster. See Entity EJBs in a cluster for more information.

   • Passivation strategy (Entity EJBs only): Select default to keep EJB instances in the WebLogic Server cache as long as possible, minimizing passivation. Select transaction to passivate the EJB instance at the completion of each transaction.

   • Database is shared (Entity EJBs only): Specifies whether or not the EJB's data store is shared by other servers or clients outside of WebLogic Server. See Using db-is-shared to limit calls to ejbLoad().

   • Is-modified method (Entity EJBs only): Specifies an EJB method WebLogic Server calls to determine whether or not the EJB data should be stored at the successful commit of a transaction. See Using is-modified-method-name to limit calls to ejbStore().

   • Finders call ejbLoad (Entity EJBs only): Select true to have WebLogic Server load the EJB instance into cache immediately when a reference is returned by a finder. To enable this feature, your finder must return a valid enumeration of EJBs. Select false to load EJB instances in accordance with the EJB 1.1 specification.

   • Updates at end of transaction: (Entity EJBs only) determines whether ejbStore() is called at the end of a committed transaction, or after each method call. See Using delay-updates-until-end-of-tx to change ejbStore() behavior.

7. Select File->Save to save your changes to the .jar file.

1. Start DeployerTool and load the EJB .jar file if you have not already done so. See Starting DeployerTool and Loading a .jar file if you need instructions.

2. Select the + sign next to the .jar file name to display its contents.

3. Select the + sign next to the Beans object to display all available EJBs in the .jar file.

4. Select the + sign next to the EJB name you want to view or modify.

5. Select the Clustering item to display the clustering properties for the selected EJB. DeployerTool displays the current property values in the edit panel:

6. Edit the displayed property values as necessary:

   • Home call router class: Specifies a custom class to use for routing bean method calls to WebLogic Servers in a cluster. This class must implement weblogic.rmi.extensions.CallRouter(). If specified, an instance of this class will be called before each method call and be given the opportunity to choose a server to route to based on the method parameters. It either returns a server name or null indicating that the current load algorithm should be used to pick the server.

   • Home is clusterable: If checked, the bean is deployed with a cluster-aware home stub. Calls to the home stub are load-balanced between the servers on which this bean is deployed, and if a server hosting the bean is unreachable, the call automatically fails over to an available server. If you check Home is clusterable, also select one of the Home load algorithm options described below. See EJBs in WebLogic Server Clusters for more information.

   • Home load algorithm: Specifies the algorithm WebLogic Server uses to load balance EJB lookup requests among WebLogic Servers in a cluster. If no algorithm is specified, WebLogic Server uses the algorithm specified by the weblogic.cluster.defaultLoadAlgorithm property in weblogic.properties. Possible settings include:

   • round-robin

   • random

   • weight-based

     DeployerTool displays the following properties only for stateless session EJBs:

   • Call router class: Specifies a custom class to use for routing bean method calls. This class must implement weblogic.rmi.extensions.CallRouter(). If specified, an instance of this class is called before each method call and is given the opportunity to choose a routing server based on the method parameters. The method returns either a server name or null indicating that the current load algorithm should be used to pick the server.

   • Bean is clusterable: If checked, each call to the EJB stub is load-balanced between the servers that are hosting the bean. If a call to the bean fails due to a communication failure, the call fails over to another server hosting the bean. If you check Bean is clusterable, also select one of the load algorithm options described above.

   • Bean methods are idempotent: Checking this option allows the failover handler to retry a failed call without knowing whether the call actually completed on the failed server. Check this option only if the stateless session EJB methods are truly idempotent. See Session EJBs in a cluster for more information.

EJB providers can define application roles for EJBs in the ejb-jar.xml deployment file. Application roles define required roles for EJBs, but they do not specify the actual security principal names in the running application server.

DeployerTool enables you to create EJB application roles and map them to actual WebLogic Server security principal names during the deployment process.

To map WebLogic Server principals to EJB application roles:

1. Start DeployerTool using the instructions in Starting DeployerTool.

2. If you have not yet done so, add one or more server profiles using the instructions in Setting up DeployerTool servers and preferences.

3. Select the WebLogic Server you want to deploy to by clicking on its name in the Server category.

4. Load an EJB deployment unit using the instructions in Loading a .jar file.

5. Expand the .jar file by clicking the + sign next to its name.

6. Select the .jar file's Security item to display available application roles in the .jar file, and available principal names in the selected WebLogic Server.

   If the .jar file does not contain any application roles, click Add and enter a name for the new role.

7. Click on the name of the application role to modify. DeployerTool shows which of the current principal names are members of the role by checking the In role checkbox:

8. To change membership in the selected application role, check or un-check the In role boxes for the principals you want to add or remove.

9. To delete a selected application role, click the Remove button.

10. Select File->Save to save your changes to the .jar file.

To map EJB references to actual EJBs:

1. Start DeployerTool using the instructions in Starting DeployerTool.

2. If you have not yet done so, add one or more server profiles using the instructions in Setting up DeployerTool servers and preferences.

3. Select the WebLogic Server you want to deploy to by clicking on its name in the Server category.

4. Load an EJB deployment unit using the instructions in Loading a .jar file.

5. Expand the .jar file by clicking the + sign next to its name.

6. Expand the Beans item to display all available EJBs in the .jar file.

7. Expand the EJB name that contains the references you want to view or modify.

8. Select the EJB's EJB references item to display available references in the .jar file.

   If the .jar file does not contain any EJB references, click Add to create one.

9. Expand the EJB References object (if it is not already expanded) to view available references in the .jar file.

10. Select a listed EJB reference to display its properties in the edit panel:

11. Modify the EJB reference properties as follows:

    • EJB Link: This entry defines a link to a specific EJB defined in ejb-jar.xml, or to an EJB installed in a running server (Installed bean).

    • Reference bean type: Specify whether the referenced bean is a session EJB or entity EJB.

    • Home interface class: Enter the expected Java class type of the home interface for this referenced EJB.

    • Remote interface class: Enter the expected Java class type of the remote interface for this EJB reference.

    • Linked bean JNDI name: Specify the JNDI name of the references EJB.

    • Description: Enter descriptive text for the EJB reference.

1. Start DeployerTool using the instructions in Starting DeployerTool.

2. If you have not yet done so, add one or more server profiles using the instructions in Setting up DeployerTool servers and preferences.

3. Select the WebLogic Server you want to deploy to by clicking on its name in the Server category.

4. Load an EJB deployment unit using the instructions in Loading a .jar file.

5. Expand the .jar file by clicking the + sign next to its name.

6. Expand the Beans item to display all available EJBs in the .jar file.

7. Expand the EJB name that contains the resource references you want to view or modify.

8. Select the EJB's Resource factory references item to display available resource references in the .jar file.

   If the .jar file does not contain any EJB references, click Add and enter a name for the new reference.

9. Expand the Resource factory references item to list references in the .jar file.

10. Select a listed resource factory reference to display its properties in the edit panel:

11. Modify the resource factory reference properties as follows:

    • Resource factory type: Select a resource factory type from the drop-down list. See New resource factory support for more information on available types.

    • Sign-on responsibility: Select whether the responsibility for signing on to the resource factory lies with the Container or Application.

    • JNDI reference link: Enter the JNDI name of the resource factory available in the selected WebLogic Server.

    • Description: Enter descriptive text for the resource factory.

You can use DeployerTool to configure persistence properties for Entity EJBs that use container-managed persistence. The following sections describe how to configure properties for EJBs that use WebLogic Server RDBMS-based persistence.

If you use a third-party persistence type, configuration may take place within DeployerTool or in a separate utility or procedure. In either case, refer to your persistence type documentation for instructions.

To view or modify the container-managed fields defined in your XML deployment files:

1. Start DeployerTool using the instructions in Starting DeployerTool.

2. Load an EJB deployment unit that uses WebLogic Server RDBMS-based persistence services.

3. Expand the .jar file by clicking the + sign next to its name.

4. Expand the Beans item to display available EJBs in the .jar file.

5. Expand the EJB name that uses WebLogic Server RDBMS-based persistence.

6. Select the Persistence object to display the EJB's persistent fields and primary key definition:

7. To change the primary key type, select a type from the Primary key type drop-down menu. You can specify a simple primary key by selecting a simple Java type. Select a compiled primary key class type to define a compound key. See Simple and compound primary keys for more information.

8. For simple primary keys, select a Primary key field from the drop-down menu.

9. Select the Container-managed check boxes next to a field name to have WebLogic Server automatically manage persistence for those fields using RDBMS-based persistence.

   Note: For each field that you designate as Container-managed, define the mapping of the field to a database column using the instructions in Configuring WebLogic Server RDBMS-based persistence.

DeployerTool enables you to perform the following configuration tasks for beans that use WebLogic Server RDBMS-based persistence services:

• Specifying the table and connection for RDBMS operations

• Mapping container-managed fields to database columns

• Editing EJB finder method expressions

Specifying the table and connection for RDBMS operations

1. Start DeployerTool using the instructions in Starting DeployerTool.

2. Load an EJB deployment unit that uses WebLogic Server RDBMS-based persistence services.

3. Expand the .jar file by clicking the + sign next to its name.

4. Expand the Beans item to display available EJBs in the .jar file.

5. Expand the EJB name that uses WebLogic Server RDBMS-based persistence.

6. Expand the Persistence item to list available backing stores.

7. Expand the Backing stores item to display the WebLogic RDBMS Persistence backing store.

8. Select the WebLogic RDBMS Persistence backing store to display configuration properties in the edit panel.

9. Click the Configuration tab in the edit panel to display basic backing store properties:

10. Edit backing store fields to define the high-level mapping for RDBMS operations:

    • Schema name: If applicable to your datastore, enter the schema name that stores data for container-managed fields.

    • Table name: Enter the RDBMS table name that stores data for the EJB's container-managed fields. See Mapping container-managed fields to database columns for information on assigning fields to individual columns in the selected table.

    • Connection pool name: Enter the JNDI name of the connection pool to use for accessing the RDBMS.

    • Transaction isolation level: Select the transaction isolation level to pass to the underlying datastore for this EJB. See Transaction isolation level for more information.

Follow these steps to map individual EJB container-managed fields to columns in a selected datastore:

1. Follow the instructions in Specifying the table and connection for RDBMS operations to open the WebLogic RDBMS Persistence backing store.

2. Click the Field-column map tab in the edit panel to display the current mapping between container-managed fields and database columns:

3. To change the database column used to back a container-managed EJB field, double click the Table column name and type in the new name.

   Note: WebLogic Server does not support using quoted RDBMS keywords in a column mapping. For example, you cannot map EJB fields to columns named "create" or "select" if those names are reserved in the underlying datastore.

Follow these steps to modify the WebLogic Query Language (WLQL) expressions and Java expressions used in EJB finder methods:

1. Follow the instructions in Specifying the table and connection for RDBMS operations to open the WebLogic RDBMS Persistence backing store.

2. Click the Finders tab in the edit panel to display the finder methods available in your deployment files:

3. To view or change the expressions used in a particular finder method, double click the method name to display an Edit finder method dialog:

   The Name and Parameter(s) section of the dialog lists all parameters to the selected finder method along with each parameter's number designation. In the example above, the findBigAccounts method has a single parameter of type double, represented by $0. Additional parameters would be designated by $1, $2, and so forth.

   The Query and Expression(s) section lists the text of the WLQL query for the finder method. The WLQL query uses number designations ($0 in the example above) to represent values supplied by the finder method arguments, or values supplied by embedded Java expressions.

   The bottom portion of the dialog lists optional Java expressions that you can embed within the WLQL query. As with the parameters Name and Parameter(s) section, each Java expression uses a number designation. In the above example, adding a new Java expression would yield the number designation "1", since the initial value "0" is used by the method parameter. Within the WLQL, expression, $0 would represent the method parameter, and $1 would represent the embedded Java expression.

4. To edit the finder's WLQL query, simply edit the text in the Query and Expression(s) section of the dialog. See Using WebLogic Query Language (WLQL) for complete information about WLQL syntax and conventions.

5. To add an embedded Java expression, click the Add button and follow the instructions below.

6. To edit an embedded Java expression, double-click a column and edit the value as appropriate:

   • No.: Edit the number designation used to refer to the Java expression in the WLQL query. If you use a number listed in the Name and Parameter(s), you "override" the parameter designation in the query.

   • Text: Enter the text of the Java expression. See Using Java Expressions in WLQL for complete instructions and restrictions for using embedded Java in WLQL.

   • Type: Enter the return type of the Java expression. See Using Java Expressions in WLQL for complete instructions and restrictions for using embedded Java in WLQL.

7. Click OK or Cancel to save or cancel changes to the finder method.

DeployerTool validates EJB deployment units in two ways by:

• automatically checking deployment properties and references to ensure that they contain appropriate values

• checking EJB home, remote, and implementation classes to ensure that method signatures are compliant with the EJB 1.1 specification

Validating deployment properties

When you load a new .jar file or change deployment properties, DeployerTool automatically checks the properties to ensure that supplied values are valid and appropriate for the selected server. This includes:

• ensuring that all class files referenced in ejb-jar.xml exist in the .jar file

• ensuring that required deployment properties contain values

• checking environment entry values to ensure that they match their associated Java types

• connecting to a WebLogic Server profile and ensuring that resource factory references, EJB references, and security principals map to actual JNDI names and principals in the server

If DeployerTool finds any errors in the deployment properties that would prevent you from deploying to the selected server, it lists those errors in the Problems display of the message panel. DeployerTool also highlights in red the .jar file, EJB, method, or property category that contains the error.

To address deployment property errors:

1. Start DeployerTool and open the .jar file that contains deployment errors.

2. Click the Problems tab in the messages panel to display the deployment error messages.

3. Expand the red highlighted objects in the object panel to locate the source of individual deployment errors. As you select nested objects, the Problems display changes to show only those deployment errors in the current object or property listing.

4. Edit the property value as indicated in the error message to correct the problem. DeployerTool validates your entry immediately after editing, so you can determine if the problem is resolved.

5. Continue addressing highlighted items in the object panel as necessary. Once you have addressed all of the deployment errors, the .jar file entry will no longer appear highlighted, and you can continue compiling or deploying the EJBs.

DeployerTool provides a compliance checking option to check compiled EJB classes for compliance to the EJB 1.1 specification. To check the contents of a deployment unit for compliance to EJB 1.1:

1. Start DeployerTool and open the .jar file that you want to check for compliance.

2. If you have not done so, address all deployment property errors using the instructions in Validating deployment properties. You cannot check for compliance to the EJB 1.1 specification until all deployment properties are valid.

3. Select the name of the .jar file to check in the DeployerTool object panel.

4. Select the Messages tab in the messages panel.

5. Select Tools->Check Compliance to begin the validation process.

   DeployerTool displays any noncompliance messages in the message panel. Individual messages are tagged with a section number, which indicates the section of the JavaSoft EJB 1.1 specification that describes the requirement.

   If you need more information about how to address a noncompliance message, refer to one of the following sources:

   • Required changes for EJB 1.1 compliance in the WebLogic Server EJB documentation

   • The section of the JavaSoft EJB 1.1 specification indicated by the DeployerTool compliance message

     After addressing known compliance errors, recompile your classes, repackage the EJB .jar file, and use DeployerTool to repeat the compliance check.

For each EJB deployment present in a .jar file, DeployerTool calls the ejbc compiler to generate container implementation classes. The implementation classes are then processed through the RMI compiler, which generates a client-side stub and a server-side skeleton.

When you use DeployerTool to generate container classes, the files are inserted back into the .jar file. If you want to place the container classes into a different file, use ejbc from the command line, as described in ejbc.

By default, ejbc uses javac as a compiler. For faster performance, specify a different compiler (such as Symantec's sj) by setting up ejbc preferences within DeployerTool. See Setting up DeployerTool servers and preferences for more information.

To generate container classes for EJBs you have loaded:

1. If you have not done so, address all deployment property errors using the instructions in Validating deployment properties. You cannot generate container classes until all deployment properties are valid.

2. Select the name of the .jar file to check in the DeployerTool object panel.

3. Select Tools->Generate container... to begin compiling EJBs in the .jar file.

To deploy a .jar file to WebLogic Server:

1. If you have not done so, compile the container classes into the .jar file using the instructions in Compiling EJB container classes.

2. Select the name of the .jar file to check in the DeployerTool object panel.

3. Select Tools->Deploy... to deploy the .jar file to the default WebLogic Server. If you want to use a non-default server, select Tools->Deploy To...->server_name where server_name is the WebLogic Server profile you want to use.

   Note: DeployerTool uses hot deployment, via the deploy command shell utility, to deploy EJBs. See Deploying EJBs in WebLogic Server for general information on deploying EJBs. See Deploying EJBs in a running WebLogic Server (Hot Deployment) for specific information and restrictions regarding hot deployment.