Jrpcgen - Distinct RPC/XDR IDL Compiler
Jrpcgen compiles RPC/XDR IDL ("*.x") files into Java client and server stubs.
Syntax
java Jrpcgen [ options ] filename.x
Description
The Jrpcgen command compiles RPC/XDR IDL ".x" files into Java client and server stubs. You then integrate these stubs with your RPC client or server application, compile the complete application with javac (or an equivalent Java compiler), and run it together with the Distinct ONC RPC/XDR for
Java. The stubs are created as Java files in the current directory. Jrpcgen creates one main stub class file per ".x" file, which has the same name as the ".x" file but has a ".java" extension, as well as one Java class per data structure defined in the ".x" file. The server stubs include an additional stub for the server.
The main stub class is always derived from the class JRPCClient. It defines a constructor that connects the client to the server and one method for each function defined in the RPC/XDR interface description. As with the C mapping, the interface version number is automatically appended after an underscore to the method names. All defined types in the interface description and the types of the methods input and output parameters are mapped to equivalent Java types.
XDR data structures are mapped to Java types as follows.
| XDR
Data Structures |
Java
Types |
| (unsigned) int |
int |
| (unsigned) long |
int |
| (unsigned) short |
short |
| (unsigned) char |
char |
| (unsigned) hyper |
long |
| float |
float |
| double |
double |
| bool |
boolean |
| string |
String |
| opaque |
byte array |
| fixed length array |
Java array |
| variable length array |
Java array |
| optional data (pointer-like *x) |
Reference to an object of class x. If x is a basic type, a special wrapper class XDRx which implements XDRType is used instead. |
| enum x |
Class x implements XDRType with member variable int value and one constant int per enum constant. |
| struct x |
Class x implements XDRType with member variables for each struct member. |
| union x |
Class x implements XDRType with member variables for each union member including discriminant. No overlaying of members is supported (neither for type conversion nor for saving space). |
| typedef x y |
Class x implements XDRType with member variable value of the redefined type y. |
Each generated class implements the XDRType interface. This interface defines the methods for encoding and decoding the classes into and from an XDRStream. You can define your own types (or alter the Jrpcgen generated files) and use them in RPC calls as long as they define these RFC 1832 (XDR) compliant encoding and decoding methods.
Jrpcgen understands C-like comments (/* ... */) and it copies lines that are starting with a "%" symbol in front of all generated output files. By default, Jrpcgen runs a C/C++ preprocessor on the given ".x" file before translating it to Java. It defines two symbols for this preprocessor run. The symbol "JAVA" is always defined. In addition, a context symbol with the name of the top-level ".x" file (without extension) is defined (i.e. "java Jrpcgen demo.x" defines a symbol "demo"). This allows the writing of RPC/XDR specifications with special Java related parts (although this is not recommended, it might sometimes be necessary).
Options
| -c |
C-preprocessor
Specifies the name of the C/C++ preprocessor to be used. The default is "cl /C /EP /nologo" (in the current path). Specify the command line if you are using a different preprocessor (for example, "/usr/ccs/lib/cpp" on Solaris systems). |
| -d |
Removes all input lines from the .x file which start with '%'. These lines often contain C specific comments which are no longer needed. |
| -f |
Names the generated class after the name given in the "program" statement. Without this option, the name of the generated class is based on the name of the .x file being processed. This option is useful to override the default behavior if there is no relationship between the class name and the name of the .x file. |
| -m |
Jrpcgen by default generates constructors for XDR data types. For backward compatibility, this feature can be disabled by specifying this option. |
| -n |
Do not run the C/C++ preprocessor before translating the ".x" file. This option is useful when you do not have a C compiler installed and you want to translate a file that does not contain preprocessor directives. |
| -x |
Enables XML-RPC support.
Without this option only standard ONC RPC stubs and types are generated.
With this option set, Jrpcgen add the following
features to the generated classes:
| o |
A new class <interfacename>_xml.java is generated. It
contains the client stub for the XML-RPC Web-Service. |
| o |
Each standard ONC RPC server
stub now also implements the
org.apache.xmlrpx.XmlRpcHandler interface, i.e. provides an implementation for
its execute() method. I.e. it can be used directly for providing the server
functionality not only over ONC RPC but also at the same time over XML-RPC. |
| o |
Each standard ONC RPC client stubs now also implements the
org.apache.xmlrpx.XmlRpcHandler interface, i.e. provides an implementation for
its execute() method. I.e. it can be used as a handler that receives an XML-RPC
and calls out using ONC RPC. |
| o |
Each generated interface type class now implements the
com.distinct.rpc.XMLRPCType interface, i.e. it provides an implementation for
its obj_encode() and obj_decode() methods that convert the Java class to an
XML-structure and vice versa. |
|
| -o class |
Names the generated class as specified by the class parameter.Without this option, the name of the generated class is based on the name of the .x file being processed. This option is useful to override the default behavior if there is no relationship between the class name and the name of the .x file. |
| -O path |
Specifies the destination path where all generated files will be saved. |
| -p |
package
Specifies the package name of the generated stub files. By default there is no package name. |
| -P |
package
Specifies the package name of the generated stub files, creates the according package subdirectories and places the generated files there. |
| -R |
package
Specifies the name of the Distinct JRPC package. This option exists only for backward compatibility to allow the latest Jrpcgen to generate files which will be used with a previous version of
JRPC. |
| -S |
Use this option to generate the server side stubs. |
| -X
<packagename> |
Specifies the exact name of
the xmlrpc-package. This enables to select from the various available
implementations. Default is "org.apache.xmlrpc" and it is a
requirement that the package is functionally equivalent to this package.
But there are other implementations available, like the well-known
"helma.xmlrpc" that are derived from the same source, that can
be used instead. |
|