Chapter 13 Creating CORBA-Compatible Java Clients

Generating Java stubs

Stub classes allow you to instantiate local Java objects that act as proxies for an instance of the Jaguar component. You can generate Java stubs for components that are implemented in any of Jaguar's supported component models. One stub interface is generated for each IDL interface that the component implements.

When using the Jaguar ORB runtime, you must generate stubs with Jaguar Manager and compile them with a Java compiler. If you are using another ORB implementation class to connect to Jaguar, you must export the IDL interface definitions, then use the vendor's IDL compiler to generate stubs. See "Connecting to Jaguar with a third-party client ORB" for more information.

Stubs for different client models If you are generating stubs for multiple client models, such as EJB and CORBA, stubs for each model must be generated to a different codebase or Java package. "Specifying Java package mappings for IDL modules" describes how to change the Java package for stubs associated with each IDL module.

You can generate stubs in Jaguar Manager or by using the command line IDL compiler (see Appendix E, "Using the Command Line IDL Compiler").

To generate Java stubs in Jaguar Manager:

Highlight a component, package, or module as follows:
1. Highlight a component to generate stubs for all interfaces and types required by a component,
2. Highlight a package to generate all stubs needed by components in the package, or
3. Highlight a module to generate stubs for IDL interfaces and types defined within that module.
Select File | Generate Stub/Skeleton. The Generate Stubs & Skeletons dialog is displayed.
Select the Generate Stubs option and the Generate Java Stubs option. Enter values in the Stubs fields as follows:
- Java Types Choose CORBA from the drop-down list.
- 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.
- 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 NT path, including a drive.
  - 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 "Specifying Java package mappings for IDL modules".
Unselect the Generate C++ Stubs and Generate Skeletons options unless you wish to also create C++ stubs and skeletons, respectively.
Click Generate.

Avoiding name collisions with existing Java files When you are generating Java stubs for a Java component, you must ensure that the generated stubs will not overwrite 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 when 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.

Compiling stubs

For each IDL interface that is assigned to a component, Jaguar Manager generates a Java interface with the same name as the IDL interface, a stub class that implements that interface, a helper class, and a holder class. For example, for an IDL interface named Calculator::Calc, Jaguar Manager creates the source files listed in the following table:

Table 13-1: IIOP Java stub source files for example component calc
File Name	Purpose
Calc.java	Defines an interface with methods equivalent to the component's methods.
_st_Calc.java	Class that implements the interface.
CalcHelper.java	Contains methods that are required by the ORB and by the application; for example, the ORB calls helper-class methods to read and write object instances to the network.
CalcHolder.java	Used when interface references are passed as an inout or output parameter.

Jaguar Manager creates stubs for each interface and datatype defined in a module. If your component references a module that contains multiple interfaces, you will find that additional stub files are generated besides the stubs for the interfaces that are directly implemented by your component.

Jaguar Manager creates stubs in a package subdirectory below the directory specified as the code base 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. For example, if the interface is Calculator::Calc, and you specify a code base of c:\classes , the stubs will be created in c:\classes\Calculator.

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 "To generate Java stubs in Jaguar Manager:".

Compile the stub classes with a compiler that is compatible with the desired Java version for the stubs. Make sure that the CLASSPATH setting contains the code base directory and the Jaguar html/classes subdirectory. For example, the following commands will compile the stub source files assuming that the IDL-interface and code base values from the example above are valid:

cd c:\classes\calculator

set CLASSPATH=c:\classes;%JAGUAR%\html\classes;%CLASSPATH%

javac *.java