Preparing Enterprise Beans for Deployment

The foregoing chapters have focused on creating individual enterprise beans. However, before one or more finished beans can be assembled into an application and deployed on a J2EE-compliant application server in a production environment, the following tasks remain to be done:

1. Configure individual beans. Furnish information about each bean's external dependencies and operating requirements. This information becomes part of the bean's deployment descriptor, which is described in the next section.

2. Form an EJB module around a bean or group of beans that need to work cooperatively in an application, and configure the module. By packaging the beans into an EJB module, you generate a deployment descriptor. This deployment descriptor identifies the runtime services that the module's components need from the application server, such as container-managed persistence.

3. Add one or more EJB modules to a J2EE application (and, if necessary, add other components such as web modules).

4. Configure the J2EE application and its included modules to work with each other and with other resources such as a database.

This book focuses on the deployment considerations for enterprise beans and EJB modules. It also touches briefly on creating and configuring a J2EE application around one or more EJB modules. For complete scenarios and details on application design, assembly, and configuration, refer to these three books: Building Web Services, Building Web Components, and Building J2EE Applications. Also, you'll find the Sun ONE Studio 5 applications and tutorials helpful (go to http://forte.sun.com/ffj/documentation/tutorialsandexamples.html).

You can test-run an individual enterprise bean, using the automated testing feature of the Sun ONE Studio 5 IDE. The IDE generates an EJB module and an application strictly for the purpose of testing your bean, but you can easily substitute your production components and test them. The testing feature is described in Chapter 9.

Ordinarily, enterprise beans are assembled into an EJB module, one or more EJB modules are assembled into an application, and the application is deployed to an application server. However, an individual EJB module can also be deployed.

---

Understanding Deployment Information

The deployment information you specify in the property sheets for an enterprise bean or EJB module becomes part of the deployment descriptor. This is an XML-based text file that captures information about a J2EE component's structure and its internal and external dependencies, that is, its relationships to other components inside and outside its immediate environment. The deployment descriptors for an enterprise bean and its EJB module contain all the instructions an application server needs when the bean's application is deployed. Any change in this descriptor can change the bean's behavior in the application.

You automatically generate a deployment descriptor for an enterprise bean when you use the EJB Builder wizard to create the bean, as described in the foregoing chapters. The wizard generates the bean's basic descriptor.

When you place enterprise beans in an EJB module (as explained in Creating and Configuring an EJB Module), the IDE automatically generates a deployment descriptor for the module as well. This descriptor file captures:

• Each bean's declarative meta-information from the bean's deployment descriptor; that is, information about the bean that is not written into the bean's source code
• Declarations of external resources (such as enterprise beans) that are required for the beans within this module to operate properly
• Security and transaction information that allows the EJB module to override any such information that had been specified at the bean level

When you deploy an application to an application server, the server adds its own deployment descriptor with information about the datasource on which the application's entity beans are based.

By changing the EJB module's descriptor, you can change the application's behavior without touching the source code or even the deployment descriptor of the component beans.

The contents of a deployment descriptor are accessible through the property sheets of the corresponding bean or module. If necessary, you can also edit an EJB module's descriptor directly. The following three sections describe how you can see and affect the deployment descriptor.

Looking at a Generated Deployment Descriptor

To see the XML-based file that constitute the deployment descriptor of an enterprise bean:

In the Explorer window, select a bean's logical node, right-click, and choose View Deployment Descriptor. (Or, select an EJB module's logical node, right-click, and choose Deployment Descriptor View.)

The Source Editor displays the file as read-only.

Changing a Deployment Descriptor

The recommended way to change a bean's or EJB module's deployment descriptor is to use property sheets. (Those instructions start in Using Properties to Edit a Deployment Descriptor.) When you use Properties, all you have to do is specify file or object names and values. You don't see the actual descriptor file, and you don't have to write any XML. You make your selections using a dialog box, and the IDE automatically applies the changes across all the appropriate components of the EJB module.

It's also possible to edit the deployment descriptor directly. After a direct edit, you can no longer add or delete beans from the module or use the property sheets to change the descriptor. However, you can revert to the generated descriptor.

Editing an EJB Module's Deployment Descriptor Directly

If you need to make a direct edit in the deployment descriptor file of an EJB module, do it as follows:

Right-click the EJB module's node and choose Deployment Descriptor Final Edit.

After directly editing an EJB module's deployment descriptor, you can still use the property sheets to make changes that don't affect the deployment descriptor. For example, you can still go to the Sun ONE AS tab of the EJB module's property sheet and specify or change the connection with the data source used by an entity bean in the module. However, fields that represent items in the deployment descriptor are closed to edits in the property sheets.

Reverting to the EJB Module's Last Generated Descriptor

If you have used the Final Edit feature, but now want to go back to the last generated version of the deployment descriptor and continue from there to make changes in the property sheets, do as follows:

Right-click the EJB module's node and choose Deployment Descriptor Revert to Generated.

---

Note - If you choose Revert to Generated, any edits you made directly in the deployment descriptor file are lost.

---

Using Properties to Edit a Deployment Descriptor

To use property sheets to add to, edit, or complete an enterprise bean's or an EJB module's descriptor, do as follows:

Select the bean's or EJB module's logical node, right-click, and choose Properties.

In the case of an enterprise bean, the Properties dialog box appears, showing at least three tabs:

• Properties
• References
• Sun ONE AS (the Sun ONE Application Server)

You also see a tab for any other application server's plugin module that has been installed with the IDE.

For an EJB module node or a J2EE application node, there are two default tabs:

• Properties, which includes reference fields
• Sun ONE AS

The default tabs for enterprise beans are described next.

---

Specifying Bean Properties

Before you create an EJB module around cooperating enterprise beans, you might need to configure individual beans by specifying one or more properties on the beans. These properties are discussed tab by tab in the following sections: Using the Properties Tab, Using the References Tab, and Using the Sun ONE AS Tab.

Notice that any properties that are dimmed or read-only have been set automatically by the EJB Builder and can't be changed. If, for example, you decide your CMP entity bean should manage its own persistence, you must go to the EJB Builder wizard and recreate it as a BMP entity bean.

Using the Properties Tab

Since you're familiar with your bean's code, you'll probably recognize most of the fields in the Properties tab. Also notice the following:

• In the Properties tab for any kind of enterprise bean, certain fields are read-only. These fields were automatically completed by the EJB Builder wizard when you created the bean. The properties named in these fields are so intrinsic to the bean type that you shouldn't need to change them. The only practical way to change them would be to go back to the wizard and recreate the bean.
• The Name field and the fields naming the bean's interfaces were completed by the EJB Builder wizard when you created the bean (or you overrode the names in those fields in the wizard, at creation time).

If you want your bean to use another existing class, you can override one of the classes shown in these Properties fields.

If you want to change the name of a class but retain the same class content, you must either make the change in the property editor for that class (not the property editor for the logical bean node) or directly edit the class code in the Source Editor.

• The Large Icon and Small Icon fields are for any icons that you want to accompany the enterprise bean and be available to tools like application servers. For a large icon, the file must be a JPEG or GIF image 32x32 pixels in size, or 16x16 pixels for a small icon. The file must have the suffix .jpg or .gif.
• The Security Identity field lets you specify the identity the enterprise bean will use when it makes calls.
• If you select Run As Specific Security Role and name a role, for example, a role found in a related bean, your bean executes under that security role, and all methods called by the bean carry that security role. In this way, the bean can access data ordinarily reserved for the other bean. Or, you can specify the bean's default security role here.
• If you select Use Caller's Security Identity, the executing bean assumes the security identity of the caller.
• If you leave the Not Set value in this field, the bean executes under the security identity defined at the application-server level or under the caller's security identity.

Some property types in this tab are unique to specific bean types, and these properties are discussed next.

Properties of Entity Beans

In the Properties tab for any entity bean, you also see the following fields:

• Primary Key Class. This is the Java class associated with the primary key of the table that the CMP entity bean is modeling. When the bean was created, the EJB Builder based this class on information retrieved from the database about the table's primary-key field.
• Reentrant. If you want to avoid unintentional multithreading problems, leave this field marked False. This way, if an instance of your bean executes a client request in a given transaction context, and a second request for the same context arrives for the same entity object, the container throws an exception to the second request. However, if you really need to let your bean use another bean to make a call to itself, mark this field True.

In the Properties tab for a CMP entity bean, you also see the following fields:

• Abstract Schema Name. The abstract schema defines the bean's persistent fields and relationships. Your CMP entity bean's EJB QL queries are modeled on the bean's abstract persistence schema and its dependent object classes, and EJB QL queries use the bean's abstract schema name.
• CMP Version. This read-only field reflects whether the CMP bean has a version 1.x bean class or a a version 2.x bean class.

Properties of Session Beans

In the Properties tab for a session bean, you also see the following fields:

• Bean Type. If you want, you can change this value from Stateless to Stateful (or the opposite).
• Transaction Type. This field reflects whether the container or the bean manages its transactions.

Properties of Message-Driven Beans

In the Properties tab for a message-driven bean, you also see the following fields:

• Transaction Type. This field reflects whether the container or the bean manages its transactions. The EJB Wizard populated this field, but you can change it if necessary.
• Acknowledge Mode. If the message-driven bean's transaction type is Bean, you see the Acknowledge Mode property in this tab. To make sure all messages consumed by the bean are acknowledged, set this property to Auto. Or, if you want the bean to acknowledge duplicate messages at its convenience, set this property to Duplicates Allowed.
• Message Selector. Use this field if you want to apply one or more filters to reduce the number of incoming messages your message-driven bean must listen for. For example, the following string causes the bean to receive only messages whose AccountStatus property is set to Late or Delinquent.

AccountStatus = `Late' OR AccountStatus = `Delinquent'

The syntax for message selectors, which is based on a subset of the SQL92 conditional expression syntax, is described in the JMS specification and the JMS tutorial.

• Message-Driven Destination. In this field, specify whether your message-driven bean listens to a message queue, or whether it subscribes to a topic (and, in that case, whether the subscription is durable or non-durable). The data in this field is related to the data in certain fields on the property sheet's tabbed interfaces for application servers. For details, see Setting Sun ONE AS Properties for Message-Driven Beans.

Using the References Tab

To prepare your enterprise bean for assembly and deployment, you complete this tab's fields, which represent many of the enterprise bean's external dependencies. Some of the information can be stated at the bean level and then overridden at the module or application level.

One example of a References tab is shown next.

 FIGURE 8-1 References Tab of the Properties Dialog Box for a CMP Entity Bean

[ D ]

Each field in this tab is described next, with instructions for completing the field.

Specifying EJB Local References

This field and the following one contain information about any other enterprise beans whose methods your bean calls. You use the EJB Local References field to specify references to beans that reside within the same JVM. An EJB local reference accesses the local interface of a bean running in the same JVM, although the two beans might be in different EJB modules. (For contrast, see Specifying EJB References.)

You can specify the name of the implementing enterprise bean at development time, and, if necessary, that setting can be overridden when your bean is assembled into an EJB module.

In the bean's code, you use the JNDI interface to look up the local home interface of another bean. Before enclosing the bean in an EJB module, you also link the beans by specifying those same references in the bean's property sheet. The person who assembles the application looks at the EJB References field to see which other beans your bean must have access to in order to work as designed. The references specified here at the bean level can be used or overridden at the module level, as needed in the target environment.

---

Note - Before enclosing multiple beans in an EJB module, be sure the bean-to-bean references are coded in the bean class and the EJB references are specified in the property sheet.

---

To specify EJB local references in the property sheet, do as follows:

1. Click the EJB Local References field, then the ellipsis (...) button.

The EJB Local References property editor appears.

2. Click Add.

The Add EJB Local Reference dialog box appears.

3. Complete the fields.

The following fields are mandatory.

---

Note - The easiest way to fill in these fields is to start with the Referenced EJB Name field, selecting a local enterprise bean from the Browse list. The IDE then automatically fills in the type field and the two interface fields. However, you can change the interface fields if you need to.

---

• Reference Name. The referenced bean's name, which is mapped to the same name in the context.lookup method call in your bean class code and used by the assembler to locate the correct object.

Notice that in this property sheet, the field already contains ejb/. The name is relative to the java:comp/env context under the ejb/ subcontext. After the slash, type the reference name of the bean to which your bean refers.

The reference name does not have to be the actual JNDI name of the object. This name provides a level of indirection for the sake of flexibility. It is not a reference to the bean itself, but to the way the object is named in the lookup code.

For example, the bean Account might look up a reference to the home interface for the bean DiscountCodeTbl. The full reference name in this case would be ejb/DiscountCodeTblHome, or you can supply another reference name that is consistent with the name used in the lookup code.

In the case of local references, Sun ONE Application Server 7 might not need the full JNDI name, that is, the name preceded by ejb/, to find the object.

• Referenced EJB Name. The actual JNDI name of the enterprise bean that implements the local home and local interfaces specified in those fields. You can do any of the following, depending on your situation:
• Click Browse and select a bean. This might be the most convenient approach, as it causes the IDE to complete the interface and type fields for you.
• Type over data in this field to specify another bean that implements those same interfaces, and change the reference to another bean.
• Leave this field blank until the bean has been assembled into an EJB module or an application.

• Type. Whether the referenced bean is a session or entity bean.
• Local Home Interface. The referenced bean's local home interface.
• Local Interface. The referenced bean's local interface.

The description field is optional. That information might be helpful to the person who assembles your EJB module into an application.

• Description. The purpose of the referenced bean, or why your bean needs to reference it.

Specifying EJB References

In the EJB References field, you specify links to any enterprise beans that reside outside your bean's JVM but whose methods your bean calls. You use the field as you would the EJB Local References field, except that the reference you name here points to the remote interface of a bean running in the another JVM.

Specifying Environment Entries

An environment entry, stored in your bean's runtime environment, is a named data value that depends on policy or procedure at the deployment site. Environment entries can alter the behavior of an enterprise bean at deployment time without modifying the source bean's code. Any values that you set here in the property sheet can be overridden at deployment time in the deployment descriptor of an EJB module or an application.

For example, the Account bean can use the environment entry overdraftAllowed (of type boolean). This variable might indicate whether or not a particular bank that uses the Account bean allows customers to overdraw their account balances. The Account bean looks up the value of overdraftAllowed to decide what should happen if a customer's request causes an overdraft.

To add an environment entry, do as follows for each environment:

1. Click the Environment Entry field and then the ellipsis (...) button.

The Environment Entry property editor appears.

2. Click Add.

The Add Environment Entry dialog box appears.

3. Complete the fields.

The following two fields are mandatory.

• Name. The name of the environment variable.
• Type. The data type of the variable.

You can also complete the other two fields.

• Description. The purpose of the variable, and any other information that the assembler or deployer should know when using your bean in that environment.
• Value. An initial value.

Specifying Resource Environment References

Use this field to specify any administered object your bean needs to use, such as a JMS destination (a queue or topic). The resource environment reference is the queue's or topic's logical name.

This logical name must map to the name that appears in your bean class's InitialContext.lookup method. (Notice that this logical name can be either the actual JNDI name or merely a reference name such as myQueue, just as long as it matches what is in the lookup code.)

When your bean needs the resource that you specify in this field, an instance of the resource is created by the factory mentioned in the next section.

To add a resource environment reference, do as follows for each object that you want your bean to use:

1. Click the Resource Environment Reference field and then the ellipsis (...) button.

The Resource Environment References property editor appears.

2. Click Add.

The Add Resource Environment Reference dialog box appears.

3. Complete the fields.

The following fields are mandatory.

• Name. The name that appears in the InitialContext.lookup method of your bean class code.
• Type. The type of resource factory. Specify your own type, or select one of the following:
• javax.jms.Queue, a Java Message Service queue.
• javax.jms.Topic, a Java Message Service topic.

Specifying Resource References

This field contains the name of the factory that creates a connection to a resource that your been needs. This resource might be a datasource (such as a relational database), an administered object (such as a queue or topic), a JavaMail session, a URL, or a J2EE connector (which lets you connect your bean to another application system or EIS). The information in the Resource Reference field must correspond to a JNDI lookup method call in your bean class code. However, in this field you don't have to specify the resource by its actual JNDI name. It's a reference name, and it must simply match what you've written into your bean class code.

To add a resource factory reference, do as follows for each resource that your bean needs:

1. Click the Resource Factory Reference field and then the ellipsis (...) button.

The Resource Factory References property editor appears.

2. Click Add.

The Add Resource Reference dialog box appears.

3. Complete the fields.

The following fields are mandatory.

• Name. The name that appears in the InitialContext.lookup method of your bean class code. For example, for a JDBC resource factory that you refer to as myPointbase, your lookup method might be coded as follows:

javax.naming.InitialContext myContext = new javax.naming.InitialContext(); javax.sql.DataSource mySource = (javax.sql.DataSource) myContext.lookup("java:comp/env/jdbc/myPointbase");

The corresponding name for the resource reference in this case would be jdbc/myPointbase. Notice that the environment's subcontext is represented by jdbc/.

• Type. The type of resource factory. Specify your own type, or select one of the following:
• javax.sql.DataSource, a JDBC connection factory.
• javax.jms.QueueConnectionFactory, a Java Message Service connection factory.
• javax.jms.TopicConnectionFactory, a Java Message Service connection factory.
• javax.mail.Session, a JavaMail session factory.
• javax.resource.cci.ConnectionFactory, a connection factory that you declare if you want your bean to connect to another application system or EIS. An enterprise bean can use the Connector architecture Common Client Interface (CCI) API and a resource adapter to get access to outside data. For more information on implementing the CCI API in your application, refer to the Java 2 Platform, Enterprise Edition Tutorial.
• java.net.URL, a URL connection factory.

• Authorization. How the user is authenticated and authorized to use the resource.
• Container: The EJB container signs on to the resource manager, using information supplied by the application deployer at deployment time.
• Application: The enterprise bean code causes the resource manager sign-on to happen programmatically.

The following field is optional.

• Sharing Scope. Whether the connection to this resource can be shared by another enterprise bean in the same application. If two or more beans can use the same resource in the same transaction context, the container can carry out transactions locally and save time.

Specifying Security-Role References

If your enterprise bean does its own security checking, that is, if it checks to see if the user has the authority to use your bean to perform a task, you must provide security-role references in this field. (A message-driven bean needs no security role; it merely propagates whatever security information came from a client in a message. Any needed security checking is done later by either the container or the enterprise bean from which the message-driven bean requests work.)

To use this field, you must also have provided corresponding code (programmatic security) in your bean class. For example, your code might include the following method from the javax.ejb.EJBContext interface:

isCallerInRole(rolename)

In that case, you also need to add all applicable role names as security-role references in this property sheet.

Security roles can also be defined at the module level. For more information, refer to Building J2EE Applications.

To add a security role at the bean level, do as follows:

1. Click the Security Role Reference field and then the ellipsis (...) button.

The Security Role References property editor appears.

2. Click Add.

The Add Security Role Reference dialog box appears.

3. Complete the fields.

• Name. The name of the security role, as it appears in your bean class code. This field is mandatory.
• Description. An explanation of the role. This field is optional.
• Security Role Link. A link to a security role in the deployment environment. (This field is optional at the bean level. The data might not be available until deployment time; the field typically is completed by the deployer.)

Using the Sun ONE AS Tab

The tab for Sun ONE Application Server (the Sun ONE AS tab) shows properties that are automatically assigned when you use the EJB Builder to create an enterprise bean. Many of these properties contain default values based on how the server understands the type of enterprise bean. Also, any non-local EJB references that you've declared between enterprise beans appear automatically as EJB Reference Mappings in the Sun ONE AS tab.

You'll rarely need to specify any properties on the Sun ONE AS tab for an individual enterprise bean. The application server requires more information on an EJB module that contains one or more CMP beans. There, you see the IDE's generated instructions to the container on how to intercede between the bean and its underlying data storage.

First, let's consider the property-field values in the Sun ONE AS tab for individual enterprise beans. Then, starting in Creating and Configuring an EJB Module, we will explore how to create an EJB module around enterprise beans, and how to set a CMP entity bean's database-related properties at the EJB-module level.

Setting Server Properties for Individual Session and Entity Beans

For a session bean, a CMP bean, or a BMP bean, the Sun ONE AS tab displays the properties shown next. The following example uses a session bean called Process Order.

[ D ] 

The plugin supplies values in the following fields if they have been specified in the bean's other property sheets or source code:

• EJB Reference Mappings. This property names the target referenced enterprise bean as it is known to the specifying bean (which doesn't have to be the actual JNDI name) and to the server (this must be the actual JNDI name).
• JNDI Name. The server plugin populates this field with the name by which a JNDI lookup call locates your bean before creation. You can change the name here if you want, but you can't leave it blank.
• Pass By Reference. By default, the server plugin applies pass-by-value semantics to enterprise beans co-located within the same process, but without marshalling all call parameters. In this way, the call overhead is kept low. However, you can set the value of this property to true if you want pass-by-reference semantics to be used on a particular enterprise bean.
• Resource Environment Reference Mappings. The server plugin populates this property with a resource pair: the JNDI name from the bean's source code, and the resource manager that is registered with the server and that the bean needs (for example, a JMS destination object such as a message queue).
• Resource Reference Mappings. The server plugin populates this field with another resource pair: the JNDI name from the bean's source code, and a connection factory that is registered with the server (for example, a queue connection factory).

For an entity bean, this is where you specify the data source by two names: the reference name and the actual JNDI name. When you open the properties editor, you see a dialog box with two tabs, as shown in the next two figures.

• In the Standard tab, you specify the logical name defined in the entity bean's source code, which is the name used in the initial context lookup. It doesn't have to match the actual JNDI name of the data source. In the example in FIGURE 8-2, the logical name of the data source is jdbc/myPointbase.

 FIGURE 8-2 Standard Tab of the Resource Reference Property Editor for an Entity Bean

• In the Sun ONE App Server tab, you specify the actual JNDI name of the data source as it was assigned under Registered JDBC DataSources in the Explorer's Runtime tab.

In the example in FIGURE 8-3, the data source's actual JNDI name is jdbc/jdbc-pointbase. Both the default user name and the default password are PBPUBLIC (all capitals). After you type the password, press the Enter or Return key.

 FIGURE 8-3 Sun ONE App Server Tab of the Resource Reference Property Editor for an Entity Bean

In most cases, you don't need to change the values of the other properties in the Sun ONE AS tab. However, if you need details, refer to the documentation on Sun ONE Application Server. The remaining properties in this tab allow you to do the following:

• Adjust the behavior of the bean pool
• Change the default runtime bindings of a resource reference
• Use another commit option for the bean's transactions
• Redirect the bean's input or output
• Change the bean's run-as role
• Make a bean read-only, so that a client can't modify it
• Tell the server how often to refresh a read-only bean from its JDBC data source

The relationship between an enterprise bean and its underlying data storage is controlled through properties specified on the EJB module that contains the bean, not through the individual bean's properties. Before you deploy an enterprise bean to any server, you must first create an EJB module to hold the bean, whether you do this within the context of testing (see ) or for production purposes. See Setting Database-related Properties for CMP Entity Beans for details.

Setting Sun ONE AS Properties for Message-Driven Beans

The Sun ONE AS tab for a message-driven bean also contains properties that describe the kinds of messages the bean consumes and the resources the bean uses.

[ D ] 

Most of the time, you will need to consider only the following properties:

• JMS Durable Subscription Name. If the message-driven bean subscribes to a topic and has a durable subscription, specify the name here.
• JMS Max Messages Load. If necessary, you can specify here the maximum number of messages to be loaded into a JMS session for the message-driven bean to consume.
• MDB Connection Factory. The server plugin supplies these values from the registered resource, including any access data (a name and password for the default resource principal, or user of the database).

For details on the other properties, refer to the documentation for Sun ONE Application Server 7.

To deploy an enterprise bean, you must first create an EJB module around the bean. EJB modules are discussed next.

---

Creating and Configuring an EJB Module

Perhaps you have designed an enterprise bean to work on its own, or perhaps you have designed several beans to work cooperatively. In either case, you must package your enterprise beans in an EJB module to deploy it to an application server. In the case of multiple cooperating beans, the module ensures that the right beans are kept together and that all necessary information about the beans' operating requirements is packaged with them.

Enterprise beans don't have to be in the same module to work together; they can run in different modules and even in different JVMs. However, sometimes it's more convenient to keep cooperating beans together in the same module.

If you need to have multiple CMP beans working together within an EJB module, it's best to start by using the EJB Builder wizard to create a set of related CMP beans from a database or database schema. At the same time, the wizard creates the surrounding EJB module. When you approach the task that way, the IDE automatically preserves all the relationships between the beans.

An EJB module is a logical entity in the IDE, a symbolic representation of its physical counterpart, which is an EJB JAR (a standard Java archival file with the extension .jar). The EJB module contains a J2EE deployment descriptor, which it uses to track cooperating enterprise beans, the beans' source code and interconnections, and properties that reflect the deployment environment, that is, information specific to an application server. However, neither the beans nor copies of them actually reside in the EJB module.

The beans in an EJB module can be in the same directory or in several directories, even in different filesystems.

An EJB module is the smallest unit of enterprise beans that can be deployed to an application server. Ordinarily, the unit that executes on an application server is a J2EE application containing several EJB modules, each of which contains one or more enterprise beans.

Deciding What Should Go Into an EJB Module

Here are some general guidelines for deciding how many enterprise beans to package in a single EJB module. (For details, refer to the documentation for the Java 2 Platform, Enterprise Edition.) You might want to package your beans for any of the following results.

• Maximum reusability. If one enterprise bean is highly reusable, you might package it in its own EJB module. When the application is assembled, this module can be combined freely with other modules, to supply only the functionality that the application needs and to keep the size of the application down.

You should group into one module any beans that are most likely to be used together. For example, all CMP beans that were built in the EJB 2.0 environment and that have relationships between them must be in the same module.

• Maximum ease of assembly. The application assembler has less work to do if you package in one module all the enterprise beans an application needs, or at least all the beans in a chunk of the application. This can be an effective approach if reusability isn't an issue.
• A balance between reusability and ease of assembly. For a J2EE application of moderate size, you can probably group any related or closely coupled enterprise beans in one module, and any singly reusable beans each in its own module. Good candidates for grouping are beans with related functionality, dependencies on each other, circular references, or common security profiles.

Considering When to Create an EJB Module

If you are going to use the IDE's testing feature on a CMP bean, consider whether you want to create the bean's EJB module first and use it in testing, or wait until after you have tested the bean.

The testing process creates an EJB module for you. This is not a module you can deploy in production, but one that lets you test your CMP bean's code and all its deployment settings. You might save time by running your CMP bean through the testing process, finding out how the properties you set there work, and afterward replicating those settings in a "real" EJB module that you generate for production purposes, following the instructions in this section.

Or, if you would rather not do the process twice, you can create a production EJB module according to the instructions in this chapter and substitute it for the module that the testing feature provides.

For information on testing enterprise beans, see Chapter 9.

Putting Enterprise Beans in an EJB Module

To create an EJB module around a single enterprise bean, do as follows:

1. In the Explorer window, right-click the bean's logical node and choose Create New EJB Module.

2. In the New EJB Module dialog box, rename the module if necessary.

3. Select a location for the module from the tree view of your filesystem.

4. Click OK.

To create an EJB module around multiple cooperating enterprise beans, follow the steps above, but use the Control or Shift key to select at the same time all the beans you want in the module.

Another way to create an EJB module around several beans is to right-click the beans' Java package and choose New All Templates. In the New wizard, expand the J2EE node and select EJB Module. The IDE creates a new, empty EJB module in the package. Right-click the module node and choose Add EJB. In the file chooser that appears, use the Control or Shift key to select all the beans you want to include in the EJB module.

See the contents of the module by expanding its node in the Explorer.

[ D ] 

If you need to add one enterprise bean to a module you've already created, do as follows:

1. In the Explorer window, right-click the EJB module's node and choose Add EJB.

A file chooser appears, showing a tree view of your filesystem.

2. Select an enterprise bean from the tree view.

3. Click OK.

Setting Database-related Properties for CMP Entity Beans

The server-related properties for a CMP entity bean are provided at the level of the EJB module.

FIGURE 8-4 shows the Sun ONE AS tab for an EJB module called EJBModule_Customer. This EJB module, as you will see a little later, contains several related CMP beans.

 FIGURE 8-4 Sun ONE AS Tab's Properties for an EJB Module Containing CMP Beans

[ D ]

In a CMP bean's Sun ONE AS tab, you can edit the following properties:

• CMP Resource. Specify the actual name of the data source whose tables are represented by the CMP entity bean or beans in the EJB module. An example is shown in FIGURE 8-5.

 FIGURE 8-5 How to Specify a CMP Bean's Data-Source Properties to Sun ONE Application Server 7

[ D ]

• Notice how the PointBase database is referred to.
• After typing the password, press the Enter or Return key.

• Mapped Security Roles. You can specify resource principals (that is, users who are authorized to access the database) at the level of the EJB module or the J2EE application. The editor for this property lets you add or delete principal names and group names.

Understanding the Application Server's Generated SQL

Sun ONE Application Server 7 automatically generates its own SQL to handle your CMP beans' queries to the database. Ordinarily, you don't need to be concerned with those SQL statements.

However, it's possible for your application to use a CMP entity bean that was created in the EJB 1.1 environment, or a CMP bean that was created using an earlier version of the Sun ONE Studio IDE. Or, you might have based a CMP bean in your application on a bean class of version 1.x (for details on creating such a CMP bean, see Chapter 4).

If your application contains such CMP beans, you can treat them the same as you do EJB 2.0 CMP beans, with one important change. You need to go to the server's generated SQL and adjust a statement relating to the bean's finder or selector methods. For these methods of CMP 1.1 beans, Sun ONE Application Server 7 uses an extended version of the Java Data Objects query language (JDO QL).

The application server exposes that query language in the property sheet for the CMP 1.1 bean's finder method. Look in the Sun ONE AS tab for properties relating to this method.

---

Note - Be sure that none of your beans (tables) or their fields (columns) have names that are reserved words in SQL.

---

For details, refer to the documentation for Sun ONE Application Server 7.

Adding Transaction Attributes to an EJB Module

Transaction attributes tell the EJB container how to control a CMT bean's transactions. In a session bean that manages its own transactions (a BMT bean), you must explicitly code the bean's transactions. In a CMT bean, you include no explicit code for transactions; instead, you let the container control them based on transaction attributes you assign to your bean's methods.

By default, the IDE sets all bean methods to use the Required attribute. You can assign different transaction attributes at the bean level or at the method level. For example, if you don't want a particular method to be included in the context of a transaction, you can change that method's attribute from Required to Not Supported.

The transaction attributes are stored in the deployment descriptor, and they can be edited using the EJB module's property sheet. Before an EJB module that contains CMT beans is assembled into an application, you should make sure that the appropriate transaction attributes are specified for that module.

When you change a transaction attribute for an individual bean or for a method in a bean, the attribute is changed only for execution within that EJB module. The bean's source code has not been changed. If you reuse that bean within another EJB module, you can apply a different set of transaction attributes.

To change a CMT bean's transaction attributes within an EJB module, do as follows:

1. In the Explorer window, right-click the bean's EJB module and select Properties.

In the Properties tab, notice that the Transaction Settings field displays the value Container-transaction.

2. In the Properties tab, click the Container-transaction field, and click the ellipsis (...) button.

The Transaction Settings dialog box appears. Notice that the larger panel displays the module's enterprise beans that use CMT, each bean with a transaction attribute that applies to the entire bean.

[ D ] 

• To change a bean's transaction attribute, select the bean and select another item from the Trans-attribute combo box. The new attribute appears beside the bean's name in the larger window.
• To change a particular method's transaction attribute, expand the bean, select the method, and select another item from the Trans-attribute combo box. The new attribute appears beside the method's name in the larger window, as shown next. Notice that the bean's other methods display no transaction attribute unless the default attribute is overridden.

 

While you're working in the Transaction Settings dialog box, you can take the opportunity to provide the application assembler a description of the transaction settings for individual beans or methods in the module. For example, you might want to explain why you've changed a particular transaction attribute in this EJB module.

3. Click OK when you're finished with transaction attributes.

Changing EJB References Within the EJB Module or Application

In Specifying EJB Local References and Specifying EJB References, you saw how references between enterprise beans are declared at the level of the individual bean. Those references also can be overridden as follows:

• If the beans are in the same EJB module, you can override the references at the level of the EJB module.
• If the beans are in different EJB modules but within the same application, you can override the references at the level of the application.

This feature is handy if, for example, you want to package a particular enterprise bean in three different EJB modules to be used variously by one or more applications.

To use this feature, you must provide the EJB module (or application) two or more enterprise beans whose interfaces are the same. The feature works for local, remote, or local and remote interfaces, but the beans' interfaces must be identical, while the bean classes or properties (deployment information) can differ.

Overriding a Reference at the Module Level

To override a bean reference within the EJB module, do as follows:

1. In the Explorer window, right-click the bean's EJB module and select Properties.

2. Click the applicable references field (EJB Local References or EJB References) and then click the ellipsis (...) button.

The appropriate property editor appears.

3. Find the enterprise bean whose reference you want to override and click the Override checkbox.

4. Click the Override Value field.

Below the Override Value field appears a combo box containing the names of the enterprise beans you can select from. An example is shown in FIGURE 8-6.

 FIGURE 8-6 EJB Local References Property Editor, Showing an Example of Override Selections for an Enterprise Bean's Local References

[ D ]

5. Select the reference you want the enterprise bean to use, and click OK.

Overriding a Reference at the Application Level

To override a bean reference at the application level, do as follows:

1. In the Explorer window, right-click the bean's application and select Properties.

2. Click the applicable references field (EJB Local References or EJB References) and then click the ellipsis (...) button.

The appropriate property editor appears.

The property editors for EJB references and EJB local references are the same at the module and application level. Continue with the same steps as described in the previous section.

Adding Extra Files to an EJB Module

When you select an enterprise bean and create an EJB module around it, or when you add enterprise beans to an EJB module, the module's class closure feature takes care of finding and including all of the bean's source code, including helper classes.

Look at the classes included in a module as follows:

1. In the Explorer window, select the EJB module.

2. Right-click and select Calculate EJB JAR Contents.

A window opens to display all the included classes.

However, in a few cases, class closure might not pick up all the files you want in the module. For example, you might want to add an image file from elsewhere. You can add extra files by hand.

Add a file to an EJB module as follows:

1. In the Explorer, display the property sheet for the EJB module.

2. Click the Extra Files field and then the ellipsis (...) button.

The Extra Files property editor appears.

3. In the Source pane, select a file and click Add.

The file appears in the Files To Be Added pane.

4. Click OK to add the file.

When you deploy the EJB module, this file is included in the EJB module.

Creating an EJB JAR

An EJB module is a standard JAR file (see Creating and Configuring an EJB Module for more discussion). An individual EJB module can be deployed to an application server. Or, you might want to hand off an EJB module to another part of the organization for application assembly. You can create an EJB JAR file in which to export the module and its contents for use by the assembly people.

Create an EJB JAR file to house an EJB module as follows:

1. In the Explorer window, select the EJB module.

2. Right-click the module node and select Export EJB JAR File.

The Specify Location and Application Server Type window appears.

3. Accept the default location or navigate to another place you want the resulting JAR file to live.

4. Select the appropriate server in the Application Server Type field.

5. Specify which types of files to include: all files or just JAR files. Then, accept the resulting JAR file name or specify another.

If you select All JAR files, the resulting JAR file appears in the large pane. Select it and its file name appears in the File Name field. Specify another name here if you wish.

If you select All Files, all the files in the folder appear in the large pane. Select a file to export, renaming the result unless you want to replace the original file.

6. Click Export.

The Output Window appears and shows you the progress as the module and its contents are compiled. Notice any error messages in this window.

After the EJB JAR file has been created, you can still adjust the module or its contents for use in this or another EJB JAR file.

One or more EJB modules can be placed in a J2EE application and deployed. For details on assembly and deployment, refer to Building J2EE Applications.

---

Creating a J2EE Application

When you have one or more EJB modules containing all the enterprise beans that will be needed to produce a desired result, you are ready to create a J2EE application around all the components. Normally, what is deployed on an application server is an application containing one or more EJB modules and one or more web modules.

The IDE automatically generates an EAR file for each J2EE application. The EAR file is the portable archive of the application's contents, and it includes a deployment descriptor for the application as a whole. You can separately configure the properties on the application.

For details about assembling EJB modules and other types of modules into an applications and for details on their configuration, refer to Building J2EE Applications.