Programmer tools for Java

Important: VisiBroker version 6.5 provides additional features in VisiBroker for Java tools that are not documented here. Go to www.borland.com/techpubs/bes for the latest information about these changes.

This chapter describes the programmer tools offered by VisiBroker for Java. In this section, command syntax consists of the commands, the arguments necessary to execute them, and command-line options. Some commands take no arguments, but their options are provided.

Options

All VisiBroker for Java programmer's tools have both general and specific options. The specific options for each tool are listed in the section for the tool. All the options in the list are enabled by default and they are preceded by a hyphen (-). To turn-off the default value, you can either prepend -no_ or remove the hyphen. For example, to display a "warning" if a #pragma is not recognized, the default value is:

warn_unrecognized_pragmas

To turn-off the default, use the following option:

-no_warn_unrecognized_pragmas

The general options available to all programmer tools are provided in the following section.

General options

The following options are common to all programmer tools:

General programmer's tools options

Option	Description
`-VBJdebug`	Outputs VisiBroker for Java debugging information.
`-J<java_option>`	Passes the `java_option` directly to the Java Virtual Machine.
`-VBJversion`	Outputs the VisiBroker for Java version in use.
`-VBJprop <property>=<value>`	Passes the specified property to VBJ executable.
`-VBJjavavm <vm-name>`	Specifies the path, flags to the Java VM. If not specified, the default value `java` is used.
`-VBJclasspath <classpath>`	Specifies the classpath. The value entered here precedes the `CLASSPATH` ENV variable.
`-VBJaddJar <jarfile>`	Appends <install-dir>/lib/<jarfile> to the `CLASSPATH` before executing the VM.
`-VBJconfig <config-file-name>`	The path to the configuration file to be used by the launcher. If not specified, the default location is `<install-dir>/bin/vbj.config\|vbjc.config`.
`-help\|-h\|-?\|-usage`	Prints usage information.

Configuration Files and their Directives and Conventions

You are able to define environment settings (for example, the classpath and VM options) for the VisiBroker programmers tools using configuration files. The default location of the configuration file is the directory where the tool executable itself resides. The default configuration filename for the vbjc tool is vbjc.config. For the other tools, the default filename is vbj.config.

Comments

Lines whose first character is a hash (#) are treated as comments and ignored to allow the configuration file to be structured and documented.

Path Conventions

All directory separators must be forward slashes regardless of the vagaries of local platforms. If no absolute directory is specified in the file, the current working directory will be used as the default directory for any relative paths.

Supported Directives

The following table shows directives you can use in your configuration files to specify launcher behavior.

Configuration File Directives

Directive	Description
addbootjars	Add all jars in a directory to the boot classpath.
addbootpath	Add a file or directory to the boot classpath.
addjars	Add all jars in a directory to the classpath.
addpath	Add a file or directory to the classpath.
addskippath	Never add this file or directory to the classpath or boot classpath.
apparg	Define an argument to pass to the application main class.
dirmustexist	Halt the launcher if the specified directory cannot be found.
include	Include another configuration file.
includedir	Include all configuration files in the specified directory.
javahome	Location of Java installation.
jpda	Enable or disable JPDA debugging. This directive does not start the JVM with JPDA turned on. Rather, in enables JPDA support in the launcher so that you can selectively turn JPDA on using the command line. Usage: `jpda paused\|running, [<address>=<port>]`
set	Set an internal launcher variable, for example: `set foo=bar`.
setfromoption	Used to extend the launcher's command-line syntax to include another variable. For example, `setfromoption instanceName=-server` extends the launcher's command-line syntax to support a `-server <server-name>` argument.
vmparam	Sets a VM parameter.
vmprop	Sets a Java system property.
vmtype	Sets the VM to run.
vmversion	Specifies the VM version required.

Configuration Macros

Configuration files support runtime values using a simple set of macros. All macros start with the $ character, are named, and have a value name in parentheses. The value name is looked up in the macro-specific value space and the corresponding value is used to replace the entire macro invocation. For example, the macro $env(PATH) is replaced by the value of the PATH environment variable. Most of the macros support an optional default value that is used if the value name lookup fails to return a value.

The macro can be specified at any point in a directive value. Multiple macros can be specified on a single directive, but macros may not be nested within other macro invocations. For example, while $env(DRIVE)$env(DIR) is valid, $env($env(VARNAME)) is not. As macros can only apply to the directive value, not the directive name itself, they are only expanded once a directive has been recognized and is about to processed.

Supported Macros

Macro	Description
`$var`	Substitutes a launcher or application variable. The following variables are supported: `PID`: the process ID number of the launcher. `installRoot`: the parent directory of the launcher executable. `JDK_HOME`: the root directory of the JDK. `CWD`: the current working directory of the launcher at the time it was started. `fileSep`: the platform-specific file separator. `pathSep`: the platform specific path separator.
`$env`	Substitutes an environment variable.
`$reg`	Substitutes a value from the Windows registry.
`$envThenReg`	Substitute from an environment variable or Windows registry.
`$regThenEnv`	Substitute from the Windows registry or an environment variable.
`$file`	Convert value to platform native file format.

idl2ir

This tool allows you to populate an interface repository (IR) with objects defined in an Interface Definition Language (IDL) source file. It is executed using the idl2ir command.

Syntax

idl2ir [options] {filename}

Example

idl2ir -irep my_repository -replace java_examples/bank/Bank.idl

Description

The idl2ir command takes an IDL file as input, binds itself to an interface repository server and populates the repository with the IDL constructs contained in filename. If the repository already contains an item with the same name as an item in the IDL file, the old item will be modified.

Keywords

The keyword contains both the options listed below and the IDL input files to be processed.

Options

The following options are available for idl2ir.

idl2ir options

Option	Description
`-D, -define foo[=bar]`	Defines a preprocessor macro `foo`, optionally with a value `bar`.
`-I, -include <dir>`	Specifies an additional directory for #include searching.
`-P, -no_line_directives`	Suppresses the generation of line number information. The default is off.
`-H, -list_includes`	Prints the full paths of included files on the standard error output. The default is off.
`-U, -undefine` <foo>	Undefines a preprocessor macro `foo`.
`-[no_]idl_strict`	Specifies a strict OMG standard interpretation of IDL source. The default is off.
`-[no_]warn_unrecognized_pragmas`	Displays a warning that appears if a #pragma is not recognized. The default is on.
`-[no_]back_compat_mapping`	Specifies the use of mapping that is compatible with VisiBroker 3.x.
`-irep <irep name>`	Specifies the name of the interface repository.
`-deep`	Applies a deep (versus shallow) merge. The default is off.
`-replace`	Replaces entire repository instead of merging. The default is off.
`-h, -help, -usage, -?`	Prints help information.

ir2idl

This tool allows you to create an Interface Definition Language (IDL) source file with objects from an interface repository. It is executed with the ir2idl command.

Syntax

ir2idl [options] filename

Example

ir2idl -irep my_repository -o my_file

Description

The ir2idl command binds to the IR and prints the contents in IDL format.

Keywords

The keyword contains both the options listed below.

Options

The following options are available for ir2idl.

Options for ir2idl

Option	Description
`-irep <irep name>`	Specifies the name of the interface repository.
`-o <file>`	Specifies the name of the output file, or "-" for stdout.
`-strict`	Specifies strict adherence to OMG-standard code generation. The default is on. The compiler will complain upon occurrences of Borland-proprietary syntax extensions in input IDL.
`-version`	Displays or prints out the version of Borland Enterprise Server VisiBroker that you are currently running.
`-h, -help, -usage, -?`	Prints help information.

idl2java

This tool generates Java source code from an IDL source file. It is executed using the idl2java command.

Syntax

idl2java [options] {filename}

Example

idl2java -no_tie Bank.idl

Description

The idl2java command, a Java-based preprocessor, compiles an IDL source file and creates a directory structure containing the Java mappings for the IDL declarations. Typically, one IDL file will be mapped to many Java files because Java allows only one public interface or class per file. IDL file names must end with the .idl extension.

Keywords

The keyword contains both the options listed below and the IDL source file(s) to be processed.

Options

The following options are available for idl2java:

idl2java options

Option	Description
`-D, -define foo[=bar]`	Defines a preprocessor macro `foo`, optionally with a value `bar`.
`-I, -include <dir>`	Specifies the full or relative path to the directory for #include files. Used in searching for include files.
`-P, -no_line_directives`	Suppresses the generation of line number information in the generated code. The default is off.
`-H, -list_includes`	Prints the full paths of included files on the standard error output.
`-compilerflag`	Specifies the flags that can be set.
`-compiler options`	Specifies the option for the compiler.
`-U, -undefine foo`	Undefines a preprocessor macro `foo`.
`-[no_]idl_strict`	Specifies strict adherence to OMG standard interpretation of idl source. The default is off.
`-[no_]warn_unrecognized_pragmas`	Displays a warning that appears if a #pragma is not recognized. The default is on.
`-[no_]back_compat_mapping`	Specifies the use of IDL mapping that is compatible with VisiBroker 3.x caffeine compiles.
`-[no_]boa`	Specifies BOA-compatible code generation. The default is off.
`-[no_]comments`	Suppresses the generation of comments in the code. The default is on.
`-[no_]examples`	Suppresses the generation of the _example classes. The default is off.
`-gen_included_files`	Generates code for #included files. The default is off.
`-list_files`	Lists files written during code generation. The default is off.
`-[no_]obj_wrapper`	Generates support for object wrappers. The default is off.
`-root_dir <path>`	Specifies the directory in which the generated files reside.
`-[no_]servant`	Generates servant (server-side) code. The default is on.
`-tie`	Generates _tie classes. The default is on.
`-[no_]warn_missing_define`	Warns if any forward declared interfaces were not defined. The default is on.
`-[no_]bind`	Suppresses the generation of`bind()` methods in the generated Helper class. The default is off.
`-[no_]compile`	When set to on, automatically compiles the Java files. The default is off.
`-dynamic_marshal`	Specifies that marshalling use DSI/DII model. The default is off.
`-idl2package <IDL_name> <pkg>`	Overrides default package for a given IDL container type.
`-[no_]invoke_handler`	Generates invocation handler class for EJB. Default is on.
`-[no_]narrow_compliance`	Generated code for narrow is compliant. the default is on. When this option is set to off, generated code is backward compatible.
`-[no_]Object_method`	Overrides certain methods on `java.lang.Object`. The default is on.
`-package <pkg>`	Specifies the root package for generated code.
`-stream_marshal`	Specifies that marshaling use the stream model. The default is `on`.
`-strict`	Specifies strict adherence to OMG standard for code generation. The default is off.
`-version`	Displays the software version number of Borland Enterprise Server VisiBroker.
`-map_keyword <kwd> <replacement>`	Specifies the keyword to avoid and designates its replacement.
`-h, -help, -usage, -?`	Prints help information.

java2idl

This command generates an IDL from a Java class file (in Java byte code). You can enter one or more Java classes (in byte codes). If you enter more than one class name, make sure you include spaces in between the class names.

If you use a class that extends org.omg.CORBA.IDLEntity in some Java remote interface definition, it must have the following:

an IDL file that contains the IDL definition for that type because the org.omg.CORBA.IDLEntity interface is a signature interface that marks all IDL data types mapped to Java.
all related (supporting) classes according to the CORBA 2.4 IDL2Java Specification from the Object Management Group (OMG).

If you use a class that extends org.omg.CORBA.IDLEntity in some Java remote interface definition, use the -import <IDL files> directive in the java2idl tool's command line.

For more information, refer to the CORBA 2.4 IDL2Java Specification located at http://www.omg.org/.

Note: To use this command, you must have a virtual machine supporting JDK 1.3 or later.

Syntax

java2idl [options] {filename}

Example

java2idl -o final.idl Account Client Server

Description

Use this command when you want to generate an IDL from your Java byte code. You might want to use this when you have existing Java byte code and want to create an IDL file from it so it can be used with some other programming language like C++, COBOL, or Smalltalk.

Using the option "-o"as shown in the above example, the three Java byte code files (Account, Client, Server) are output to a file, final.idl. By default, the output is displayed on the screen.

Keywords

The keyword contains both the options listed below and the Java byte code file(s) to be processed.

Options

The following options are available for java2idl.

java2idl options

Option	Description
`-D, -define foo[=bar]`	Defines a preprocessor macro `foo`, optionally with a value `bar`.
`-I, -include <dir>`	Specifies the full or relative path to the directory for #include files. Used in searching for include files.
`-P, -no_line_directives`	Suppresses the generation of line number information in the generated code. The default is `off`.
`-H, -list_includes`	Prints the full paths of included files on the standard error output.
`-U, -undefine foo`	Undefines a preprocessor macro `foo`.
`-[no_}idl_strict`	Specifies strict adherence to OMG standard interpretation of idl source. The default is `off`.
`-[no_]warn_unrecognized_pragmas`	Displays a warning that appears if a #pragma is not recognized. The default is `on`.
`-[no_]back_compat_mapping`	Specifies the use of mapping that is compatible with VisiBroker 3.x caffeine compile.
`-exported <pkg>`	The type definitions in the specified package will be exported.
`-[no_]export_all`	Exports the type definitions in all packages.
`-import <IDL file name>`	Loads extra IDL definitions.
`-imported <pkg> <IDL file name>`	The type definitions in the specified package should be considered imported from the specified IDL file and should not be code generated
`-o <file>`	Specifies the name of an output file, or "-" for stdout.
`-strict`	Specifies strict adherence to OMG standard for code generation. The default is off.
`-version`	Displays the software version number of Borland Enterprise Server VisiBroker.
`-h, -help, -usage, -?`	Prints help information.

java2iiop

This command allows you to use the Java language to define IDL interfaces instead of using IDL. You can enter one or more Java class names (in Java byte code). If you enter more than one class name, make sure you include spaces in between the class names. Use fully scoped class names.

Note: To use this command, you must have a Java Virtual Machine supporting JDK 1.3 or later.

If you use a class that extends org.omg.CORBA.IDLEntity in some Java remote interface definition, it must have the following:

an IDL file that contains the IDL definition for that type because the org.omg.CORBA.IDLEntity interface is a signature interface that marks all IDL data types mapped to Java.
all related (supporting) classes according to the CORBA 2.4 IDL2Java Specification from the Object Management Group (OMG).

If you use a class that extends org.omg.CORBA.IDLEntity in some Java remote interface definition, use the -import <IDL files> directive in the java2iiop tool's command line.

For more information, refer to the CORBA 2.4 IDL2Java Specification located at http://www.omg.org/.

Syntax

java2iiop [options] {class name}

Example

java2iiop -no_tie Account Client Server

Description

Use java2iiop if you have existing Java byte code that you wish to adapt to use distributed objects or if you do not want to write IDL. By using java2iiop, you can generate the necessary container classes, client stubs, and server skeletons from Java byte code.

Note: The java2iiop compiler does not support overloaded methods on CORBA interfaces.

Keywords

The keyword contains both the options listed below and the Java byte code file(s) to be processed.

Options

The following options are available for java2iiop.

java2iiop options

Option	Description
`-D, define foo[=bar]`	Defines a preprocessor macro `foo`, optionally with a value `bar`.
`-I, -include <dir>`	Specifies the full or relative path to the directory for #include files. Used in searching for include files.
`-P, -no_line_directives`	Suppresses the generation of line number information in the generated code. The default is `off`.
`-H, -list_includes`	Prints the full paths of included files on the standard error output.
`-U, -undefine foo`	Undefines a preprocessor macro `foo`.
`-[no_}idl_strict`	Specifies strict adherence to OMG standard interpretation of idl source. The default is `off`.
`-[no_]warn_unrecognized_pragmas`	Displays a warning that appears if a #pragma is not recognized. The default is `on`.
`-[no_]back_compat_mapping`	Specifies the use of mapping that is compatible with VisiBroker 3.x.
`-exported <pkg>`	Specifies the name of an exported package.
`-[no_]export_all`	Exports all packages. The default is `off`.
`-import <IDL file name>`	Loads extra IDL definitions.
`-imported <pkg> <idl_file_name>`	Specifies the name of an imported package.
`-[no_]boa`	Specifies BOA-compatible code generation. The default is `off`.
`-[no_]comments`	Suppresses the generation of comments in the code. The default is `on`.
`-[no_]examples`	Suppresses the generation of the `_example` classes. The default is `off`.
`-gen_included_files`	Generates code for #included files. The default is `off`.
`-list_files`	Lists files written during code generation. The default is `off`.
`-[no_]obj_wrapper`	Generates support for object wrappers. The default is `off`.
`-root_dir <path>`	Specifies the directory in which the generated files reside.
`-[no_]servant`	Generates servant (server-side) code. The default is `on`.
`-tie`	Generates `_tie` classes. The default is `on`.
`-[no_]warn_missing_define`	Warns if any forward declared file names were not defined. The default is `on`.
`-[no_]bind`	Suppresses the generation of `bind()` methods in the generated Helper class. The default is `off`.
`-[no_]compile`	Automatically generates Java files. When set to on, also automatically compiles the Java files. The default is `off`.
`-compiler`	Specifies the Java compiler to be used. This option is ignored if the `-compile` option is not set.
`-compiler flags`	Specifies the Java compiler flags to be passed to the Java compiler. This option is ignored if the `-compile` option is not set.
`-dynamic_marshal`	Specifies that marshalling use DSI/DII model. The default is `off`.
`-idl2package <IDL name> <pkg>`	Overrides default package for a given IDL container type.
`-[no_]invoke_handler`	Generates invocation handler class for EJB. Default is `on`.
`-[no_]narrow_compliance`	Generated code is compliant. the default is `on`.
`-[no_]Object_method`	Generates all methods defined in `java.lang.Object` methods, such as string and equals. The default is `on`.
`-package <pkg>`	Specifies the root package for generated code.
`-sealed <pkg> <destination_pkg>`	Generates stubs and skeletons for remote interfaces in the specified package to the `org.omg.stub` and the destination package respectively.
`-stream_marshal`	Specifies that marshaling use the stream model. The default is `on`.
`-strict`	Specifies strict adherence to OMG standard for code generation. The default is `off`.
`-version`	Displays the software version number of Borland Enterprise Server VisiBroker.
`-map_keyword <kwd> <replacement>`	Specifies the keyword to avoid and designates its replacement.
`-h, -help, -usage, -?`	Prints help information.

vbj

Important: The vbj tool documentation in VisiBroker version 6.5 is not complete here. Go to www.borland.com/techpubs/bes for the latest information about this tool.

This command starts the local Java interpreter.

Syntax

vbj [options] [arguments normally sent to java VM] {class} [arg1 arg2 ...]

Where:

Argument	Description
`{class}`	Specifies the name of the class to be executed.
`[arg1 arg2 ...]`	Specific arguments to be passed to the class.

Example

vbj Server

Description

Java applications have certain limitations not faced by applications written in other languages. The vbj command provides options to work around some of these limitations, and is the preferred method to launch Borland Enterprise Server VisiBroker applications. The vbj command performs the following actions:

Checks environment variables and Windows registry settings.
Can optionally locate an osagent for those Java Virtual Machines that lack UDP broadcast support.
Automatically sets the CLASSPATH to work correctly with the Borland Enterprise Server VisiBroker runtime.

In addition, the vbj command sets two VisiBroker ORB properties and passes them to the VisiBroker ORB runtime.

vbroker.agent.addr is set to the value of the OSAGENT_ADDR environment variable or registry setting.
vbroker.agent.port is set to the value of the OSAGENT_PORT environment variable or registry setting.

Note:If you do not use the vbj command, you must explicitly set the values of vbroker.agent.addr and vbroker.agent.port.

Options

The following options are available for vbj.

vbj options

Option	Description
`-version`	Displays or prints out the version of Borland Enterprise Server VisiBroker for Java that you are currently running.
`-<VBJpropname>=<value>`	Passes the property name and value pair into the Java Virtual Machine as a System Property by adding it as a `-D<name>[=<value>]` parameter to the executed "java."
`-VBJjavavm <vmpath>`	Specifies the Java Virtual Machine to be used.
Windows: `-VBJtag <tag>`	Specifies the tag to use for the parameters being passed to the Java Virtual Machine. The default tag value is `-D`.
Windows: `-VBJquoteSpaces 0`	Turns off the automatic placement of quotation marks around arguments that contain spaces.
Windows: `-VBJclassPath classpath`	Specifies an explicit setting for classpath.
`-VBJdebug`	Turns on debugging information.

Additional options that may be passed to this command are defined by the Java Virtual Machine that is installed on your system. For example, to view all of the options for the Java Virtual Machine, enter java with no options.

prompt>java

A list of options available for the Java interpreter appears.

Windows: In Windows environments, you can only use the Borland Enterprise Server VisiBroker vregedit tool to set the following options in the registry:

VBROKER_ADM
OSAGENT_PORT

vbjc

Important: The vbjc tool documentation in VisiBroker version 6.5 is not complete here. Go to www.borland.com/techpubs/bes for the latest information about this tool.

This command is used to compile Java source code that can import VisiBroker classes. When called, it:

Locates the VisiBroker library path
Adds the VisiBroker-standard jar files into the CLASSPATH
Launches javac

Syntax

vbjc [arguments normally passed to javac]

Example

vbjc Server.java

Specifying the classpath

Important: The information in this section is not complete for VisiBroker version 6.5. Go to www.borland.com/techpubs/bes for the latest information about this tool.

Here are the possible sources of information that can affect the classpath:

vbroker library files ($VBROKERDIR/lib/*.jar)
JDK library files ($JAVAHOME/lib/*.jar,$JAVAHOME/jre/lib/*.jar,classes.zip)
Environment variable CLASSPATH ($CLASSPATH)
Command line argument -VBJclasspath <path string>
Command line argument -classpath <path string>
Command line argument -Djava.class.path=<path string>
Command line argument -Denv.class.path=<path string>
Command line argument -VBJaddJar <jar file name> (The jar file should reside in vbroker/lib directory.)

Usually, a subset of these is merged into one classpath before the Java Virtual Machine is started. The classpath is generated differently on different platforms.

The following sources are merged together in the following order:

The classpath specified in -VBJclasspath
The $CLASSPATH exported in the environment
Visibroker-standard jar files (determined based on where vbj was found)
jar files added through VBJaddJar and assumed to be located in the <vbroker>/lib directory.
The current directory

UNIX: The merged classpath is exported and is not passed as a parameter to the Java Virtual Machine.

The other classpath sources are passed to the Java Virtual Machine untouched, along with other non-classpath parameters.

Windows: The merged classpath is passed using -Djava.class.path. The other classpaths are treated as normal arguments and are passed without alteration.

Note: Tools defined by Windows as SERVICEs don't recognize -classpath. Some of these tools ignore this argument, but some stop on it and generate errors. (for example, nameserv, irep)

Specifying the JVM

Important: The information in this section is not complete for VisiBroker version 6.5. Go to www.borland.com/techpubs/bes for the latest information about this tool.

UNIX: The default Java Virtual Machine (JVM) is java. You can specify a different JVM by including:

-VBJjavavm <jvm name>

as a command line argument. No matter which JVM is specified, its actual existence is checked and the program aborts if it fails to locate the JVM. If the JVM you specified does not exist, no attempt is made to locate the default one.

Windows : If you do not explicitly specify the JVM, Borland Enterprise Server VisiBroker will see if there is path information set in the environment. If the PATH variable is set, it checks each directory in the PATH that contains \bin to see if a JVM dll can be found there. It aborts if PATH is set but no JVM is found.

If PATH is not set, Borland Enterprise Server VisiBroker looks into the Windows registry for the location of the currently installed JVM.

It uses the following names for the dll: for JVM 1.2 jvm.dll; for JVM 1.1 it uses javai.dll.

You can specify a different JVM by including:

-VBJjavavm <jvm name>

as a command line argument. The <jvm name> must include the full path to the application; and is in the form:

*\*\*java*

where * means empty or non-empty string. For instance, C:\jdk\bin\java. The program aborts with an error message if the <jvm name> is not in the proper format or if it does not find a file with the <jvm name>.