annotate src/solaris/doc/sun/man/man1/rmic.1 @ 1228:b056c42ea5b4

6837214: Update JDK7 man pages Reviewed-by: darcy, bpatel, tbell Contributed-by:
author tbell
date Mon, 04 May 2009 18:28:26 -0700
parents 37a05a11f281
children 00cd9dc3c2b5
rev   line source
tbell@1228 1 ." Copyright 2004-2006 Sun Microsystems, Inc. All Rights Reserved.
duke@0 3 ."
duke@0 4 ." This code is free software; you can redistribute it and/or modify it
duke@0 5 ." under the terms of the GNU General Public License version 2 only, as
duke@0 6 ." published by the Free Software Foundation.
duke@0 7 ."
duke@0 8 ." This code is distributed in the hope that it will be useful, but WITHOUT
duke@0 9 ." ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
duke@0 10 ." FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
duke@0 11 ." version 2 for more details (a copy is included in the LICENSE file that
duke@0 12 ." accompanied this code).
duke@0 13 ."
duke@0 14 ." You should have received a copy of the GNU General Public License version
duke@0 15 ." 2 along with this work; if not, write to the Free Software Foundation,
duke@0 16 ." Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
duke@0 17 ."
duke@0 18 ." Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
duke@0 19 ." CA 95054 USA or visit if you need additional information or
duke@0 20 ." have any questions.
tbell@1228 21 ."
tbell@1228 22 .TH rmic 1 "04 May 2009"
tbell@1228 23 ." Generated from HTML by html2man (author: Eric Armstrong)
duke@0 24
duke@0 25 .LP
tbell@1228 26 .SH "Name"
duke@0 27 rmic \- The Java RMI Compiler
duke@0 28 .LP
tbell@1228 29 .RS 3
duke@0 30
duke@0 31 .LP
duke@0 32 .LP
duke@0 33 \f3rmic\fP generates stub, skeleton, and tie classes for remote objects using either the JRMP or IIOP protocols. Also generates OMG IDL.
duke@0 34 .LP
tbell@1228 35 .RE
duke@0 36 .SH "SYNOPSIS"
duke@0 37 .LP
duke@0 38
duke@0 39 .LP
duke@0 40 .nf
duke@0 41 \f3
duke@0 42 .fl
duke@0 43 rmic [ \fP\f3options\fP\f3 ] \fP\f4package\-qualified\-class\-name(s)\fP\f3
duke@0 44 .fl
duke@0 45 \fP
duke@0 46 .fi
duke@0 47
duke@0 48 .LP
duke@0 49 .SH "DESCRIPTION"
duke@0 50 .LP
duke@0 51
duke@0 52 .LP
duke@0 53 .LP
duke@0 54 The \f3rmic\fP compiler generates stub and skeleton class files (JRMP protocol) and stub and tie class files (IIOP protocol) for remote objects. These classes files are generated from compiled Java programming language classes that are remote object implementation classes. A remote implementation class is a class that implements the interface \f2java.rmi.Remote\fP. The class names in the \f3rmic\fP command must be for classes that have been compiled successfully with the \f3javac\fP command and must be fully package qualified. For example, running \f3rmic\fP on the class file name \f2HelloImpl\fP as shown here:
duke@0 55 .LP
duke@0 56 .nf
duke@0 57 \f3
duke@0 58 .fl
duke@0 59 rmic hello.HelloImpl
duke@0 60 .fl
duke@0 61 \fP
duke@0 62 .fi
duke@0 63
duke@0 64 .LP
duke@0 65 .LP
duke@0 66 creates the \f2HelloImpl_Stub.class\fP file in the \f2hello\fP subdirectory (named for the class's package).
duke@0 67 .LP
duke@0 68 .LP
duke@0 69 A \f2skeleton\fP for a remote object is a JRMP protocol server\-side entity that has a method that dispatches calls to the actual remote object implementation.
duke@0 70 .LP
duke@0 71 .LP
duke@0 72 A \f2tie\fP for a remote object is a server\-side entity similar to a skeleton, but which communicates with the client using the IIOP protocol.
duke@0 73 .LP
duke@0 74 .LP
duke@0 75 A \f2stub\fP is a client\-side proxy for a remote object which is responsible for communicating method invocations on remote objects to the server where the actual remote object implementation resides. A client's reference to a remote object, therefore, is actually a reference to a local stub.
duke@0 76 .LP
duke@0 77 .LP
duke@0 78 By default, \f3rmic\fP generates stub classes that use the 1.2 JRMP stub protocol version only, as if the \f2\-v1.2\fP option had been specified. (Note that the \f2\-vcompat\fP option was the default in releases prior to 5.0.) Use the \f2\-iiop\fP option to generate stub and tie classes for the IIOP protocol.
duke@0 79 .LP
duke@0 80 .LP
duke@0 81 A stub implements only the remote interfaces, not any local interfaces that the remote object also implements. Because a JRMP stub implements the same set of remote interfaces as the remote object itself, a client can use the Java programming language's built\-in operators for casting and type checking. For IIOP, the \f2PortableRemoteObject.narrow\fP method must be used.
duke@0 82 .LP
duke@0 83 .SH "OPTIONS"
duke@0 84 .LP
duke@0 85
duke@0 86 .LP
tbell@1228 87 .RS 3
duke@0 88 .TP 3
duke@0 89 \-bootclasspath path
duke@0 90 Overrides location of bootstrap class files
duke@0 91 .TP 3
duke@0 92 \-classpath path
duke@0 93 Specifies the path \f3rmic\fP uses to look up classes. This option overrides the default or the CLASSPATH environment variable if it is set. Directories are separated by colons. Thus the general format for \f2path\fP is:
duke@0 94 .RS 3
duke@0 95
duke@0 96 .LP
duke@0 97 .nf
duke@0 98 \f3
duke@0 99 .fl
duke@0 100 .:<your_path>
duke@0 101 .fl
duke@0 102 \fP
duke@0 103 .fi
duke@0 104 .RE
duke@0 105 For example:
duke@0 106 .RS 3
duke@0 107
duke@0 108 .LP
duke@0 109 .nf
duke@0 110 \f3
duke@0 111 .fl
duke@0 112 .:/usr/local/java/classes
duke@0 113 .fl
duke@0 114 \fP
duke@0 115 .fi
duke@0 116 .RE
duke@0 117 .TP 3
duke@0 118 \-d directory
duke@0 119 Specifies the root destination directory for the generated class hierarchy. You can use this option to specify a destination directory for the stub, skeleton, and tie files. For example, the command
duke@0 120 .RS 3
duke@0 121
duke@0 122 .LP
duke@0 123 .nf
duke@0 124 \f3
duke@0 125 .fl
duke@0 126 % rmic \-d /java/classes foo.MyClass
duke@0 127 .fl
duke@0 128 \fP
duke@0 129 .fi
duke@0 130 .RE
duke@0 131 would place the stub and skeleton classes derived from \f2MyClass\fP into the directory \f2/java/classes/foo\fP. If the \f2\-d\fP option is not specified, the default behavior is as if \f2"\-d\ ."\fP were specified: the package hierarchy of the target class is created in the current directory, and stub/tie/skeleton files are placed within it. (Note that in some previous versions of \f3rmic\fP, if \f2\-d\fP was not specified, then the package hierarchy was \f2not\fP created, and all of the output files were placed directly in the current directory.)
duke@0 132 .br
duke@0 133 \
duke@0 134 .TP 3
duke@0 135 \-extdirs path
duke@0 136 Overrides location of installed extensions
duke@0 137 .TP 3
duke@0 138 \-g
duke@0 139 Enables generation of all debugging information, including local variables. By default, only line number information is generated.
tbell@1228 140 .LP
duke@0 141 .TP 3
duke@0 142 \-idl
duke@0 143 Causes \f2rmic\fP to generate OMG IDL for the classes specified and any classes referenced. IDL provides a purely declarative, programming language\-independent way of specifying an object's API. The IDL is used as a specification for methods and data that can be written in and invoked from any language that provides CORBA bindings. This includes Java and C++ among others. See the
duke@0 144 .na
duke@0 145 \f2Java Language to IDL Mapping\fP @
duke@0 146 .fi
duke@0 147 (OMG) document for a complete description.
duke@0 148 .LP
duke@0 149 When the \f2\-idl\fP option is used, other options also include:
tbell@1228 150 .RS 3
duke@0 151 .TP 3
duke@0 152 \-always or \-alwaysgenerate
duke@0 153 Forces re\-generation even when existing stubs/ties/IDL are newer than the input class.
duke@0 154 .TP 3
duke@0 155 \-factory
duke@0 156 Uses factory keyword in generated IDL.
duke@0 157 .TP 3
tbell@1228 158 \-idlModule\ fromJavaPackage[.class]\ toIDLModule
duke@0 159 Specifies IDLEntity package mapping. For example:\ \f2\-idlModule my::real::idlmod\fP.
duke@0 160 .TP 3
tbell@1228 161 \-idlFile\ fromJavaPackage[.class]\ toIDLFile
tbell@1228 162 Specifies IDLEntity file mapping. For example:\ \f2\-idlFile test.pkg.X TEST16.idl\fP.\
tbell@1228 163 .RE
duke@0 164 .LP
duke@0 165 .TP 3
duke@0 166 \-iiop
duke@0 167 Causes \f2rmic\fP to generate IIOP stub and tie classes, rather than JRMP stub and skeleton classes. A stub class is a local proxy for a remote object and is used by clients to send calls to a server. Each remote interface requires a stub class, which implements that remote interface. A client's reference to a remote object is actually a reference to a stub. Tie classes are used on the server side to process incoming calls, and dispatch the calls to the proper implementation class. Each implementation class requires a tie class.
duke@0 168 .LP
duke@0 169 Invoking \f2rmic\fP with the \f2\-iiop\fP generates stubs and ties that conform to this naming convention:
duke@0 170 .RS 3
duke@0 171
duke@0 172 .LP
duke@0 173 .nf
duke@0 174 \f3
duke@0 175 .fl
duke@0 176 _<implementationName>_stub.class
duke@0 177 .fl
duke@0 178 \fP
duke@0 179 .br
duke@0 180 \f3
duke@0 181 .fl
duke@0 182 _<interfaceName>_tie.class
duke@0 183 .fl
duke@0 184 \fP
duke@0 185 .fi
duke@0 186 .RE
duke@0 187 .LP
duke@0 188 When the \f2\-iiop\fP option is used, other options also include:
tbell@1228 189 .RS 3
duke@0 190 .TP 3
duke@0 191 \-always or \-alwaysgenerate
duke@0 192 Forces re\-generation even when existing stubs/ties/IDL are newer than the input class.
duke@0 193 .TP 3
duke@0 194 \-nolocalstubs
duke@0 195 Do not create stubs optimized for same\-process clients and servers.
duke@0 196 .TP 3
duke@0 197 \-noValueMethods
duke@0 198 Must be used with the \f2\-idl\fP option. Prevents addition of \f2valuetype\fP methods and initializers to emitted IDL. These methods and initializers are optional for \f2valuetype\fPs, and are generated unless the \f2\-noValueMethods\fP option is specified when using the \f2\-idl\fP option.
duke@0 199 .TP 3
duke@0 200 \-poa
duke@0 201 Changes the inheritance from \f2org.omg.CORBA_2_3.portable.ObjectImpl\fP to \f2org.omg.PortableServer.Servant\fP.
duke@0 202 .LP
duke@0 203 The \f2PortableServer\fP module for the
duke@0 204 .na
duke@0 205 \f2Portable Object Adapter\fP @
duke@0 206 .fi
tbell@1228 207 (POA) defines the native \f2Servant\fP type. In the Java programming language, the \f2Servant\fP type is mapped to the Java \f2org.omg.PortableServer.Servant\fP class. It serves as the base class for all POA servant implementations and provides a number of methods that may be invoked by the application programmer, as well as methods which are invoked by the POA itself and may be overridden by the user to control aspects of servant behavior. Based on the OMG IDL to Java Language Mapping Specification, CORBA V 2.3.1 ptc/00\-01\-08.pdf.
tbell@1228 208 .RE
duke@0 209 .TP 3
duke@0 210 \-J
duke@0 211 Used in conjunction with any \f2java\fP option, it passes the option following the \f2\-J\fP (no spaces between the \-J and the option) on to the \f2java\fP interpreter.
duke@0 212 .TP 3
duke@0 213 \-keep or \-keepgenerated
duke@0 214 Retains the generated \\fP source files for the stub, skeleton, and/or tie classes and writes them to the same directory as the \f2.class\fP files.
duke@0 215 .TP 3
duke@0 216 \-nowarn
duke@0 217 Turns off warnings. If used the compiler does not print out any warnings.
tbell@1228 218 .LP
duke@0 219 .TP 3
duke@0 220 \-vcompat
duke@0 221 Generates stub and skeleton classes compatible with both the 1.1 and 1.2 JRMP stub protocol versions. (This option was the default in releases prior to 5.0.) The generated stub classes will use the 1.1 stub protocol version when loaded in a JDK 1.1 virtual machine and will use the 1.2 stub protocol version when loaded into a 1.2 (or later) virtual machine. The generated skeleton classes will support both 1.1 and 1.2 stub protocol versions. The generated classes are relatively large in order to support both modes of operation.
duke@0 222 .TP 3
duke@0 223 \-verbose
duke@0 224 Causes the compiler and linker to print out messages about what classes are being compiled and what class files are being loaded.
tbell@1228 225 .LP
duke@0 226 .TP 3
duke@0 227 \-v1.1
duke@0 228 Generates stub and skeleton classes for the 1.1 JRMP stub protocol version only. Note that this option is only useful for generating stub classes that are serialization\-compatible with pre\-existing, statically\-deployed stub classes that were generated by the \f3rmic\fP tool from JDK 1.1 and that cannot be upgraded (and dynamic class loading is not being used).
tbell@1228 229 .LP
duke@0 230 .TP 3
duke@0 231 \-v1.2
duke@0 232 (default) Generates stub classes for the 1.2 JRMP stub protocol version only. No skeleton classes are generated with this option because skeleton classes are not used with the 1.2 stub protocol version. The generated stub classes will not work if they are loaded into a JDK 1.1 virtual machine.
tbell@1228 233 .RE
tbell@1228 234
duke@0 235 .LP
duke@0 237 .LP
duke@0 238
duke@0 239 .LP
tbell@1228 240 .RS 3
duke@0 241 .TP 3
duke@0 242 CLASSPATH
duke@0 243 Used to provide the system a path to user\-defined classes. Directories are separated by colons. For example,
duke@0 244 .RS 3
duke@0 245
duke@0 246 .LP
duke@0 247 .nf
duke@0 248 \f3
duke@0 249 .fl
duke@0 250 .:/usr/local/java/classes
duke@0 251 .fl
duke@0 252 \fP
duke@0 253 .fi
duke@0 254 .RE
tbell@1228 255 .RE
duke@0 256
duke@0 257 .LP
duke@0 258 .SH "SEE ALSO"
duke@0 259 .LP
duke@0 260
duke@0 261 .LP
duke@0 262 .LP
tbell@1228 263 java(1), javac(1),
tbell@1228 264 .na
tbell@1228 265 \f2CLASSPATH\fP @
tbell@1228 266 .fi
tbell@1228 267
duke@0 268 .LP
duke@0 269
duke@0 270 .LP
duke@0 271