jrpcgen for ONC/RPC Java package

jrpcgen for ONC/RPC Java package.

This package provides a Java-based rpcgen RPC protocol compiler called "jrpcgen". jrpcgen is a Java-based tool that generates source code of Java classes to implement an RPC protocol. The input to jrpcgen is a language similiar to C (but more probably much more similiar to FORTRAN) known as the RPC language (Remote Procedure Call Language). Because the files containing RPC language are typically tagged with ".x" they are called "x-files" throughout this documentation.

Usage:

`jrpcgen` [`-`options] x-file

where options include:

`-c` classname
  Specify class name of client proxy stub.
`-d` directory
  Specify directory where to place generated class source code files.
`-p` package name or `-package` package name
  Specify package name for generated source code files.
`-s` classname
  Specify class name of server proxy stub.
`-ser`
  tag classes generated for XDR structs, XDR unions and XDR typedefs as serializable. Also automatically generates `serialVersionUID` using the SHA-1 algorithm.
`-bean`
  generate accessors for usage as bean, implies `-ser`.
`-noclamp`
  do not clamp version number in client method stubs.
`-withcallinfo`
  supply call information to server method stubs.
`-initstrings`
  automatically initialize all `Strings` as empty strings (""). Note that this may lead to lazy programming; better make explicitly sure that every member of a struct gets initialized properly before encoding the struct.
`-nobackup`
  Do not make backups of old source code files for which new source code is generated.
`-noclient`
  Do not create source code for the client proxy stub.
`-noserver`
  Do not create source code for the server proxy stub.
`-noToString`
  Do not create toString() methods.
`-noEquals`
  Do not create equals(Object o) and hashCode() methods.
`-noEnum`
  Generate enumerations as interfaces instead of enums (legacy support).
`-noValueCtor`
  Do not create value constructors.
`-parseonly`
  Parse x-file only but do not generate source code files.
`-verbose`
  Enable verbose output about what the jrpcgen compiler is doing.
`-version`
  Print jrpcgen version.
`-?` or `-help`
  Print this help.
`--`
  End options.

Notes

To cite the man pages for rpcgen(1): The RPC Language does not support nesting of structures. As a work-around, structures can be declared at the top-level, and their name used inside other structures in order to achieve the same effect. Name clashes can occur when using program definitions, since the apparent scoping does not really apply. Most of these can be avoided by giving unique names for programs, versions, procedures, and types. And I thought that the RFC was written before rpcgen to reflect reality but not wishes for further development.

jrpcgen can process the same x-files as its SunOS4.1-based rpcgen counterpart. Or at least it should. The Java language as well as the Java environment cause some slight differences in the code generated with respect to the typical C code emitted by rpcgen. Please also refer to the `demo.x` example in `tests.org.acplt.oncrpc.jrpcgen` for the inner details.

However, `jrpcgen` currently does not support C preprocessor directives, as `rpcgen` does my running `cpp` first on the x-file. If you need to achieve the same effect, first run `cpp` by hand (pardon: makefile) and pipe the result into `jrpcgen`.

- All elements of the interface definition file may be documented with java-doc comments. The jrpcgen copies them into the generated .java files.

- All global constants are put into one public interface with the same name as the x-file. Global constants are constants either defined using "const" or program and version constants. If a x-file named `demo.x` defines a constant `FOO`, then its Java counterpart will be accessible as `demo.FOO`.

- jrpcgen generates an java-interface for each program definition at .x file. If a x-file named `demo.x` defines a `program DEMO` jrpcgen generates a demo_DEMO_Cltif.java containing an interface demo_DEMO_Cltif with all methods of program DEMO with postfix _versionNo.

- All enumeration members of a particular enumeration are put into a public enum with the same name as the enumeration. For example: `enum FOO { foo=42 };` results in a public `enum FOO implements HasEncoding<FOO>` with value `foo(42);`. The enumeration members are accessed like `FOO.foo`. The transmitted int (at this example 42) may be obtained with`FOO.foo.getEncoding();` Within the generated Java code, wherever the enumeration type is used, the generated Java enum is used.

- For each typedef the jrpcgen protocol compiler emits a class source file of the same name. For instance, `typedef string STRING<>;` results in `class STRING`. Such classes always contain exactly one attribute named `value`. This attribute is of the same type as specified in the typedef, that is `String` (Java base type) in our case.

- For each struct the protocol compiler also emits a class source file of the same name, containing the specified attributes.

- The server stub code contains the dispatcher code and defines each remote procedure specified in the x-file as abstract. You need to supply your own implementation for each one of these stubs. Note that RPC base data types like int, u_long, etc. are mapped to their appropriate Java base type counterparts (int, int, in this example).

  By default, the server stub class is named after the x-file but with `ServerStub` appended. For example, if the x-file is named `demo.x`, then the server stub class is `demoServerStub`.

- The client stub/proxy implements the remote procedures specified in the x-file as local methods which will call their remote counterpart on an ONC/RPC server.

  By default, the client stub class is named after the x-file but with `Client` appended. For example, if the x-file is named `demo.x`, then the client class is `demoClient`.

This package is part of the Remote Tea Java Library package. (c) 1999, 2006 Harald Albrecht. (c) 1999 Lehrstuhl für Prozeßleittechnik, Aachen University of Technology, Germany. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this program (see the file LICENSE.txt for more details); if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.