Creating Enterprise JavaBeans

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.

Creating a new EJB component from scratch:

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

Double-click the Installed Packages folder that will contain the Enterprise JavaBean.
Select the Add new component icon in the right window.

The Component wizard displays.
In the Add Component dialog box, select the Define New Component check box and click Next.
In the Name of Component dialog box, enter a name for the component and click Next.
In the Summary Page, click Finish to create the object.
Display the Component Properties dialog box. Make the following changes on the General tab:
1. Set the Component 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 Class Type 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.
If you are defining a stateful session Bean, optionally switch to the Persistence tab and enter a time limit in the Time Out 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. Click on the Persistence tab, and type the name of the IDL primary key type into the Primary Key field. The Persistence field must be set to Component Class (the default). Leave all other fields besides Persistence and Primary Key blank.
Click OK to close the Component Properties dialog box.
The Adaptive Server plug-in has created default home and remote interfaces named package::componentHome and package::component, respectively, where package is the Adaptive Server plug-in package name, and component is the component name.
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 Chapter 8, “Managing Persistent Component State.”
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.
Generate stubs and skeletons for the component as follows:
1. Highlight the component icon.
2. Choose File | Generate Stubs/Skeletons.
  
  The stubs and skeletons dialog box displays.
3. Select Generate Skeletons and click OK.
4. Specify a code base for the generated files.
5. Click OK.
The Adaptive Server plug-in 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. The Adaptive Server plug-in also generates Java equivalents for the home and remote interfaces, and for an entity Bean, the primary key type.
Compile the component source files, and make sure they are correctly deployed to EJB Server. See “Deploying component classes”.
If you are testing the component with a Java applet, generate and compile stubs using the $SYBASE/$SYBASE_EJB/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.

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.

Defining home interface methods

You can add methods to a home interface using a text editor. 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 Java, EJB Server 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 The Adaptive Server plug-in 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 using a text editor. The procedure is the same as for any other IDL interface.

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

To configure EJB 1.1 role references:

If necessary, define new Adaptive Server roles to be used by callers of the component. You can create roles in the Adaptive Server plug-in in the Roles folder under the Adaptive Server icon. Adaptive Server and EJB Server share roles.
Verify that J2EE roles are mapped to Adaptive Server 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.

Deploying component classes

If you are creating components from scratch in the Adaptive Server plug-in to Sybase Central, 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 EJB Server 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.

EJB Server 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 EJB Server. Repeat the steps below to deploy new versions of your implementation.

To deploy EJB component classes:

Deploy the component class files, stub and skeleton files, and other classes required by the implementation to EJB Server. 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 $SYBASE/$SYBASE_EJB/java/classes package subdirectories. If deploying a JAR file, place it in the $SYBASE/$SYBASE_EJB/java/classes subdirectory.

The preferred code base is $SYBASE/$SYBASE_EJB/java/classes For security reasons, it is preferable to deploy Java components to the $SYBASE/$SYBASE_EJB/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 the Adaptive Server plug-in 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 the Adaptive Server plug-in to refresh the component by highlighting its icon and choosing View | Refresh All. 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 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.