Chapter 7 Creating Enterprise JavaBeans Components

Defining an EJB component

There are three ways to define EJB components in EAServer:

Steps Importing EJB class files

  1. If necessary, create class files for the home, remote, and (optionally) local interfaces, following the EJB standards for these interfaces.
  2. 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.

  3. Choose File | New Component from the menu.
  4. In the Component Wizard, select Import from EJB Class File, and click Next.
  5. Verify that the displayed importer CLASSPATH contains the JAR files and directories required to instantiate the bean's classes, specifically:

    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.
  6. Enter the component name and EJB class and interface names as follows:
  7. 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.

Steps Creating a new EJB component from scratch

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

  1. Select the Jaguar Manager package that will contain the component.
  2. Select File | New Component.
  3. In the Component Wizard dialog box, select the Define New Component check box and click Next.
  4. Enter a name for the component and click Finish.
  5. 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 2.0. (You can select 1.1. or 1.0, but EJB 2.0 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.

      Note   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.
    4. 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.

  6. 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. 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 Chapter 25, "Managing Persistent Component State" for more information.)

  7. Click OK to close the Component Properties dialog box.
  8. 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.
  9. Define home and remote interfaces. 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.
    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.



    Note   Components with no remote interface An EJB 2.0 component may have local interfaces, but no remote interfaces. If a Bean has no remote interfaces, EAServer uses the following "marker" interfaces in the component properties: These interfaces have no methods and cannot be instantiated by clients.
  10. Define local interfaces. Jaguar Manager has created default local home and local interfaces named package::componentLocalHome and package::componentLocal, respectively, where package is the Jaguar 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 each interface in Jaguar Manager, and choose File | Remove interface.

  11. Generate stubs and skeletons for the component as follows:
    1. Highlight the component icon.
    2. Choose File | Generate Stub/Skeleton.
    3. Select Generate Skeletons.
    4. Optionally select Compile Skeletons to compile the generated code. Use this option only if the component source is in the same codebase, or the compiled component class is available in the CLASSPATH.
    5. Click Generate.



    Note   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.
  12. 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.
  13. Compile the component source files, and make sure they are correctly deployed. See "Deploying the component classes".
  14. 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.

Note   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:

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.

Note   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:

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:

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

 

Copyright © 2002 Sybase, Inc. All rights reserved.