Chapter 8 Creating Enterprise JavaBean Components

Creating Enterprise JavaBeans in Jaguar Manager

In most cases it is easiest to define a Bean using one of the import methods described in "Importing Enterprise JavaBeans". However, if you prefer editing IDL to Java, you may follow the technique described here. Also, you can follow the IDL interface editing steps to edit a Bean's interfaces or primary key type for an EJB component that was created by the importer.

Creating a new EJB component from scratch:

Follow this procedure to create a new EJB component and define the home and remote interface.

Select the Jaguar Manager package that will contain the Enterprise JavaBean.
Select File | New Component.
In the Component Wizard dialog box, select the Define New Component check box and click Next.
Enter a name for the component and click Finish.
The Component Properties dialog box displays. Make the following changes on the General tab:
1. Set the Type to correspond to one of the following values:
  
  Component type
  
  To indicate
  
  EJB - Entity Bean
  
  An entity Bean
  
  EJB - Stateful Session Bean
  
  A stateful session Bean
  
  EJB - Stateless Session Bean
  
  A stateless session Bean
2. In the EJB Version field, select 1.1. (You can select 1.0, but EJB 1.1 is recommended for new development.)
3. In the Bean Class field, enter the name of the Java class that will implement your Bean, for example, foo.bar.MyBeanImpl.
4. Enter a value for the Bean Home Name field. This field specifies the name by which client applications look up the home interface. The full name consists of the server's initial naming context followed by a slash (/) and the Bean's home name.
  
  The Home Interface Class, Remote Interface Class, and Primary Key Class fields cannot be edited. These fields are set automatically after the Bean's IDL interfaces and datatypes have been defined. You can change them by changing the component's IDL interfaces and types in subsequent steps.
If you are defining a stateful session Bean, optionally switch to the Resources tab and enter a time limit in the Instance Timeout field. This value specifies how long, in seconds, that a client can hold an instance reference without making any calls. If you do not enter a value, or you specify 0, client references do not expire.
If you are creating an entity Bean, specify the primary key as follows:
1. Define the primary key type as one of the "Allowable primary key types".
2. Display the Component Properties dialog box for the component, click on the Persistence tab, and type the name of the IDL primary key type into the Primary Key field. The Persistence must be set to Component Class (the default). Leave all other fields besides Persistence and Primary Key blank. (You can optionally configure these fields to allow failover between servers in a cluster. See the Jaguar CTS Programmer's Guide for more information.)
Click OK to close the Component Properties dialog box.
If methods in your Java remote interface throw exceptions other than java.rmi.RemoteException, define equivalent IDL exceptions now. See Chapter 5, "Defining Component Interfaces" in the Jaguar CTS Programmer's Guide for more information.
Jaguar Manager has created default home and remote interfaces named package::componentHome and package::component, respectively, where package is the Jaguar Manager package name, and component is the component name.

To change the home or remote interface, follow the steps in "Changing the EJB remote or home interface".
Edit the home interface methods, following the design patterns described in "Defining home interface methods".
Edit the remote interface methods. See "Defining remote interface methods".

If portability to other EJB servers is required, use only in parameters in remote interface methods.
If creating an entity Bean with container-managed persistence, configure the persistence settings as described in "Persistence for entity components".
Optionally configure the transaction properties for each method in the home and remote interfaces, or if all are the same, configure the component's transaction properties. See "Transactions tab component properties" for more information.
If defining a version 1.1 EJB, optionally configure any references to other EJBs that are instantiated in your EJB's code. See "Configuring EJB references" for more information.
If defining a version 1.1 EJB, optionally configure any JavaMail or database connection resource references used by your EJB's code. See "Configuring resource references" for more information.
If defining a version 1.1 EJB, optionally configure role references if you plan to configure method-level permissions, or if you will call isCallerInRole in your EJB's code. See "Configuring role references and method permissions" for more information.
If defining a version 1.0 EJB, optionally configure the Run-As Mode properties for the component and methods. The Run-As Mode property is not available for version 1.1 Beans. See "Run-As Mode tab component properties" for more information.
Optionally configure environment properties as described in "Configuring environment properties".
Generate stubs and skeletons for the component as follows:
1. Highlight the component icon.
2. Choose File | Generate Stub/Skeleton.
3. Select Generate Skeletons and click Generate.
Stubs generated automatically When you generate skeletons for your component, stub source is also generated under the same code base. You do not need to select the stubs option.
Jaguar Manager generates a template for the Bean implementation class suffixed with .new, for example MyBeanImpl.java.new. Use this template as the basis for your Java implementation. Jaguar Manager also generates Java equivalents for the home and remote interfaces, and for an entity Bean, the primary key type.

If you are creating a stateful session Bean with synchronization methods, add implements SessionSynchronization to the class declaration in the implementation template, and add code to implement the methods in the javax.ejb.SessionSynchronization interface.
Compile the component source files, and make sure they are correctly deployed to the Jaguar server. See "Deploying component classes".
If you are testing the component with a Java applet, generate and compile stubs using the html/classes subdirectory as the Java code base.

Component type	To indicate
EJB - Entity Bean	An entity Bean
EJB - Stateful Session Bean	A stateful session Bean
EJB - Stateless Session Bean	A stateless session Bean

Allowable primary key types

Define an entity Bean's primary key as one of the following:

An IDL structure The structure should reflect the primary key for the database relation that the entity Bean represents. In other words, add a field for each column in the primary key. Define the structure to match the intended Java package and class name. For example, if the Java class is to be foo.bar.PK1, define a new structure PK1 in module foo::bar. See Chapter 5, "Defining Component Interfaces" in the Jaguar CTS Programmer's Guide for more information.

The name of a serializable Java class Enter the name of a serializable Java class, for example: foo.bar.MyPK.

The IDL string type Use string if the key relation has only a string column. In Java, the mapped primary key is java.lang.String.

Interoperability and key types Define your entity Bean's primary key as an IDL structure or string if other types of clients besides Java will use the Bean.

Defining home interface methods

You can add methods to a home interface using the techniques described in Chapter 5, "Defining Component Interfaces" in the Jaguar CTS Programmer's Guide. However, the method signatures in a home interface must follow the design patterns described here to ensure that the generated code works as intended.

Patterns for create methods All Beans can have create methods, which clients call to instantiate proxies for session Beans and insert new data for entity Beans.

Create methods must return the Bean's IDL remote interface type and raise CtsComponents::CreateException. Create methods can take any number of in parameters. To distinguish multiple overloaded create methods, append two underscores and a unique suffix. (This is the standard Java to IDL mapping for overloaded method names. When generating stubs for C++ and Java, Jaguar removes the underscores and suffix from the stub method name). The pattern is as shown below:

remote-interface create
(
  in-parameters
) raises (CtsComponents::CreateException);

remote-interface create__suffix1
(
  in-parameters
) raises (CtsComponents::CreateException);

Patterns for finder methods Only entity Beans can have finder methods. Clients call finder methods to look up entity instances for existing database rows. Names of finder methods typically have names beginning with find .

Every entity Bean must have a findByPrimaryKey method that matches the following pattern:

remote-interface findByPrimaryKey
(
  in pk-type primaryKey
) raises (CtsComponents::FinderException)

where remote-interface is the IDL remote interface, and pk-type is the IDL type of the primary key.

Entity Beans can have additional finder methods of two types:

Those that return a single remote interface instance and raise CtsComponents::FinderException, as shown in the pattern below:
```
remote-interface findSuffix
(
  in-parameters
) raises (CtsComponents::FinderException)
```
where remote-interface is the IDL remote interface, Suffix is a name suffix other than ByPrimaryKey , and in-parameters is a valid parameter list composed solely of in parameters.
Those that return a sequence of instances whose primary keys match a specified search criteria. The pattern is:
```
componentList findSuffix
(
  in-parameters
) raises (CtsComponents::FinderException)
```
where component is the component name, Suffix is a name suffix other than ByPrimaryKey , and in-parameters is a valid parameter list composed solely of in parameters.
Sequence types are automatically generated Jaguar Manager creates IDL typedefs defining a sequence of remote interface methods and a sequence of primary keys when you set the Primary Key field on the Persistence tab of the Component Properties dialog box. The type for a sequence of remote interface instances is componentList and a sequence of primary keys is componentKeys, where component is the component name.

Defining remote interface methods

The IDL for your Enterprise Bean's remote interface must define a remove method and the business methods implemented by the Bean.

remove methods are called by clients to delete the database row associated with an entity Bean, and to release a reference to a session Bean instance. remove methods have the following signature:

void remove
(
)
raises (::CtsComponents::RemoveException);

You can define business methods graphically or using the IDL editor window. The procedure is the same as for any other IDL interface. See Chapter 5, "Defining Component Interfaces" in the Jaguar CTS Programmer's Guide for more information.

If portability to other EJB servers is required, use only in parameters in remote interface methods.

Configuring EJB references

Your EJB can use EJB references to instantiate proxies for other EJBs. See Chapter 8, "Creating Enterprise JavaBean Clients," in the Jaguar CTS Programmer's Guide for more information.

You do not need to create references in order to invoke other EJBs from your code. However, doing so ensures that EJB references will be cataloged in the deployment descriptor if you export the EJB.

Stubs used for EJB references must be in the custom class list You must list stubs used for intercomponent calls in the custom class list for your component, as described in "The custom class list".

To add an EJB reference:

Display the EJB References tab in the Component Properties dialog box.
Click Add. A reference with default settings is created. Edit the settings as described below.

To edit an EJB reference:

If necessary, display the EJB References tab in the Component Properties dialog box. Existing references are displayed as a list with one row for each reference.
Edit the reference fields of interest as follows:
- Name Specifies the JNDI name used in your EJB's code to refer to the called EJB. The aliased name is displayed in the Link Value field. Enter the part of the JNDI name that begins with ejb/ . For example, if your code refers to java:comp/env/ejb/MyBean, enter ejb/MyBean .
- Type Choose Session for session Beans or Entity for entity Beans.
- Home The Java class name of the EJB home interface, specified in dot notation. For example, com.sybase.MyBeanHome .
- Remote The Java class name of the EJB home interface, specified in dot notation. For example, com.sybase.MyBeanRemote .
- Link Value The actual JNDI name of an instance of the specified EJB that is installed in the Jaguar server where your EJB is to be deployed. This is specified by the Home Name property in the Component Properties of the called EJB component.
To delete a reference, click anywhere in the fields for the reference of intererest and click Delete.

Configuring resource references

Resource references are used to obtain database connections, JavaMail sessions, and URL factories.

To add a resource reference:

Display the Resource References tab in the Component Properties dialog box.
Click Add. A reference with default settings is created. Edit the settings as described below.

To edit a resource reference:

If necessary, display the Resource References tab in the Component Properties dialog box. Existing references are displayed as a list with one row for each reference.
Edit the reference fields of interest as follows:
- Name The partial JNDI name used in servlet and JSP code. Use the prefix mail/ for JavaMail references, jdbc/ for data source references, and url/ for java.net.URL references. For example, if your code refers to java:comp/env/jdbc/MyDatabase, enter jdbc/MyDatabase .
- Type Choose the type of resource:
  - javax.sql.DataSource for JDBC connections. See "JDBC DataSource lookup" for more information.
  - java.mail.Session for JavaMail sessions. See Chapter 30, "Creating JavaMail" for more information.
  - java.net.url for aliased URLs.
- Authentication Container is the only option that is supported.
Specify deployment properties:
- SMTP Host For JavaMail resources. Specifies the SMTP mail server for outgoing mail.
- Connection Cache For JDBC references. The name of the Jaguar connection cache to be used for this reference.
- URL Specification For aliased URLs. The URL string, as it would be used to construct a java.net.URL instance by calling the URL(java.lang.String) constructor. URLs must contain a protocol and host address, for example: http://www.sybase.com or ftp://pub.sybase.com .

Configuring role references and method permissions

To restrict access to an EJB 1.1 component, you must configure method permissions settings as described below, or you can call the isCallerInRole Java method to restrict access. If you call the isCallerInRole Java method, you must configure role references to map names used in isCallerInRole calls to J2EE role names that are configured in the package properties.

To restrict access in an EJB 1.0 component, use the Roles facility in Jaguar Manager. See Chapter 5, "Security Configuration" in the Jaguar CTS System Administration Guide for more information.

EJB 1.1 uses a different security model than other component types EJB 1.1 component security uses method level constraints rather than the package and component Role constraints used for other component models. The Roles folder does not display for EJB 1.1 components, or for packages that contain only EJB 1.1 components. If EJB 1.1 components are installed in a package that contains other component types, the package role folder has no effect on the EJB 1.1 components.

To configure EJB 1.1 method permissions:

If necessary, define new Jaguar roles to be used by callers of the component.
Verify that J2EE roles are mapped to Jaguar roles in the properties of the package where the component is installed; check the Role Mappings tab in the Package Properties window-see "Configuring package properties ". You must map a J2EE role name for each role to be used in method permissions.
For each method that requires limited access, display the Method Properties dialog and highlight the Permissions tab. A check box displays for each mapped J2EE role in the package that contains the component. Select the check box by each role that can call the method.

To configure EJB 1.1 role references:

If necessary, define new Jaguar roles to be used by callers of the component.
Verify that J2EE roles are mapped to Jaguar roles in the properties of the package where the component is installed; check the Role Mappings tab in the Package Properties window-see "Configuring package properties ". You must map a J2EE role name for each role to be used in role references.
For each component that calls the isCallerInRole method, display the Component Properties dialog and highlight the Role Refs tab. Add or modify roles as follows:
- To add a role, click Add and edit the new entry as described below.
- To modify a role, edit the Reference Name (used in isCallerInRole calls), and choose the mapped J2EE role (configured in the properties of the package where the component is installed).

Configuring environment properties

Environment properties allow you to specify read-only data for use by an EJB. For example, you might use environment properties to tune the size of a data cache used in your implementation, or to specify the name of a log file. Use environment properties for any constant value that might change when the EJB is deployed to another server.

When coding your EJB, use JNDI to retrieve environment properties, using the prefix java:comp/env in JNDI lookups.

When you export your EJB, the deployment descriptor catalogs the environment properties used by your servlets and JSPs, as well as each property's Java datatype and default value. When the EJB is imported to another server, the deployer can override the default value for each environment property.

Environment properties for EJB 1.0 components An EJB 1.0 component can only have environment properties with datatype String, and these properties must be configured in the All Properties window. Any property name that does not begin with com.sybase.jaguar.component is considered an environment property. In source code, use the EJBContext.getEnvironment method to retrieve property values. You cannot use the JNDI InitialContext.lookup method to retrieve these values.

To add an EJB 1.1 environment property:

Display the Environment tab in the Component Properties dialog box.
Click Add. Jaguar Manager creates a new entry with default settings. Edit the settings as described below:

To edit EJB 1.1 environment properties:

If necessary, display the Environment tab in the Component Properties dialog box. A list of environment properties appears.
Edit the fields for the property of interest:
- Entry The environment property's JNDI name, relative to the java:comp/env prefix.
- Type Choose the Java datatype that matches the property value from the dropdown list.
- Value The initial or post-deployment value of the property, specified as text in a format that is valid for the specified datatype.
- Description Optionally enter a comment to explain how the property is used.

Deploying component classes

If you are creating components from scratch in Jaguar Manager, you must follow the steps in this section to deploy the component class and other classes that it depends on. If you deploy from PowerJ, PowerJ performs these steps for you. If you are using another EJB development tool that can export EJB JAR files, import the EJB JAR file as described in "Importing Enterprise JavaBeans". If you import an EJB JAR file that calls Jaguar components that are not implemented in the same JAR file, you must list the stub classes for the called components in the custom class list as described below.

Jaguar supports hot refresh of components by using a Java class loader. This feature speeds the development process by allowing you to deploy new class versions without restarting Jaguar server. Repeat the steps below to deploy new versions of your implementation.

In a production environment, you may wish to disable refresh to improve performance. See "Disabling component Refresh" for details.

To deploy EJB component classes:

Deploy the component class files, stub and skeleton files, and other classes required by the implementation to Jaguar. For example, you may need to copy stubs for user defined types and utility classes that are in your component's package.

If deploying class files, place each class in their respective java/classes package subdirectories. If deploying a JAR file, place it in the java/classes subdirectory.

The preferred code base is java/classes For security reasons, it is preferable to deploy Java components to the java/classes subdirectory or some other directory that is not accessible to HTTP downloads. Deploying to this directory also allows your component to be refreshed, and allows you to deploy classes in JAR files without reconfiguring the server's CLASSPATH environment variable. If you deploy to another location, make sure it is listed in the server's CLASSPATH environment variable.
Use Jaguar Manager to configure the component's custom class list, specifying the classes that must be loaded when your component is loaded or reloaded, as described in "The custom class list".
Use Jaguar Manager to refresh the component by highlighting its icon and choosing File | Refresh. You can also refresh the component by refreshing the package, application, or server where it is installed.

The custom class list To support component refresh, you must specify the custom class list to be loaded when a component is refreshed in the com.sybase.jaguar.component.java.classes component property. This property must be set on the All Properties tab in the Component Properties dialog box. "com.sybase.jaguar.component.java.classes" describes the syntax of this property.

The custom class list for an EJB component must contain these classes:

These packages:

com.sybase.ejb.*;javax.naming.*;javax.naming.spi.*

Stubs for all components that your component calls. If the called component's classes are loaded in a JAR file, list the JAR file name in the custom class list.
Other classes that your component loads and passes as parameters or return values for intercomponent calls, or passes to clients as method return values and output parameter values.
Classes that extend javax.naming.InitialContext or other javax.naming classes and that are called by your component.

Troubleshooting ClassCastException errors When calling javax.naming.InitialContext.lookup, if you see NamingContext exceptions with root-cause exception ClassCastException, check for the following errors:

You are casting to an incorrect type (check the class name of the object returned by lookup).
Your component has refresh enabled, and the custom class list does not contain some required classes.
Your component has refresh enabled, and calls a component that has refresh disabled or vice-versa.

Disabling component Refresh In a production server, you may wish to disable refresh for Java components to decrease memory use and increase performance. When refresh is enabled, duplicate copies of common Java classes can be loaded for components. When refresh is disabled, you must restart the Jaguar server in order for it to load a new version of your component class.

Refresh property and intercomponent calls If your component calls another Java component, both must have refresh enabled or both must have refresh disabled.

To disable refresh:

Make sure the code bases for all classes used by your component are in the server's CLASSPATH environment variable. JAR files referenced in the custom class list must be added to the server CLASSPATH setting, or expanded into the java/classes Jaguar subdirectory.
Display the Component Properties dialog box, and click on the All Properties tab.
Set the com.sybase.jaguar.component.refresh to false (the default is true).
Restart the server for the changes to take effect.