Developer's-Panther WebSphere

This chapter describes the process for building Enterprise JavaBeans in Panther.

Creating Service Components

Service components perform the server-side processing in component-based applications. In Panther, building a service component saves a Panther service component in an application library and generates the EJB and/or COM component associated with that service component.

How to Create Service Components

1. In the editor, choose FileNewService Component, which displays a blank service component.
   

2. Create the widgets (from the Create menu or from the repository) that will be needed for method parameters and properties.
   

---

Defining the Component Interface

Components must have a defined interface. This interface consists of properties and methods supported by the component, together with information about those properties and methods, such as data types, parameter lists, and so on. This interface definition is the public face of your component; all interactions with application clients is by means of the properties and methods defined in this interface.

How to Define the Component Interface

1. Choose ViewComponent Interface. The Component Interface window displays.
   

2. To add methods, select the Methods tab and choose Change. For more information on adding methods, refer to "Adding a New Method."
3. To add properties, select the Properties tab and choose Change. For more information on adding properties, refer to "How to Add a Property."
4. To specify your EJB settings, select the EJB tab. For more information on EJB settings, refer to "The Component Interface Window - EJB Section."

---

The Component Interface Window - Methods Section

The Methods section of the Component Interface window lists the methods currently defined for the component. Each row in the grid corresponds to a method. The first column shows the method's return type, the second the method's name, and the third the method's parameters, prefixed by their kind and type.

Figure 5-1 The Methods window allows you to view and define the component's methods.

Methods correspond to the actions to be performed by the component. The code to implement the service component's methods can be written in JPL, in C, or in Java. The procedure or function must be in scope at runtime, and the name must match the method name. For information on implementing methods, refer to "Implementing Methods."

Adding a New Method

Choosing Change on the Methods section displays the Change Methods window where you can add a new method, copy an existing method, or edit a method. On the left, the New Methods column displays the JPL procedure names defined in the service component's JPL Procedures property. On the right, the grid contains the current list of methods, their types, and parameters.

Note: You must specify at least one method in order to generate an EJB.

How to Add a Method

1. In the New Methods column, highlight the method names and use the arrow buttons to add methods to the grid.
2. Alternatively, type the method name in the New Method field, and choose OK. (This name does not need to be listed in the New Methods column.)
3. To add (or edit) the method's parameters, highlight the method in the grid on the right. Choose Modify (or double-click) to open the Change Parameters window.
4. Specify the method's return type at the top of the Change Parameters window. The return type for the method can be Void, String, Int, Bool, Double, or Object. The JPL return value for the method will be converted to the appropriate type and returned to the client.
   

   Note: The method's return value cannot be an array. If this functionality is needed, the data should be returned in a parameter.

On the Change Parameters window, the Service Widgets column to the left displays the names of the fields on the service component. On the right, the grid contains the current list of parameters, their kind, and type. The order of the parameters is important; it is the order clients will use when calling the method.

How to Add Parameters

1. In the Service Widgets column, highlight the names and use the arrow buttons to add parameters to the grid. If the selected widget is an array, the array specification is selected automatically for the parameter.
2. Alternatively, type the parameter name in the New Parameter field, and choose OK. (This name does not need to be listed in the Service Widgets column.)
3. Choose Modify (or double click on a parameter name) to open the Change Parameter window, which contains four fields:

   • Name—The parameter's name

   • Type—String, Int, Bool, Double, or Object

   • An Array check box

   • Kind—In/Out, In, or Out

4. Choose the desired options for each parameter.
   

• On the Change Parameters window, choose Template to generate a JPL procedure for the method and its parameters in the clipboard. This generated JPL template can then be pasted into the JPL procedures or a file.

  For example, the Template option generated the following JPL for the GetCustomer method:

  proc GetCustomer
  {
  receive_args (CompanyName)
  
  return_args (CompanyName, CustomerID, Phone)
  }

The Component Interface Window - Properties Section

The Properties section in the Component Interface window displays a grid that shows the properties supported by the component. Here you can add, modify or delete a component's properties. Often, properties are defined to contain information about the application state.

Figure 5-2 The Properties card allows you to add, modify, and delete a component's properties.

Each row in the grid corresponds to a property. The grid's columns correspond to the attributes of each property: Type, Read-only (Ro) and Property Name. The order in which the properties appear in this grid is irrelevant to the functionality of your component.

How to Add a Property

Choosing Change opens the Change Properties window where you can add new properties or modify current properties. The New Property column displays the widget names found in the service component. You do not have to choose one of the names on this list. You can enter the name of a global JPL variable or the name of a field that you will create later.

1. In the New Property column, highlight the widget names and use the arrow buttons to add properties to the grid.
2. Alternatively, you can enter the name of the property in the New Property field and choose OK.
3. Highlight the property name in the grid and choose Modify to display the Change Properties window.
   

4. The Change Properties window consists of the following fields:

   • Name—The name clients will use when accessing the property. The name must correspond to a field or global JPL variable accessible when the component is open at runtime. This field or variable implements the property.

   • Type—A property can be specified as String, Int, Bool, Double, or Object. The value in the field or JPL variable that implements the property is converted to this type when a client requests the value of the property, and handed to the client in the form specified.

   • Read-only—If a property is marked Read-only, clients can get its value but not set it.

   • Array—A property can have an array of values.

The specification for EJBs, unlike other types of components, does not contain support for reading and setting properties. In order to provide this support, the interface generated for the EJB contains a set method and get method for each property defined in the interface.

The Component Interface Window - EJB Section

In the EJB section of the Component Interface window, you can specify:

• The directory in which to generate the EJB Java files

• The settings to be included in the EJB deployment descriptor

Specifying General Settings

Select General to specify the following:

Directory

Enter the directory to contain the generated Java files (or Java jar file). If WebSphere is installed on your machine, you can choose the application server's working directory.

Package Name

Enter a Java package name for the EJB bean class, home interface and remote interface. Typically, the same package name is used for an application or a subset of an application. If you leave this blank, it defaults to the component name with "EJB" appended.

JNDI Home Name

Enter the name to be associated with the EJB on the JNDI server. If you leave the field blank, the JNDI Home Name defaults to the service component name. If you enter a value, it must be specified as the component name in the client's sm_obj_create calls.

On the EJB section of the Component Interface, select Transaction to specify the transaction attributes for the bean. If you write your own JDBC, you can set transaction attributes for the methods in a bean.

Transaction Attributes

Set the Transaction Attribute to include in the EJB deployment descriptor. The possible values are: BEAN_MANAGED, MANDATORY, NOT_SUPPORTED, REQUIRES_NEW, REQUIRED, and SUPPORTS. For more information on each setting, refer to "Transaction Attribute Settings."

Isolation Level

Set the Isolation Level to include in the EJB deployment descriptor. The possible values are: SERIALIZABLE, REPEATABLE_READ, READ_COMMITTED, and READ_UNCOMMITTED. For more information on each setting, refer to "Isolation Level Settings."

If you write your own JDBC, you can set the Transaction Attribute to the following values. Each setting is briefly described below. For more information, refer to the IBM WebSphere Documentation.

• BEAN_MANAGED—Indicator that the bean is an active participant in transactions and can call methods to explicitly manage transaction boundaries.

• MANDATORY—The container always invokes the bean methods within the transaction context associated with the client.

• NOT_SUPPORTED—The container invokes bean methods without a transaction context.

• REQUIRES_NEW—The container always invokes the bean method within a new transaction context, regardless of whether the method is invoked within an existing transaction context.

• REQUIRED—The container invokes the bean method within a transaction context. If a method is invoked outside a transaction context, the container creates a new transaction context and invokes the bean method from within that context.

• SUPPORTS—The container invokes the bean method within a transaction context if the client invokes the bean method within a transaction. If the client invokes the bean method without a transaction context, the container invokes the bean method without a transaction context. (Default)

  Note: Panther database drivers support only this option in the current version.

Isolation Level Settings

If you write your own JDBC, you can set the Isolation Level, which determines how isolated one transaction is from another, to the following values. Each setting is briefly described below. For more information, refer to the IBM WebSphere Documentation.

• SERIALIZABLE—Prohibits dirty reads, nonrepeatable reads, and phantom reads.

  • Dirty reads—An uncommitted "update" (A transaction reads a database row containing uncommitted changes from another transaction.)

  • Nonrepeatable reads—A committed "update" (One transaction reads a row, a second transaction changes the same row so that when the first transaction rereads the row, it gets a different value.)

  • Phantom reads—An uncommitted "insert" (One transaction reads rows satisfying a SQL WHERE clause, a second transaction inserts a row satisfying the same WHERE clause, and the first transaction applies the same WHERE condition and gets the row inserted by the second transaction.)

• REPEATABLE_READ—Prohibits dirty reads and nonrepeatable reads, but allows phantom reads.

• READ_COMMITTED—Prohibits dirty reads, but allows nonrepeatable reads and phantom reads.

• READ_UNCOMMITTED—Allows dirty reads, nonrepeatable reads, and phantom reads. (Default)

  Note: Panther database drivers support only this option in the current version.

How to Specify Environmental Settings

Select Environment to specify user-defined environment variables and their values for use in Java business logic that implements the bean's methods. These variables are available only at the bean's scope; they are unavailable to the application's environment.

• Enter the Java environment property in the Name field, enter its value in the Value field, and press Set.
  

Implementing Methods

A method is a piece of work that a client can request the component to perform. The component implements each of its methods by means of a function (written in C, JPL or Java) that has the same name as the method's name.

Implementing Methods in JPL

To implement a method in JPL, the JPL procedure must be in scope when the service component is open at runtime. The simplest way to do this is to use the Template option on the Change Methods window to write a JPL procedure to the clipboard and then paste that procedure in the screen-level JPL (under ProceduresJPL Procedures). However, the procedure could also be written in a separate JPL module and made available with include or public commands.

Receiving a Method's Parameters

A JPL procedure that implements a component's method gets no parameters passed directly to it. To gain access to the method's in and in/out parameters, as sent by the client making the method request, use the receive_args command. For example, a sample JPL implementation of a component's method would be the following procedure:

proc my_method()
{
	vars id, name
	receive_args (id, name, address, city, state, phone) ...
}

The JPL command receive_args is followed by a list of targets. The values of the in and in/out parameters from the method call are placed in these target locations. The out parameters are skipped, therefore if a given method call has two out parameters, the first and third, only the values of the second, fourth and following parameters would be copied into the target list for the receive_args command.

The items in the target list must have a valid JPL syntax. In the example above, the first two items on the target list are variables declared locally in the procedure. For the target list to be valid, the latter four items on the target list must correspond to fields on the screen, to JPL global variables, or to JPL variables declared in the screen's unnamed JPL. Since any valid JPL syntax can be used, you could copy an incoming parameter into a property by using the property API.

Sending a Method's Parameters

The client that made the request for a method is expecting values passed back to it in the in/out and out parameters. It also expects a return value for the method as a whole, and it might also be checking for error codes, to determine whether some error has occurred while attempting to perform the method. To send these values back to the clients code like the following would be used:

proc my_method()
{
	. . .
	return_args (id, name)
	raise_exception -2
	return 0
}

Note: For information on calling methods from a client screen, refer to page 7-5, "Accessing the Component's Methods."

The return_args command works similarly to the receive_args command. The values of the JPL variables in the list will be written to the in/out and out parameters of the method, based on the order of the parameters in the method's definition.

Sending an Error Code

The raise_exception command is used to send an error code back to the client. The client's error handler can then decide what to do based on the value sent.

Sending the Return Value

The JPL return command is used to provide the return value for the method.

For return types other than integer or object, you must declare the return type in the proc statement, for example:

string proc s_method()

Figure 5-3 This sample screen-level JPL module implements the component's methods.

JPL Variables

JPL variables declared in the component's unnamed procedure are available only in the component-level JPL; they will not be in scope for widget-level JPL or for calls from the client. To increase the scope of the variables, use the JPL global command.

Implementing Methods in C

In C, rather than the JPL commands receive_args, return_args, and raise_exception, you would use the following functions:

• sm_receive_args (char *)

• sm_return_args (char *)

• sm_raise_exception (int, char *)

As in JPL, the functions sm_receive_args and sm_return_args take a list of Panther variables as a single string. The variables can be comma or space-delimited and can include the use of the property API syntax to refer to properties of fields on the component.

To make your C code accessible at runtime, your code must be packaged in a shared library and loaded at application startup.

Note: For more information on calling your C functions in EJBs, refer to Appendix C, "Adding C Functions."

Implementing Methods in Java

To implement a method in Java, the service component must have a Java Tag property set to correspond to a class which implements ScreenHandler. This class should have a method whose return type corresponds to the return type specified for the method (such as int, double, boolean, string or object) and which takes two parameters, a ScreenInterface and a WSFunctionsInterface.

The WSFunctionsInterface contains the following methods:

• get_bean

  public native PantherSessionBean get_bean()

• log

  public native int log(String message)

• raise_exception

  public native void raise_exception(String message)

• receive_args

  public native int receive_args(String args)

• return_args

  public native int return_args(String args)

Calling Other Enterprise JavaBeans

An EJB can also create other EJBs and, in a Panther application, open Panther screens. Each component operates in a different context; each component also has its own form stack. This means that the property API cannot be used to pass information between EJBs; instead, you must use the public methods of the beans.

Programming Component Events

For service components, the Procedures category (in the Properties window) contains properties for two events:

• Entry Function—Occurs when the component is instantiated

• Exit Function—Occurs when the component is destroyed

Entry and Exit Functions can be written in JPL, Java or C/C++. Typically, these functions are used to open and close database connections.

For JPL, enter a procedure name in the Entry and/or Exit Function properties and then access the JPL Procedures property to enter the JPL commands.

For Java, enter a Java Tag (under Identity), which is the name of the Java event handler for the entry and/or exit events. For more information on using Panther's Java event handlers, refer to Chapter 21, "Java Event Handlers and Objects," in Application Development Guide.

For C/C++, the function named in the Entry and/or Exit Function properties must be packaged in a shared library and loaded at application startup. For more information on calling your C functions in EJBs, refer to Appendix C, "Adding C Functions."

Generating Enterprise JavaBeans

An Panther-built EJB consists of:

• A Panther service component located in a Panther application library.

• A Java class, home and remote interfaces, a deployment descriptor and environment properties packaged in a jar file.

How to Save a Service Component and Generate an EJB

1. Create an application library in which to save your service components, such as server.lib, if one does not already exist.
2. If WebSphere is installed on your machine, set the Directory field (on the EJB section of the Component Interface window) to the directory which will contain the initial jar for the generated EJBs.
3. Choose Filesave AsLibrary Member. Enter a name, and select the application library to save it in, generally server.lib.
4. The screen displays the following Component File Generation window.
   

5. Select your options and choose OK.

   • To generate a COM component (32 bit Windows only), select Generate DLL and Typelib for COM. The DLL and typelib are placed in the directory specified on the COM section of the Component Interface.

   • To generate an EJB, select Generate Enterprise JavaBean, which places the files in the directory specified in the General setting of the EJB section of the Component Interface.

   • Select Local if WebSphere is installed on your machine.

   • Select Remote if WebSphere is not available.

6. If you select Local:

   • The Java files for the EJB are generated to the Directory specified on the Component Interface window. (For a list of affected files, see "Description of the Java Files.")

   • The files are compiled and placed in a jar.
     

     For the next step, deploying the EJB, refer to Chapter 6, "Deploying Enterprise JavaBeans in WebSphere."

7. If you select Remote, the screen displays the following message:
   

   You need to:

   • Copy the application library (such as server.lib) to the application server's working directory.

   • In the working directory, run makeejb on the application library. This generates the Java files, compiles the files in a jar file.

   • Start IBM's Administration Console in order to deploy the bean. This process is described in Chapter 6, "Deploying Enterprise JavaBeans in WebSphere."

Generating the EJB results in the following Java files:

• The Java class file, which implements the EJB interface.

• The home interface, which describes how an application client (or another EJB) creates the EJB from its container.

• The remote interface, which describes the bean's methods. An application client or another EJB calls methods defined in the remote interface to perform the business logic implemented by the bean.

• The helper class, which helps clients create a bean and handles any out parameters specified in the interface.

• The XML deployment descriptor.

In addition to the Java files, generating the EJB also produces a batch file that is used to prepare the EJB for deployment. In Windows, this files ends with a .bat extension and in UNIX .sh.

Sample Enterprise JavaBeans

The Panther distribution contains sample EJBs. For more information about the EJB samples, refer to Appendix B, "Sample Applications."