Chapter 12 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.

To implement a Java source file for a Java component that runs on a Jaguar server, follow these steps:

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 Jaguar loads the implementation class.
   
   
4. Implement ServerBean interface methods - Optionally implement the ServerBean interface.
   
   
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. Share data between instances - Allow components to share properties between the same class's instances.
      
      
   2. Manage database connections - Connect to databases through connection caches using the Connection Management API.
      
      
   3. Return result sets - Return result sets using the Jaguar Result Sets API.
      
      
   4. 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, Jaguar'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 Jaguar 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 skeleton and implementation files

You can generate Java source files for skeleton classes from Jaguar Manager as follows:

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 Jaguar 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 NT path. It can include a drive and as many directories as you want. You can use %JAGUAR% or $JAGUAR in place of the Jaguar installation directory. Other environment variable substitutions or shell aliases such as "~" to indicate your home directory are not supported. If you specify a relative path, such as myclasses, it is expanded relative to the html/classes subdirectory in the Jaguar installation directory.
     
   
   
   
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 Jaguar package name and Comp represents the component name.

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

Compile the skeleton classes with a compiler that is compatible with JDK 1.1. Make sure that the CLASSPATH setting contains the code base directory and the Jaguar html/classes subdirectory. For example, if code base is c:\classes, these commands compile _sk_calc.java:

cd c:\classes\Calculator
set CLASSPATH=c:\classes;%JAGUAR%\html\classes;%CLASSPATH%
javac _sk_calc.java

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 Jaguar CTS 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 the ServerBean interface, then you should use the activate(InstanceContext, String) and deactivate() methods to manage instance-specific data.

If the component does not implement the ServerBean interface, then 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 ServerBean interface methods

The ServerBean interface provides methods that the Jaguar server invokes in response to transitions in the component's lifecycle. Chapter 3, "Understanding Transactions and Component Lifecycles" describes how component instances are created, bound to clients, and destroyed.

Implement the ServerBean interface if any of the following requirements apply:

• You require explicit control over whether each component instance is reused or destroyed. In this case, code the canReuse() method to specify whether the component instance can be reused by another client. You must disable the Pooling option in the Component Properties window or Jaguar will not call the canReuse() method (see "Instances tab component properties" for more information).
• You require code to reinitialize an instance before it is reused by another client. You can place this code in the activate and deactivate methods.
• Your component is transactional , will be called by other components, and you require the ability to veto transactions that are committed by another component. In components that implement ServerBean, a transaction is vetoed if the ServerBean.deactivate() method throws an exception.

If you are adapting an existing class that does not implement ServerBean to run as a Jaguar component, you may need to modify the source to add the ServerBean methods and required activation and deactivation code. If you do not have access to the source, create an adaptor class that implements ServerBean and calls the existing class methods. Install the adaptor class as the implementation class for the component.

If a class does not implement ServerBean, you can set component properties in Jaguar Manager to control instance reuse (pooling) and how the component participates in transactions. See "Configuring component properties" for more information.

Implementing ServerBean methods

To support the ServerBean interface, your class must implement the ServerBean interface and these methods:

For more information on these methods, see the reference page for jaguar.beans.enterprise.ServerBean in the Jaguar CTS API Reference.

Add error handling code

Errors occuring 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. Call InstanceContext.rollbackWork() if the error prevents completion of the current transaction. (Alternatively, throw the exception org.omg.CORBA.TRANSACTION_ROLLEDBACK and skip the next step.)
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 Jaguar 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.
• Jaguar EJB clients rethrow any server exception as a JException instance with the message text returned by calling toString() on the original exception.

Copyright © 2000 Sybase, Inc. All rights reserved.