Chapter 8 Creating Enterprise JavaBean Components

Importing Enterprise JavaBeans

Jaguar Manager supports two methods of importing Enterprise JavaBeans:

From an EJB-JAR file An EJB-JAR file contains the implementation classes, interface classes, and deployment descriptor for one or more Beans. You can use a Java development tool such as Sybase PowerJ to define and develop Beans and create an EJB-JAR file. You can import JAR files in the EJB 1.0 format or the EJB 1.1 format. Jaguar Manager reads the JAR file and creates a package containing a component for each Bean in the JAR file.
From EJB class files Jaguar Manager can import component and method information from Java class files. Use this method if you have created a Bean's interfaces and implementation class, but have not created a deployment descriptor. You will need to manually configure properties that would otherwise be read from the deployment descriptor.

PowerJ deploys Enterprise JavaBeans directly to Jaguar If you are developing in PowerJ, use the Enterprise JavaBean Deployment Wizard to install EJB components in your Jaguar server. If using another IDE, use Jaguar Manager to import the Bean as described below.

Finder method return values Finder methods in an entity Bean's home interface can return java.util.Collection or java.util.Enumeration. All EJB components defined within one Jaguar Manager package or one EJB-JAR file must use the same type for finder method return values.

Importing an EJB 1.1 JAR file

Start Jaguar Manager if it is not already running, and connect to the server where you want to install the component.
Highlight the top-level Packages folder. Choose File | Deploy | EJB 1.1 JAR.
Select the "Prompt before overwriting existing objects" option if you wish packages and components with the same name to be overwritten without confirmation.
Select Automatically generate EJB stubs and skeletons if you want stub and skeleton files to be generated and compiled during the import process.

Home interfaces that use java.util.Enumeration Do not select the Automatically generate EJB stubs and skeletons option if entity Bean finder methods return java.util.Enumeration. Instead, generate Stubs and Skeletons after the import completes, and select the JDK 1.2 option.All entity Bean finder methods within one EJB JAR file must return the same list type, either java.util.Collection or java.util.Enumeration.
Enter the path to the JAR file and click Next.
Jaguar Manager creates a new package that contains a component for each Bean defined in the JAR file, printing status messages and warnings to the Deploy Wizard. The new package has the same name as the EJB JAR display name. If there is no display name, the new package has the same name as the JAR file. For each Bean in the EJB-JAR, Jaguar creates an EJB component with the same name as the ejb-name element in the EJB-JAR deployment descriptor.

Home names for imported EJB components Jaguar sets an imported Bean's home name to the Jaguar default, package/component, where package is the Jaguar Manager package name, and component is the Jaguar Manager component name.

You may need to configure the following settings in the Component Properties dialog box before running EJBs:

For Beans that use container-managed persistence, the settings described in "Persistence for entity components".
Role mappings and method-level permissions, described in "Configuring role references and method permissions".
Resource references, described in "Configuring resource references".
EJB references (to components that are not installed with the JAR file), described in "Configuring EJB references".
Environment properties, described in "Configuring environment properties".

Other settings have been configured by the Deploy Wizard.

Use the status dialog as a to-do list In the deployment status dialog box, Jaguar Manager display warnings for each setting that requires further attention before running the application. You can copy and paste this text to a text editor to use as a to-do list.

Importing an EJB 1.0 JAR file

This feature is provided for backward compatibility with previous Jaguar versions and any EJB 1.0 servers. To import the JAR file:

Start Jaguar Manager if it is not already running, and connect to the server where you want to install the component.
Highlight the top-level Packages folder. Choose File | Deploy | EJB 1.0 JAR.
Enter the path to the JAR file, and optionally enter a package name. If you do not specify a package name, Jaguar installs the components into a package with the same name as the base JAR file name. For example, components imported from EmploymentAuth.jar are installed to package EmploymentAuth.
Jaguar Manager displays the Beans that are defined in the JAR file. Select and configure Beans for deployment as follows:
1. In the left column, select the check boxes for each Bean that you want to deploy, or click Select All to deploy all Beans.
2. Highlight each selected Bean, then click Configure. Verify the deployment descriptor properties described in "EJB 1.0 deployment descriptor properties".
When all selected Beans have been configured, click Deploy.
Map role names that were read from the deployment descriptor to role names that exist in Jaguar Manager. Names in the left column are used in the deployment descriptor; these may not match existing roles in Jaguar Manager, or may match roles that do not agree with the access control requirements intended for the Bean. For each name in the left column, assign a role name using the drop-down list in the right column.
Map run-as identity names that were read from the deployment descriptor to identity names that exist in Jaguar Manager. You can configure these mappings now or later. To configure now, for each name in the left column, assign an identity name using the drop-down list in the right column. To configure after deployment completes, use the Run-As Mode tab in the Component Properties or Method Properties dialog.
Optionally generate stubs and skeletons for the Bean. You must generate stubs and skeletons before the Bean can run, but you can do so after deployment completes. If generating now, specify a code base for the generated files. Sybase recommends the Jaguar java/classes subdirectory, which is the default.

Importing EJB class files

Jaguar Manager can import component and method information from Java class files. Use this technique if you have created a Bean's interfaces and implementation class, but have not created a deployment descriptor. You will need to manually configure properties that would otherwise be read from the deployment descriptor afterwards.

Before importing class files Verify that the code base under which the class file is deployed is specified in the CLASSPATH environment variable, as inherited by the Jaguar Manager process. By default, the Jaguar java/classes and html/classes subdirectories are in the Jaguar Manager CLASSPATH. You must manually add any other location by setting the CLASSPATH environment variable and restarting Jaguar Manager.Create a package to contain the component if necessary.

Import EJB class files as follows:

Specify the package to install the component in as follows:
1. Double-click the Packages folder to expand it.
2. Highlight the package to which the component will be added.
Choose File | New Component from the menu.
In the Component Wizard, select Import from EJB Class File, and click Next.

Enter the component name and EJB class and interface names as follows:

Component name The name of the component to be created in Jaguar Manager, for example, FinanceBean.

Component type Choose one of the following to match your implementation:

Type	Description
JaguarEJB::StatelessSessionBean	A stateless session Bean
JaguarEJB::StatefulSessionBean	A stateful session Bean
JaguarEJB::EntityBean	An entity Bean with Bean-managed persistence.

Remote interface The full path to the Java class file that contains the Bean's remote interface.
Home interface The full path to the Java class file that contains the Bean's home interface.
Bean class name The full path to the Java class file that contains the Bean's implementation class.
Primary key class If defining an entity Bean, enter the full path to the Java class file that contains the Bean's remote interface. If defining a session Bean, leave blank.

Jaguar Manager displays the Component Properties dialog box. The Component's type and Java classes have been filled in by the importer. Specify values for the remaining properties before running the Bean.

EJB 1.0 deployment descriptor properties

When importing Beans from an EJB-JAR file, Jaguar Manager displays the settings from each Bean's deployment descriptor and allows you to make changes before the information is recorded in Jaguar's configuration repository.

The information is displayed in the Deployment Configure dialog box, which contains the tabs listed below. Changes that you make in the Deployment Configure dialog box do not affect the settings recorded in the EJB-JAR file, only the settings to be recorded in Jaguar's configuration repository.

After deploying an EJB component into Jaguar, you can change these properties using the controls in the Component Properties dialog box.

BeanName tab

The leftmost tab defines the general settings for the Bean. The Bean's implementation is dependent on the Bean type and the Java class names specified here. You may change the EJB Home Name if you wish. Do not change other settings unless the deployment descriptor was prepared incorrectly.

EJB Class The Java class that implements the Bean, specified in dot notation.
Home Interface Class The Java home interface name, specified in dot notation.
Remote Interface Class The Java remote interface name, specified in dot notation.
EJB Home Name The name suffix used by client applications to look up the Bean's home interface in the Jaguar naming service. The full name consists of the server's initial naming context followed by a slash (/) and the Bean's home name.
EJB Session Type Session Beans only. Whether the session Bean is stateful or stateless.
EJB Primary Key Entity Beans only. The Java class that specifies primary key values for the entity Bean, in Java dot notation.
Reentrant Entity Beans only. Whether the Bean is reentrant. A reentrant Bean can participate in loopback call sequences, which are call sequences where one of the Bean's methods calls another component which in turn calls a method in the calling Bean instance. Most Beans are not implemented to support reentrancy. Do not enable this option unless the Bean developer has verified that the implementation allows it.

Changing general properties after deployment After deployment completes, use the General tab in the Component Properties dialog to view or modify these properties. The Reentrant property for an entity Bean is specified with a check box on the Instances tab.

Access Control tab

This tab configures the users that can call the Bean's methods. If roles are listed for a method name, only users in that role can execute the method. The displayed role names are those listed in the Bean's deployment descriptor. The displayed roles may not exist in Jaguar Manager. If they do not, the Deployment Wizard prompts you to map these role names to existing Jaguar Manager roles after all selected Beans have been configured.

Changing Access Control properties after deployment completes After deployment completes, you can configure access control for the EJB component and its methods in Jaguar Manager. To change access control for the component, use the Role Membership folder below the component's icon. To change access control for a method, expand the Interfaces folder below the component icon, then expand the icon for the interface that contains the method. Add or remove roles using the Role Membership folder.

Control Descriptor tab

Use this tab to configures settings that control how Jaguar executes the Bean's methods:

Tx Attribute Determines how the Bean participates in transactions managed by Jaguar. See the Jaguar CTS Programmer's Guide for more information.
Tx Isolation If the Bean participates in transactions, determines the transaction isolation level. See the Jaguar CTS Programmer's Guide for more information.

Run-as Mode Determines the user name and password used when the Bean calls other Jaguar components installed in the same server or server cluster. The choices are:

Option	Description
Client	Use the client's username and password.
System	Use the system user name and password. The system account effectively belongs to any role, and can execute any method on any component that is installed in the same server or cluster.
Specified	Use the user name and password associated with the identity name specified in the Run-as Identity column.

Run-as Identity If the run-as mode is set to Specified, an identity name for calls to components installed on same the Jaguar server or server cluster. The identity name read from a Bean may not exist in Jaguar. If it does not, the Deployment wizard asks you to map this identity name to a identity listed in the Jaguar Manager Identities folder after all selected Beans have been configured.

Changing Control Descriptor properties after deployment completes After deployment completes, you can configure transactional properties on the Transactions tab in the Component Properties dialog box. Use the Run-As Mode tab to view and edit the run-as mode and run-as identity settings.

Environment tab

Use this tab to specify Bean properties required by the implementation. For example, there might be a property specifying a JDBC database URL for queries to a remote database. At runtime, the Bean accesses these properties using the EJBContext.getEnvironment() method. The tab initially displays the properties and values defined in the Bean's deployment descriptor. You can modify, add, and delete properties as follows:

To do this	Do this
Modify a property	Edit the value in the right column.
Add a property	Click Add. A blank row appears. Type a property name and a value for the property. Property names beginning with com.sybase are reserved for Sybase internal use.
Delete a property	Highlight the property name or value column, then click Delete.

Changing Environment properties after deployment completes After deployment completes, you can configure environment properties using the All Properties tab in the Component Properties dialog box. The environment properties are listed in addition to the com.sybase.jaguar.component properties used internally by Jaguar.