Appendix C Creating EAServer 1.1 Java Clients

Generate EAServer 1.1 Java stubs

Jaguar Manager creates a Java stub class and Java interface for each component. A Java stub class allows a Java client to create instances of a component on the server and to execute the component's methods as though the component were a local Java object. The Java stub class hides the details of remote method execution from the Java client. A Java stub method remotely executes a like-named method in the component.

For example, for a component named "Stock," Jaguar Manager creates the Java files Stock.java and StockIntf.java. StockIntf.java defines a Java interface that defines Java stub methods, and Stock.java implements the Java interface. The Java interface contains the following elements:

A Java stub method for each method in the component.
A destroy() method. In EAServer versions prior to 2.0, calling destroy() was a required step. In the current version, it does nothing but is provided for backward compatibility.

The stub class implements the stub interface, and contains additional methods that are required for retrieving row results.

Stubs for different client models If you are generating stubs for multiple client models, such as EAServer 1.1and CORBA, stubs for each model must be generated to a different codebase or Java package.

Component interface restriction For compatibility with the EAServer 1.1 stub model, a component's IDL interfaces may not contain create and destroy methods.

Generating stub source files

Generate stub source files in Jaguar Manager, as described below:

Select the component or, to generate stubs for all components in a package, select the package.
Select File | Generate Stub/Skeleton. The Generate Stubs & Skeletons dialog is displayed.

Select the Generate Stubs and Generate Java Stubs options. Enter values in the Stubs fields as follows:

Java Types Choose Jaguar 1.1.
Generate File Type Choose either:
- JAR File - enter the fully-qualified name of the JAR file into which the generated stubs should be compiled.
  
  The JAR file is always created locally. The path must be a valid UNIX or Windows path, including a drive.
- Java Files - enter the top-level directory path where generated files should be created, and optionally compile stubs while generating.
  
  The path 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 to specify subdirectories within the Jaguar installation directory, for example:
```
%JAGUAR%\html\classes
```
  You can type a different path or use the Browse button to select a directory.
Java Package Available only when generating stubs for an IDL module. Enter the name of the Java package for the generated stubs, or leave blank to use the default stub package names described in "Java packages".

Generation Strategy Choose one of the following:

Deployment strategy	Specifies
Full	Generates Java types for every IDL interface and type referenced by the component.
Incremental	Compares IDL and Java timestamps to determine whether a new version of the Java type must be generated. See "IDL and Java timestamping" for more information. Choosing this option can save generation time if you have not changed many IDL interfaces, and have previously generated Jaguar 1.1 stubs for the component, package, or module.
Optimistic	Similar to Incremental, except that the check for changed classes in each module ends if the first comparison indicates no change.

Java Version This option has no effect for Jaguar 1.1 stubs. It affects only EJB stubs.

Unselect the Generate C++ Stubs and Generate Skeletons options unless you wish to also create Skeletons and C++ stubs, respectively.
Click the Generate button.

Avoiding name collisions with Java component files

When generating Java stubs for a Java component, you must ensure that the generated stubs will not collide with existing Java classes or interfaces.

Name collision occurs if an unscoped IDL interface name matches the name of an existing class in the package to which you are generating stubs. For example, collision would occur if you generate stubs into the com.yourco package if the class com.yourco.Stock exists and the component implements the IDL interface YourCo::Stock. You can avoid name collisions using either of the following strategies:

When defining components, specify an IDL interface name that is different from existing Java class names in the package where you will generate stubs.
When generating stubs, specify a stub package that is different than that which contains the duplicate class.

Generated package directories and source files

Jaguar Manager creates Java package subdirectories for the generated stubs based on the code base and package name, as follows:

code_base/stub_package_name

where

code_base is the value from the Code Base field in Jaguar Manager. If you leave the field blank, stubs are generated in your home directory.

stub_package_name is the package name for the generated stubs. Jaguar Manager creates stubs in a package subdirectory below the directory specified as the Code Base field in the Generate Stubs & Skeletons dialog. By default, the Java package directory has the same name as the IDL module in which the interface is defined. If a component implements interfaces from more than one module, Jaguar Manager creates stubs for each module in separate packages that match each module name. You can specify a single Java package for all stubs as described in "Generating stub source files".

For example, the following UNIX directory structure is created if the code base is user, and the package name is com.sybase.samples. The code base is appended to the working directory, which is /opt/EAServer/html/classes.

/opt/EAServer/html/classes/user/com/sybase/samples

In each package directory, Jaguar Manager generates stubs for each interface and type that is defined in the module associated with the Java package. For each interface, the following files are created:

The Java interface file contains a Java interface specifying the method prototypes. The interface file is named according to the following syntax:
```
stubnameIntf.java
```
where:

stubname is the component name displayed in the Jaguar Manager.
The Java class file contains a Java class that implements the methods. The class file is named:
```
stubname.java
```
where:

stubname is the component name displayed in the Jaguar Manager.

Jaguar Manager generates stubs for each interface and type that is defined in a module, and stubs are generated for all modules that are referenced by the component. Consequently, you may see additional generated files besides those that represent interfaces that are implemented by your component.