Choose implementation datatypes  Advanced techniques

Chapter 11: Creating CORBA Java Components

Write the 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 EAServer Manager.

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

StepsImplementing 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, EAServer 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 EAServer Manager to generates stubs and skeletons for the component. EAServer Manager will also create a sample implementation template for the class that implements the component methods.

NoteInternally, EAServer’s IDL-to-Java compiler is invoked by EAServer 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:

Using the sample implementation EAServer 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.

StepsGenerating 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 Wizard displays. Follow the instructions on each page to generate skeletons. See the online help for descriptions of any input fields that you do not understand.

EAServer 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. If the class file is available when you generate skeletons, you can select the Compile Skeletons option in the wizard to compile from EAServer Manager.

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:


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:

Package(s)

Description

com.sybase.jaguar.server

Contains utility classes for use in server-side Java code.

com.sybase.jaguar.sql

Defines interfaces for defining and sending result sets. See “Sending result sets with Java” for details on using these classes.

com.sybase.jaguar.jcm

Provides the Java Connection Management (JCM) classes. See Chapter 26, “Using Connection Management” for a description of this feature.

com.sybase.jaguar.util

com.sybase.jaguar.util.jdbc11

Contain the JException class and the holder classes that are used to pass inout and out parameter values.

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:

Package(s)

Description

org.omg.CORBA

Contains Java holder and helper classes for each of the core CORBA datatypes. Also defines the interfaces for a standard Java client-side Object Request Broker.

com.sybase.CORBA.jdbc11.*

Contains utility classes for converting between EAServer IDL datatypes and core Java datatypes.

com.sybase.jaguar.server

Contains utility classes for use in server-side Java code.

com.sybase.jaguar.sql

Defines interfaces for defining and sending result sets. See “Sending result sets with Java” for details on using these classes.

com.sybase.jaguar.jcm

Provides the Java Connection Management (JCM) classes. See Chapter 26, “Using Connection Management” for a description of this feature.

com.sybase.jaguar.util.JException

Many of the methods in the EAServer Java classes throw JException. Note that the packages com.sybase.jaguar.util and org.omg.CORBA contain identically named classes, so you can not import all classes from both packages. To avoid compilation problems, import JException explicitly or always refer to this class by its full name.

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:

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:





Copyright © 2005. Sybase Inc. All rights reserved. Advanced techniques