rmic: The Java RMI Compiler


rmic: The Java RMI CompilerJDK 1.1 and later

Synopsis

     rmic [ options ] fully-qualified-classnames

Description

The rmic compiler generates the stub and skeleton classes for remote objects that you've written. The rmic compiler is capable of generating stubs and skeletons for both the Java Remote Method Protocol (JRMP) or the CORBA Internet Interoperable Object Protocol (IIOP). Once you've compiled your remote objects using a standard Java compiler, such as javac, you need to run rmic, specifying the class names of your RMI implementation classes using their full packages.

For example, suppose you define an interface named utils.remote.TimeServer that extends java.rmi.Remote and write an implementation of this interface called utils.remote.TimeServerImpl. After compiling both with a Java compiler, you can run rmic, specifying utils.remote.TimeServerImpl as the class name argument.

The native RMI remote method protocol, JRMP, was updated in Java 2 Version 1.2. The rmic compiler in JDK 1.2 and later supports the generation of stubs that are compatible with JRMP Version 1.1, 1.2, or both. A key difference between the two is that 1.1 required the generation of both stub and skeleton classes for a remote interface, while 1.2 requires only the stub class (the server-side skeleton operations are implemented dynamically by the RMI runtime). The -vcompat, -v1.1, and -v1.2 options, described in the next section, control what flavor of stubs and skeletons are generated when you run rmic.

Running rmic with 1.1 compatibility generates a skeleton class for each remote object type, named xxx_Skel, where the xxx is the name of the remote interface. The skeleton is responsible for receiving client requests on a server object and dispatching these requests to the actual remote object. A stub class, named xxx_Stub, is also generated; this is used for client references to the remote object. When a client gets a reference to a remote object, it receives an instance of the stub class, which forwards any method requests to the server object over the network. In our example, the stub and skeleton classes would be called utils.remote.TimeServer_Stub and utils.remote.TimeServer_Skel, respectively. When using just 1.2 compatibility (e.g., the -v1.2 option), only the stub classes are generated.

Both the stub class and the skeleton class implement the same remote interface as your remote object implementation, so they can be type cast to the remote interface.

IIOP-compatible stubs and skeletons can also be generated with rmic, using the -iiop option. In CORBA parlance, the skeletons are called ties. The concepts are the same as JRMP-compatible stubs and skeletons, except that the generated classes speak the IIOP protocol, and the class names are _rmtinterface_stub and _rmiimpl_tie (rmtinterface is the class name of the RMI remote interface, and rmiimpl is the class name of the RMI object implementation). It's also important to note that, when using IIOP-compatible stubs and skeletons, a client has to use the javax.rmi.PortableRemoteObject.narrow( ) method to safely cast remote object references to their expected remote interface type, rather than just using the Java cast operator.

Options


-always


-alwaysgenerate

Applicable only when used with the -idl or -iiop option. They tell rmic to regenerate the stub and tie classes, regardless of the timestamps on the classes.


-bootclasspath pathlist

Allows you to override the path used by rmic to find its bootstrap classes. This is useful if a custom RMI runtime implementation is used. The directories in the list are separated by colons in Unix environments (Linux, Mac OS X, etc.) and by semicolons in Windows environments.


-classpath pathlist

Provides the classpath rmic uses to find any required classes (remote object implementation, remote interface, and classes referenced by these). This option overrides the environment CLASSPATH and the default classpath. The directories in the list are separated by colons in Unix environments (including Mac OS X) and by semicolons in Windows environments.


-d path

The destination directory where the compiler should write the class files that are generated. If a -d option is given, the package of the generated classes places the stubs and skeletons in their proper subdirectories in the given destination. If the directories don't exist, rmic creates them for you. If no -d option is given, the stubs and skeletons are still generated to have the same package as the remote implementation, but the class files are placed in the current directory (e.g., the compiler assumes -d).


-depend

Forces the compiler to attempt to recompile interdependent classes whose class files are out of date with each other. Without this option, the compiler attempts to recompile only class files explicitly referenced in the command-line options. Note that this option was removed in Java 5.0, since it was seen as redundant with the same capabilities in the javac compiler.


-extdirs path

Overrides the location of runtime extensions. Normally, extensions are found in a standard location in the JRE, such as lib/ext. This option allows you to specify a custom directory to find these extension libraries.


-factory

Applicable only if used with the -idl option. It tells rmic to generate declarations for initializers for value types in the generated IDL, using the IDL factory keyword. This option is relevant only if your RMI-IIOP implementation class uses CORBA Objects By Value. This option was removed in Java 5.0.


-g

Includes debugging information in the generated stub and skeleton classes; for use with Java debuggers.


-idl

Uses the rmic compiler to generate CORBA IDL interfaces for your RMI remote objects, generating according to the CORBA Java Language to IDL Mapping specification. Note that the implementation class specified needs to be implemented as an RMI-IIOP remote object, as described in Chapter 13. Remote objects that support only JRMP can't use the IIOP protocol and can't have IDL interfaces generated for them. The -factory, -idlModule, -noValueMethods, and -idlFile options are allowed only when used with the -idl option. The -d option can control where the IDL files are generated.


-idlFile javapackage[.class] idlfile

Valid only when used with the -idl option. It overrides the default mapping of IDL entities in the Java class to an IDL file. For example, to have the IDL from any entities in the jent.corba package mapped into a jententities.idl file:

     > rmic -idl -idlFile jent.corba jententities.idl     jent.corba.MyIIOPObjImpl


-idlModule javapackage[.class] idlmodule

Valid only when used with the -idl option. It overrides the default package mapping of IDL entity references, allowing you to specify another IDL module to map them to in the generated IDL. For example, if you want the generated IDL to map entities referenced in the Java jent.corba package to a custom corba::custom::mod module:

     > rmic -idl -idlModule jent.corba corba::custom::mod     jent.corba.MyIIOPObjImpl


-iiop

Instructs the compiler to generate IIOP-compatible stubs and ties instead of JRMP stubs and skeletons. The implementation class specified needs to be implemented as an RMI-IIOP remote object, as described in Chapter 13. The -always, -alwaysgenerate, -nolocalstubs, -noValueMethods, and -poa options are allowed only when used with the -iiop option. The -d option can control where the stub and tie classes are generated.


-J[javaoption]

Passes the option immediately following the -J to the Java interpreter. There should be no spaces between the -J and the option to be passed to the interpreter.


-keep


-keepgenerated

Keeps the Java source files for the stub and skeleton classes generated by the compiler. The Java files will be written to the same directory as the class files, with or without a -d option specified. Without the -keep or -keepgenerated option present, the Java source files will be removed after the stub and skeleton classes are generated.


-nolocalstubs

Used with the -iiop option, to instruct the compiler to avoid generating IIOP stubs that are optimized for local clients. Without this option, the generated stub classes attempt to detect whether the client is running in the same process as the servant and optimizes the IIOP operations. With this option, these checks aren't generated, and the stub assumes that the servant is always remote.


-noValueMethods

Used in conjunction with the -idl option, to instruct the compiler to avoid generating valuetype methods and initializers in the generated IDL.


-nowarn

Instructs the rmic compiler to eliminate warning messages from its output. Only errors encountered during compilation are reported.


-poa

Used with the -iiop option, -poa tells rmic to generate POA-compatible servants. The generated server class inherits from the org.omg.PortableServer.Servant interface rather than the default org.omg.CORBA_2_3.portable.ObjectImpl interface.


-vcompat

Creates stub and skeleton classes that are compatible with both JDK 1.1 and 1.2 (and later) versions of RMI. This option is enabled by default in JDK 1.4 and earlier and doesn't need to be specified in those environments. In Java 5.0, the default was switched to -v1.2.


-verbose

Prints verbose messages as compilation takes place, including which class is being compiled and class files that are loaded during compilation.


-v1.1

Creates stub and skeleton classes that are compatible with the JDK 1.1 version of RMI. These classes may not run in a 1.2 or higher Java runtime environment, unless its RMI runtime supports 1.1 compatibility.


-v1.2

Creates stub and skeleton classes that are compatible with the JDK 1.2 and higher RMI runtime. These classes will not run in a 1.1 Java runtime environment. This option is the default as of Java 5.0 and doesn't need to be specified in those environments. Prior to Java 5.0, the default was -vcompat.

Environment


CLASSPATH

An ordered list of directories, zip files, and/or jar files the rmic compiler uses to look for classes. This list is separated by colons in Unix environments (Linux, Mac OS X, etc.) and by semicolons in Windows environments. The list is searched, in order, for a given class when it is encountered during compilation. The compiler automatically appends the system classpath to the CLASSPATH, if it is specified. If the CLASSPATH isn't set in the environment, the compiler uses the current directory and the system CLASSPATH as its classpath. The CLASSPATH environment variable is overridden by the -classpath option to rmic.



Java Enterprise in a Nutshell
Java Enterprise in a Nutshell (In a Nutshell (OReilly))
ISBN: 0596101422
EAN: 2147483647
Year: 2004
Pages: 269

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net