Appendix C Creating Jaguar 1.1 Java Clients

Generate Jaguar 1.1 Java stubs

The 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," the 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 Jaguar 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 Jaguar 1.1and CORBA, stubs for each model must be generated to a different codebase or Java package.

Component interface restriction For compatibility with the Jaguar 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 "Using JDBC Datatypes" in the drop-down list. The other option, "Using CORBA Datatypes," corresponds to the CORBA-compatible stub model described in Chapter 13, "Creating CORBA-Compatible Java Clients".
- Java Version - Select the JDK version that the stub classes will run under. Many current Web browsers support only the JDK 1.0.2 virtual machine. Choose "JDK 1.0.2" if you are creating Java clients that must run in a JDK-1.0.2-compatible browser.
- Java Code Base - Enter the top-level directory path where generated files should be created.
  The default path when the window displays is the Jaguar html/classes subdirectory, which is where applet classes must be deployed to allow downloading from the Jaguar server. You can type a different path or use the Browse button to select a directory.
  
  The path 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 to specify subdirectories within the Jaguar installation directory, for example:
```
    %JAGUAR%\html\classes
```
  Other variable substitutions or shell aliases such as "~" to indicate your home directory are not allowed.
  
  If you clear the field, the default is your home directory (specified by $HOME for UNIX and %home% for NT).
  
  If you specify a relative path, such as "myclasses," the path is interpreted relative to the Jaguar html/classes 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".
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.

Generate Java stubs for all components

To generate Java stubs for all components on a single Jaguar server or all servers, start the Jaguar Manager and complete these steps:

To generate the stub files for all servers, highlight the Servers icon and select File | Generate All Stubs.
To generate the stub files for a specific server, highlight the Server that you want the stubs generated for, then select File | Generate All Stubs.

Fill in the required properties and click Generate. Required properties are:

Code Base - The Code Base field designates the directory that stores your generated Java stub subdirectories and files. If an invalid or non-existent directory is specified, an exception is raised.
Select JDK type - Select the JDK to use for generating the Java stub files. Your choices are JDK 1.0.2 or JDK 1.1.

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/Jaguar/html/classes.

/opt/Jaguar/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.