Packaging EJB Components

Packaging EJB Components involves packaging the enterprise beans and Java files. Use the Package Tool in Studio to package ejb components explicitly. EJB modules in Studio act as the JAR and contain all ejb components to be assembled.

Adding a bean or making any changes in the Bean Properties dialog box, always reflect the changes in the added bean. However, if you change the properties of the bean inside a JAR, the changes are not affected in the bean.

Open the Package Tool using Tools > Package from the main menu. Click on JAR > New, to create a JAR.

The left window which displays a tree of all Enterprise JavaBeans present in the opened JAR and

The right window that displays the information corresponding to the tree node selected.

The deployment descriptor is initially populated/developed based on the information provided during bean creation and generation of interfaces by the Bean Wizard and the Interface Wizard respectively. The deployment descriptor for the EJB components is stored as META-INF/ejb-jar.xml. For each enterprise bean, the ejb-jar file must include the following class files:

Bean class

Home and Remote Interfaces

Primary key class, if the bean is an entity bean

Adding EJB or Helper Classes

Select Enterprise JavaBeans from a list of all Enterprise JavaBeans available on the active desk to add to the JAR. If the bean being added to the JAR is a CMP 2.0 entity bean and has relationships with other CMP 2.0 entity beans, then related beans to be added to the JAR.

The Package Tool picks up all the custom classes referred in the home and remote methods either as arguments or as return types, and all the custom classes that are fields of a CMP bean. The JAR tool picks up any classes defined in the home or remote interfaces like exceptions, value objects and other referred beans. The classpath of the Source Root of the bean affects this operation. The tool will add only those classes that are found in the classes directory of the Source Root. Any classes that are found in either the system classpath or the user classpath are not added to the archive.

Adding the Bean classes displays a table on the right side panel and displays files (Home Interface, Remote Interface and Bean class) associated with the Bean.

Resolve the Enterprise JavaBeans environment before packaging it. To specify a parameter, simply click on it. The parameters include:

Security Roles References

References

Method Permissions

Transaction Attributes

Environment Attributes

Container Managed Fields

Abstract Persistence Schema

We recommend that you set these parameters using the Bean Properties Dialog, so that when you move the bean around, all its properties are always associated with the bean and get added to the JAR with the bean.

This command helps add the helper class files used by the beans present in the JAR. "Select Files to Add" dialog prompts for the following details to be filled before the files are added to the JAR:

Base Directory: Base Directory is the directory where the classes are located. For example, if the classes com/wombat/* are placed in c:/myclasses/com/wombat/*, then c:/myclasses is the base directory

Recurse: Enabling this option browses through the sub-directories and adds the matching files. This option is by default enabled

Filter: Type the filter to be implemented while searching for the files. Once the filter has been decided click on Search. This filters all the unwanted files and displays a list of all files available with the specific requirements. For example,

Target Directory: The folder under which the files selected are to be added. This is optional. Target Directory is appended to the path by which the files get added. For example, if the path of the selected file is wombat/Foo.class, then setting target directory to com makes the final path to com/wombat/Foo.class in the JAR. Not selecting a target directory adds the files under the folder where the right click was implemented

Add: Selecting all the files to be added and clicking on Add places the selected files in the Selected Files box.

Repeat the process as many times as required. Clicking on OK adds all the files in the target directories.

This lists all the beans that can be removed and clicking on OK removes the bean from the JAR. Removing a bean may cause the other beans in the JAR to get affected. Classes of the removed bean might be needed by some other beans to load them when the Java archive opens. It is important to verify that the Java archive has been correctly formed after a remove operation. If the JAR is closed and then re-opened it will point out all the affected beans, if any. These affected beans have to be then added back to the JAR.

If the beans in the JAR are CMP 2.0 entity beans and have relationships with other CMP 2.0 entity beans, then removing one bean will cause other related beans to be removed.

Updates the home interface, remote interface, bean classes, static files like and the primary key if it exists, XML entries in the JAR. A bean is considered to have changed if any of its classes (Home, Remote, PK, Bean) have been changed (time stamp check) since the last update to the JAR. The Update tool always refreshes the XML details inside the JAR with the corresponding details from the bean properties except all the deployment time information (like O-R Mapping). All settings must be made in the Bean Properties dialog box. Settings made only at the JAR level will be lost on an update. XML Updation happens on all beans and is not time-stamp based.

Files other than beans are saved with their absolute path. A time stamp based update is used to update the JARs, which makes the updating faster in most scenarios.

Updating a Java archive comprises first locating the beans and files on the desk and the file-system and if they need to be updated, the latest files are added to the JAR. A log of update operations is available on the Update Tab in the Output area of Studio. This log shows normal messages in black, updating messages in green and any failures or errors in red. Usually a remedial measure is also provided in the case of errors. A progress bar indicates the progress of the operation.

Choosing Update brings up a dialog box with a progress bar. All the updating messages are displayed here. To stop updating the JAR, click on Cancel. Studio in the meantime can be used as usual but the JAR being updated cannot be opened. If the package names of the above are changed, then the changed beans are not updated.

For a bean to be located correctly on the desk, it should have been added to JAR, else the bean cannot be located. This scenario is most likely to happen when the JAR was not created using Pramati Studio 3.0. Note that JARs created using earlier versions of Pramati Studio also do not have this information and will not get updated in version 3.0. This information might also get out of synch with the desk's state if you move the bean from the original Module where it was located. The solution is to re-add the entry into the JAR. This will re-create the update information.

Saving the JAR

Closing the JAR

Tools > Package > Jar > Close closes the current JAR. The Jar is saved before closing.

Reverting the JAR

Using the Bean Panel

Clicking on the bean name in the JAR brings up a panel on the right side of the dialog box. The following properties are displayed in the Bean section of the panel:

Display Name: The name with which the Bean is displayed. This can be edited

EJB Name: The unique name with which the bean is represented in the JAR. This can be edited

Home Class Name: The name of the home class of the bean

Remote Class Name: The name of the remote class of the bean

EJB Class Name: The name of the EJB Class of the bean.

The Details section of the panel, the Bean Type displays the type of the bean. The selection is based on the following criteria:

If the bean type is session then the next property to choose from is Transaction. Here you can choose from two types, Container Managed and Bean Managed.

If the bean type is entity then, select Primary Key Class. The primary key is selected here. You can choose from the options Non Compound and Compound.

Select `Reentrant' option if the bean requires loop backs in the same transaction context.

The types of references can be specified for a bean are described in the following sections.

EJB References

The bean provider uses EJB References to refer to the homes of other enterprise beans. During deployment the EJB references are bound to the enterprise bean homes in the target operational environment.

Name: the name by which to look up the bean. The name is then used in the enterprise bean code

Type: Select the expected type of the bean here

Remote Reference: The home class and remote class of the Remote References are selected here. These references specify the expected Java types of the referenced enterprise bean's home and component interfaces.

Home Class Name: Select from the available home classes.

Remote Class Name: Select from the available remote classes.

Local Reference: The home class and remote class of the Local References are selected here. These references specify the expected Java types of the referenced enterprise bean's home and component interfaces.

Local Home Class Name: Select from the available local home classes in this field.

Local Class Name: Select from the available local classes in this field.

JNDI: This field appears neither for the ejb-jar.xml file, nor for the JAR. Selecting the references automatically selects JNDI name for the reference to be created. The JNDI name is used to link an ejb reference to the target enterprise bean. This is the name of the target enterprise bean, and is unique.

For J2EE, Studio does not support EJBContext.getEnvironment() method. All EJB references are declared using the EJB-ref elements of the deployment descriptor. The scope of the EJB reference is limited to the bean declaring the reference.

Resource References

Any resource that the bean uses can be specified here. Each resource reference added to the JAR describes a single resource manager connection factory reference. These resource references are then bound to the actual resources during deployment.

Clicking on Add adds a new row to the resource reference panel. Edit the following information in the row:

Reference Name: The name of the reference resource with which it is identified

Type: Select from the types available in the Resource Type column. The type contains the Java type of the resource manager connection factory that the enterprise bean code expects

Authentication: This field indicates whether the enterprise bean code performs resource manager sign-on programmatically, or whether the Container signs on to the resource manager using the principal mapping information supplied, during deployment. The Authentication can be set as either Application or Container and indicates the sign-on responsibility

Sharing Scope: This field indicates whether the connections to the resource manager, which are obtained using the Resource reference entry, can be shared or not. Select the value as either Shareable or Unshareable from the combo box

Security Role References

The Security Role references cannot be added until the Security Roles are added in the JAR. Declaring the security roles references allows the security role references to be linked to the JAR level security roles, which have already been defined. Use the Add button to add the references and Delete button to delete them. Enter the following information to create the Security Role References:

Role Name: Describe the role name in this field. The name must be the security role name that is used as a parameter to the isCallerInRole (String role-Name) method

Role Link: Select from the existing security roles to which the reference has to be linked to

Resource Environment References

A resource environment reference is a special entry in the enterprise bean's environment. The resource environment references are bound to administered objects in the target operational environment during deployment. Adding Resource Environment entries allow the ejb-jar consumer to discover all the resource environment references used by the enterprise bean.

To add resource environment entries to the JAR, use the Add button. The two mandatory fields to be described are:

Reference Name: Enter the Reference name of the resource environment in the field. This specifies the resource environment reference name, its value is the environment entry name used in the enterprise bean code

Type: Enter the resource environment reference type or select from the available types in the combo box. This field specifies the expected type of the referenced object

Note: The resource environment reference is not accessible to other enterprise beans at runtime, and other enterprise beans may define resource environment reference elements with the same resource environment reference name without causing a name conflict.

Defining Transaction Attributes

A transaction attribute is a value associated with a method of a session or entity bean's home or component interface or with the on Message method of a message-driven bean. Use the Transaction Attributes panel to set transaction attributes of the beans in the JAR. These attributes define responsibilities of the container for managing the invocation of a business method:

NotSupported: When a method is invoked, the current transaction associated with the thread is suspended and the method is executed. The suspended transaction is renewed after the method is executed

Required: When a method is invoked, it must be associated with another transaction context. If there is no current transaction context, the container automatically starts one

Supports: If the client calls with a transaction context, the container takes the Required attribute. If the client calls without a transaction context, the container takes the NotSupported attribute

RequiresNew: When a method is invoked, current transaction context is suspended and a new one started before the method is executed

Mandatory: A transaction context is mandatory for the thread when it picks up the method

Never: No transaction context must be used when the method is executed.

For entity beans that use EJB 2.0 container-managed persistence, only the Required, RequiresNew, or Mandatory transaction attributes should be used. Entity beans can optionally use NotSupported, Supports, and Never transaction attributes, but these transactions will not be portable.

Interface: The component interface type of the bean is displayed here. This field cannot be edited

Method Name: The method names of the session or entity beans or message-driven-beans are displayed here

Transaction Attribute: Select from the available transaction attribute types in the combo box. The transaction attributes available in the combo box depends on the type of bean for which it is being set

Set Transaction Attribute: To set multiple methods as having the same transaction attribute, select the required method names in the panel, and select from one of the transaction attributes in the Set Transaction Attribute combo box

Setting Security Roles

A security role is a semantic grouping of permissions that a given type of user of the application must have in order to successfully use the application. The application assembler defines Security Roles for a JAR composed of one or more Enterprise JavaBeans.

A security role needs a name (example: administrator) and a description (example: full access). More than one role can be defined.

The application assembler defines method permissions for each security role declaratively in the deployment descriptor.

At the deployment stage the deployer assigns principals, defined in the target operational environment, to the security roles defined inside the JAR.

Use the Add button to add a security role in the panel and Delete button to delete the selected role. The role name can be edited.

Defining Method Permissions

Method Permission is a permission to invoke a specified group of methods of the enterprise beans' home and component interfaces. Each security role in the JAR is assigned to a method permission in the deployment descriptor.

Clicking on the Method Permissions panel on the left side of the tree displays the list of method permissions with the following columns:

Unchecked: Checking this field indicates that the specific method should not be checked for authorisation

Exclude List: Checking this field indicates that the specific method should not be called. During deployment, the enterprise bean's security is configured such that no access is permitted to any method contained in the exclude-list. Checking this field makes the entire row color - grey to show that the method cannot be accessed once it is excluded

Interface: The type of the interface of the method is displayed here. This field is not editable

Method Name: The names of all the listed methods are displayed in this field. This field is not editable. The panel also has Security Role fields after the Security Roles are added to the JAR. Check the Roles to indicate that the method should be checked for authorization

Run As: Enter the Run As element in this field. This is usually designated by a logical role-name, which corresponds to one of the security roles defined in the deployment descriptor, since the security environment of the operational environment is not known during assembling.

During deployment, this is then assigned to a security principal defined in the operational environment to be used as the principal for the run-as identity. Instead of selecting a security role, you can also select the `use-caller-identity' element. In this case, the principal associated with the calling client is returned for the getCallerPrincipal() method.

Defining Environment Entries

Declare all environment entries accessed from the EJB code. An environment entry is scoped to the bean. This means:

The environment entry cannot be accessed from other enterprise beans at runtime

Other enterprise beans can use same named environment entries without causing a name conflict

Clicking on Add adds a new environment entry and the following fields need to be edited in the environment entry row:

Name: Enter the environment entry name in this field relative to the java:comp/env context

Value: Enter the environment entry value name in this field

Type: Select from the available Java types for the environment entry value in this field. The environment entry values may be one of the following Java types: String, Character, Integer, Boolean, Double, Byte, Short, Long, and Float

To delete an environment entry from the JAR, select the row and click on the Delete button.

Defining Container Managed Fields

If the enterprise bean is an Entity bean with container-managed persistence, the Bean Provider must specify the container-managed fields using the cmp-field elements.

Field Name: The name of the field

Is Container Managed: All fields that are container-managed have a right tick and the fields that are not container-managed have a cross tick. Both fields in the panel are not editable

Container Managed Relationships Data

This panel displays the container-managed relationships of the entity 2.0 beans with container-managed persistence.

Bean 1: This contains the EJB name of the bean for which the relationship has been defined. This field is not editable

Relationship: The multiplicity-navigability icon defining the type of the relationship is displayed in this field. This field is also not editable

Bean 2: The EJB Name of the second bean in the relationship is displayed here. In this case of a 1-> n relationship the dropdown dialog allows to select from all CMP2.0 beans in the module

Cascade Delete: Check this option if you want to cascade delete the relationship roles. The cascade delete option specifies that, within a particular relationship, the lifetime of one or more entity beans is dependent upon the lifetime of another entity bean. The cascade delete option can only be specified for relationships in which the multiplicity of the source role is One

Finder/Select Methods

This panel is used to specify EJB QL finder or select queries for the entity bean and to specify SQL Queries when the bean is a CMP 1.1 entity bean. The following are the fields in the panel:

Method Name This field specifies the name of a finder or select method in the entity bean's implementation class. This field is not editable

Result-Type Mapping This field is displayed only for CMP 2.0 entity beans and is optional. It can only be present if the query method specifies a select method that returns entity objects on their collection. The default value for the result-type-mapping element is Local

Query clicking on this field brings up the EJB QL window, depending on whether the bean chosen is a CMP 2.0 or CMP 1.1 entity bean

OR Mapping: Gives OR Mapping details

Viewing XML Files

The ejb-jar.xml file corresponding to the JAR file can be viewed in the XML node.