Chapter 7: Creating Enterprise JavaBeans Components

Defining an EJB component

There are three ways to define EJB components in EAServer:

Importing an EJB-JAR file An EJB-JAR file contains the implementation classes, interface classes, and deployment descriptor for one or more beans archived in a standard format. Chapter 9, “Importing and Exporting Application Components,” in the EAServer System Administration Guide describes how to import EJB-JAR files.
Importing class files EAServer Manager can import the method information for the home, remote, and local interfaces from Java class files. Use this method if:
- You have created a bean’s interfaces and implementation class, but have not created the deployment descriptor that is required to create an EJB-JAR file. You will need to manually configure properties that would otherwise be read from the deployment descriptor.
- You have created nothing, but prefer editing Java in your code editor to editing IDL in EAServer Manager.
Defining the component from scratch You can define the component and it’s interfaces in EAServer Manager, using the IDL editing facilities in EAServer Manager to define the home, remote, and (optional) remote interfaces.

Importing EJB class files

If necessary, create class files for the home, remote, and (optionally) local interfaces, following the EJB standards for these interfaces.
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.
Verify that the displayed importer CLASSPATH contains the JAR files and directories required to instantiate the bean’s classes, specifically:
- Verify that the code base under which the class files are deployed is included.
- If the classes are in a JAR file, verify that the full path to the JAR file is included.
- If the class definitions require other JAR files or directories not listed, list them as well.
If necessary, use the Add, Modify, Delete, Move Up, and Move Down buttons in the Component Wizard to modify the CLASSPATH. The displayed CLASSPATH affects only this importer session, not the EAServer process.

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

Component name The name of the component to be created in EAServer 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.

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.
Specify remote interface If the Bean has remote interfaces, select this option and configure the following:
- Home interface class – The full path to the Java class file that contains the Bean’s home interface.
- Remote interface class – The full path to the Java class file that contains the Bean’s remote interface.
Specify local interface If the Bean has local interfaces, select this option and configure the following:
- Local home interface class – The full path to the Java class file that contains the Bean’s local home interface.
- Local interface class – The full path to the Java class file that contains the Bean’s local interface.

EAServer 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 generating skeletons and running the bean.
Generate stubs and skeletons for the component as follows:
1. Highlight the component icon.
2. Choose File | Generate Stub/Skeleton.
3. Follow the wizard pages to generate skeletons.
4. Click Generate.
Stubs generated automatically When you generate skeletons, EAServer Manager generates stubs under the same code base. You do not need to enable the Generate Stubs options.

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 EAServer Manager package that will contain the component.
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:

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
EJB - Message Driven Bean	A message-driven bean

In the EJB Version field, select 2.0. (You can select 1.1. or 1.0, but EJB 2.0 is recommended for new development.)
In the Bean Class field, enter the name of the Java class that will implement your bean, for example, foo.bar.MyBeanImpl.

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.
Enter a value for the JNDI 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 JNDI name.

If you are creating an entity bean, specify the primary key as follows:
1. Define the primary key type as one of the “Defining the primary key type”.
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. If using mean managed persistence, the Persistence must be set to Component Class (the default). If using container managed persistence (CMP), configure the additional settings described in “Configuring automatic or EJB CMP persistence”.
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,” for more information.
Define home and remote interfaces. EAServer Manager has created default home and remote interfaces named package::componentHome and package::component, respectively, where package is the EAServer Manager package name, and component is the component name.
1. To change the home or remote interface, follow the steps in “Changing the EJB remote or home interface”.
2. Edit the home interface methods, following the design patterns described in “Defining home interface methods”.
3. 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.
An EJB 2.0 component may have local interfaces, but no remote interfaces. To remove the remote interfaces generated by EAServer Manager, highlight the Interfaces folder under the component icon, then choose File | Remove Remote Interfaces.
Define local interfaces. EAServer Manager has created default local home and local interfaces named package::componentLocalHome and package::componentLocal, respectively, where package is the EAServer Manager package name, and component is the component name.
1. If you wish to keep the local interfaces, define methods for them as described in “Defining local interfaces”.
2. If you do not need local interfaces, highlight the Interfaces folder under the component icon, then choose File | Remove Local Interfaces.
Generate stubs and skeletons for the component as follows:
1. Highlight the component icon.
2. Choose File | Generate Stub/Skeleton.
3. Follow the wizard pages to generate skeletons.
4. 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 Generate Stubs option.
EAServer 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. EAServer 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. See “Deploying the 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.

Defining the primary key type

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 “Creating IDL types, exceptions, and interfaces” 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.” 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. In Java, create methods must have names that begin with create, as in createAccount. (If defining an EJB 1.1 or 1.0 bean, create is the only valid name.)

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 in IDL, 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, EAServer 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__overload-suffix
(
  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:

Single-object finder methods 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.
Multi-object finder methods 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.

By default, the Java form of multi-object finder methods returns java.util.Collection. For compatibility with older EJB code, you can specify that generated stub methods should return java.util.Enumeration. To do so, add an IDL doc comment before the IDL method definition with this form:
```
/**
** 
**/
::MyModule::MyRemoteList findByName(in string name);
```
Sequence types are automatically generated EAServer 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.

Home interface business methods You can add business methods to the home interface for an entity bean to perform operations that are not specific to a single instance. For example, a home business method might return the average employee salary. For each home business method, the entity bean’s implementation class must have a method with the same name, except for the prefix ejbHome, and the same signature. For example, if the home interface declares:

public double averageSalary();

Then the implementation class must contain:

public double ejbHomeAverageSalary();

Home interface business methods cannot be used in EJB 1.1 or 1.0 beans.

Defining remote interface methods

The IDL for your 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,” for more information.

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

Defining local interfaces

The EJB 2.0 architecture introduces local interfaces for calls to an EJB component from within the same Java Virtual Machine. In EAServer, you can use local interfaces for intercomponent calls, and for component invocations made from servlets and JSPs hosted in the same server as the component.

Using local interfaces can improve performance, but in coding you must be aware that:

Parameters are passed by reference rather than by copy, so object instances passed through a local invocation can be shared by the client and component. If the component modifies the object, the client sees the changes.
Local interfaces are not location transparent. The called component must be hosted in the same server process as the calling component, and both components must be configured to use the same custom class loader. See “Calling local interface methods” for more information.

Defining local interfaces in Java The Java local home interface must extend javax.ejb.EJBLocalHome. Other than the base interface, the requirements are the same as for defining the home interface.

The Java local interface must extend javax.ejb.EJBLocalObject. Other than the base interface, the requirements are the same as for defining the local interface.

Defining local interfaces in IDL In IDL, local home interfaces can contain create and finder methods. The local home for an entity bean can also contain business methods. The IDL syntax is the same as for remote home interfaces, namely:

IDL create methods must return the local interface type and raise CtsComponents::CreateException.
The IDL findByPrimary key method must return the local interface type, accept the primary key type as the sole parameter, and raise CtsComponents::FinderException.
Any additional IDL finder methods must return a sequence of the primary key type and raise CtsComponents::FinderException.

The local interface can be defined in IDL with the same restrictions as for the IDL remote interface.