Chapter 11 Creating CORBA Java Components

Write Java source file

When you code the parameters for each method, make sure you use the Java datatype that corresponds to the datatype you defined in the Jaguar Manager.

   If you have an IDL interface If you are starting with an IDL interface rather than an existing class file, you can use Jaguar Manager to create a class that contains the necessary method declarations. See "Generate stub, skeleton, and implementation files" for more information.

Implementing the component

1. Generate stub, skeleton, and implementation files - Generate the files required to run the component. If you are starting development with an IDL interface, and not an existing Java class or interface, Jaguar Manager will generate a sample implementation with all the required method signatures.
2. Add package import statements - Import the packages that contain the classes that you need to use in your Java class.
3. Code the constructor - Provide a default constructor to be called when EAServer loads the implementation class.
4. Implement control interface methods - Implement the control interface methods to respond to changes in the instance lifecycle.
5. Add error handling code - Add code that gracefully handles errors by logging status messages and sending meaningful messages to the client.
6. To finish up, you can use these advanced technique to polish your component implementation:
   1. Manage database connections - Connect to databases through connection caches using the Connection Management API.
   2. Return result sets - Return result sets using the EAServer Result Sets API.
   3. Issue intercomponent calls - Instantiate a Java stub to make intercomponent calls.
   
   

Generate stub, skeleton, and implementation files

Use Jaguar Manager to generates stubs and skeletons for the component. Jaguar Manager will also create a sample implementation template for the class that implements the component methods.

   Internally, EAServer's IDL-to-Java compiler is invoked by Jaguar Manager to generate Java stubs and skeletons. The direct compiler interface is not intended for customer use.

What the skeleton does The skeleton class interprets component invocation requests and calls the corresponding method in your component with the parameter values supplied by the client. When a client sends an invocation request, the skeleton reads the parameter data and calls the Java method. When the method returns, the skeleton sends output parameter values, return values, and exception status to the client.

You must generate a new skeleton class if:

• You install the component in a different EAServer package,
• You change the name of the implementation class or move it to a different Java package,
• You add a method to the component interface,
• You delete a method from the component interface, or
• You change the signature of an existing method in the component interface.

Using the sample implementation Jaguar Manager creates a sample source for the implementation class that is specified in the Component Properties window. The generated template file name is:

componentImpl.java.new

where component is the name of the component. The .new extension avoids conflicts with existing source files.

The sample implementation provides a starting point for your own implementation, as it contains all the required method definitions to match the IDL interfaces that the component implements. Each method has the same name as the IDL operation it implements, and uses return and parameter datatypes that are mapped according to the type mappings that you have chosen (see "Choose implementation datatypes").

In the Java component, component interface methods must be public and cannot be declared static. If the IDL definition of the method has a non-empty raises clause, the Java method must throw equivalent Java exceptions for the IDL exceptions listed in the raises clause.

All methods in the implementation throw the exception org.omg.CORBA.NO_IMPLEMENT. Replace this code with your own method implementation.

If you've added methods to an existing component, you can copy the additional method signatures from the .new file to your original source file.

Stubs may be required to compile the component If the component's definition uses user-defined types for parameters, return values, or exceptions, Java stubs are required for these types. These stubs are generated when you generate stubs for your component, as described in "Generating Java stubs".

Compiled Java stubs for user-defined IDL types must be available when you compile your component's implementation file.

Generating skeletons

1. Select the component or, if you want to generate skeletons for all components in a package, select the package.
2. Select File | Generate Stub/Skeleton. The Generate Stubs & Skeletons dialog is displayed.
3. Select the Skeletons checkbox, then enter values for the Skeletons fields as follows.
   • Java code base The code base is the directory under which the implementation files are created. Jaguar Manager creates files in a Java package subdirectory beneath the code base directory. The default is the EAServer java/classes subdirectory, which is the recommended location for deploying Java components. If required, specify a path to a different directory.
     
     The codebase must be a valid UNIX or Windows path. It can include a drive and as many directories as you want. You can use %JAGUAR% or $JAGUAR in place of the EAServer installation directory.
   • Compile Java Skeletons Optionally compile the skeletons and, if present, the component source file. To use this option, your implementation must exist, or the Java source file must be in the directory where the skeleton source is generated.
4. Click the Generate button.

Compiling

Jaguar Manager generates the skeleton source file into the same Java package as the component's implementation class. Skeletons are named as _sk_Package_Comp.java, where Package represents the EAServer package name and Comp represents the component name.

You must compile the Java class that implements the component before you compile the skeleton class.

When you compile the skeleton class, make sure that the CLASSPATH setting contains the code base directory, as well as the following JAR files in the EAServer installation directory:

• java/lib/easserver.jar
• java/lib/easclient.jar
• java/lib/easj2ee.jar

Add package import statements

In addition to any Java packages that you might need, you might also need to import several Java packages. Classes coded with IDL datatypes and classes coded with SQL datatypes require different import statements.

Chapter 1, "Java Classes and Interfaces" in the EAServer API Reference provides reference pages for these packages.

Imports for classes implemented with SQL datatypes

The packages below are useful if your component is implemented using SQL datatypes:

The fragment below shows the import statements for all of these classes:

import com.sybase.jaguar.server.*;
import com.sybase.jaguar.util.*;
import com.sybase.jaguar.util.jdbc11.*;
import com.sybase.jaguar.sql.*;
import com.sybase.jaguar.jcm.*;
import com.sybase.jaguar.beans.enterprise.*;

You can also import com.sybase.jaguar.*, but you must remember to include the rest of the package name when you specify methods.

Imports for classes implemented with IDL datatypes

The packages below are useful if your component is implemented using the standard CORBA IDL-to-Java datatype mappings:

The fragment below shows the import statements for all of these classes:

import org.omg.CORBA.*;
import com.sybase.CORBA.jdbc11.*;
import com.sybase.jaguar.util.JException;
import com.sybase.jaguar.server.*;
import com.sybase.jaguar.sql.*;
import com.sybase.jaguar.jcm.*;

Code the constructor

A class constructor is normally used to initialize instance-specific data. However, if your component implements a control interface, then you should use the control interface methods to manage instance-specific data. Otherwise, instance-specific initialization must be done in the constructor.

Any uncaught exception that is thrown within the constructor aborts the creation of the new component instance.

Implement control interface methods

You can specify a control interface to be implemented by your component as described in "Configuring a control interface". At runtime, EAServer calls the control interface methods to indicate changes in the instance lifecycle. For example, if you use CtsComponents::ObjectControl:

• The setObjectContext method provides an ObjectContext instance. Among other features, the object context allows you to:
  • Control transactions.
  • Obtain the component's Jaguar Manager properties, allowing you to read user-defined properties in Jaguar Manager.
• The ctsActivate method indicates that the instance has been bound to a client session.
• The ctsDeactivate method indicates that the instance has been unbound from a client session.

You can also implement CORBA components that use the EJB session or entity design pattern using the CtsComponents::ObjectControl control interface. For more information on these methods, see the generated CtsComponents::ObjectControl HTML documentation in the html/ir directory of your EAServer installation.

Add error handling code

Errors occurring during component execution should be handled gracefully as follows:

1. Write detailed descriptions of the error to the log. This will help you debug the problem later. You can call any of the System.out.print methods to write to the log (the output is redirected).
2. If the error prevents completion of the current transaction, roll it back as described in "Set transactional state".
3. Throw an exception with a brief, descriptive message that is appropriate for display to an end user of the client application.

Java components can record errors or status messages to the server's log file. Writing to the log creates a permanent record of the error, and log messages can be automatically stamped with the date and time that the message was written. Call any of the System.out.print methods to write to the log.

You can also throw an uncaught exception. Ideally, any exception thrown by your component should be a standard CORBA IDL exception or a user-defined IDL exception (the latter must be listed in the raises clause of the IDL method definition and the throws clause of the equivalent Java method declaration). All exceptions are forwarded to the client, but only exceptions that are defined in IDL can be rethrown by the client stub as a duplicate of the server-side exception. CORBA ORB and EAServer EJB clients receive forwarded exceptions differently:

• CORBA ORB clients rethrow any exception that is defined in IDL as a duplicate of the original exception. Other exceptions are rethrown as the standard CORBA exception UNKNOWN.
• EAServer EJB clients rethrow any server exception as a JException instance with the message text returned by calling toString() on the original exception.

Copyright © 2002 Sybase, Inc. All rights reserved.