org.acplt.oncrpc

## Class OncRpcPortmapClient

- java.lang.Object
- - org.acplt.oncrpc.OncRpcPortmapClient

    public class OncRpcPortmapClient
    extends java.lang.Object

The class `OncRpcPortmapClient` is a specialized ONC/RPC client, which can talk to the portmapper on a given host using the famous UDP/IP datagram-oriented internet protocol. In addition, it is also possible to contact portmappers using TCP/IP. For this, the constructor of the `OncRpcPortmapClient` class also accepts a protocol parameter (`OncRpcPortmapClient(InetAddress, int)`). Technically spoken, instances of `OncRpcPortmapClient` are proxy objects. `OncRpcPortmapClient` objects currently speak protocol version 2. The newer transport-independent protocol versions 3 and 4 are not supported as the transport-independent ONC/RPC implementation is not that widely in use due to the brain-damaged design of XTI. If you should ever have programmed using XTI (transport independent interface) then you'll know what I mean and probably agree with me. Otherwise, in case you find XTI the best thing since the Win32 API, please implement the rpcbind protocol versions 3 and 4 and give it to the community -- thank you.

Here are some simple examples of how to use the portmapper proxy object. We first start with one of the most interesting operations, which can be performed on portmappers, querying the port of a local or remote ONC/RPC server.

To query the port number of an ONC/RPC server, we need to contact the portmapper at the host machine where the server is running. The following code snippet just contacts the local portmapper. `try` blocks are ommited for brevity -- but remember that you almost allways need to catch `OncRpcException` as well as `IOException`.

     OncRpcPortmapClient portmap =
         new OncRpcPortmapClient(InetAddress.getByName("localhost"));

With the portmapper proxy object in our hands we can now ask for the port number of a particular ONC/RPC server. In this (ficious) example we ask for the ONC/RPC program (server) number `0x49678` (by coincidence this happens to be the program number of the ACPLT/KS protocol). To ask for the port number of a given program number, use the `getPort(...)` method.

     int port;
     try {
         port = portmap.getPort(0x49678, 1, OncRpcProtocols.ONCRPC_UDP);
     } catch ( OncRpcProgramNotRegisteredException e ) {
         System.out.println("ONC/RPC program server not found");
         System.exit(0);
     } catch ( OncRpcException e ) {
         System.out.println("Could not contact portmapper:");
         e.printStackTrace(System.out);
         System.exit(0);
     }
     System.out.println("Program available at port " + port);

In the call to `getPort(...)`, the first parameter specifies the ONC/RPC program number, the secondm parameter specifies the program's version number, and the third parameter specifies the IP protocol to use when issueing ONC/RPC calls. Currently, only `OncRpcProtocols.ONCRPC_UDP` and `OncRpcProtocols.ONCRPC_TCP` are supported. But who needs other protocols anyway?!

In case `getPort(...)` succeeds, it returns the number of the port where the appropriate ONC/RPC server waits for incoming ONC/RPC calls. If the ONC/RPC program is not registered with the particular ONC/RPC portmapper, an `OncRpcProgramNotRegisteredException` is thrown (which is a subclass of `OncRpcException` with a detail reason of `OncRpcException.RPC_PROGNOTREGISTERED`.

A second typical example of how to use the portmapper is retrieving a list of the currently registered servers. We use the `listServers()` method for this purpose in the following example, and print the list we got.

     OncRpcServerIdent [] list = null;
     try {
         list = portmap.listServers();
     } catch ( OncRpcException e ) {
         e.printStackTrace(System.out);
         System.exit(20);
     }
     for ( int i = 0; i < list.length; ++i ) {
         System.out.println(list[i].program + " " + list[i].version + " "
                            + list[i].protocol + " " + list[i].port);
     }

When you do not need the client proxy object any longer, you should return the resources it occupies to the system. Use the `close()` method for this.

     portmap.close();
     portmap = null; // Hint to the garbage (wo)man

For another code example, please consult `src/tests/org/acplt/oncrpc/PortmapGetPortTest.java`.

Version:
  $Revision: 1.1.1.1 $ $Date: 2003/08/13 12:03:41 $ $State: Exp $ $Locker: $
Author:
  Harald Albrecht
See Also:
  `OncRpcClient`

### Field Summary

Fields
`static int` `PMAP_PORT` Well-known port where the portmap process can be found on Internet hosts.
`static int` `PMAP_PROGRAM` Program number of the portmapper as defined in RFC 1832.
`static int` `PMAP_VERSION` Program version number of the portmapper as defined in RFC 1832.
`protected OncRpcClient` `portmapClient` The particular transport-specific ONC/RPC client object used for talking to the portmapper.

### Constructor Summary

Constructors
Constructor and Description
`OncRpcPortmapClient(java.net.InetAddress host)` Constructs and initializes an ONC/RPC client object, which can communicate with the portmapper at the specified host using the UDP/IP datagram-oriented internet protocol.
`OncRpcPortmapClient(java.net.InetAddress host, int protocol)` Constructs and initializes an ONC/RPC client object, which can communicate with the portmapper at the given host using the speicified protocol.
`OncRpcPortmapClient(java.net.InetAddress host, int protocol, int timeout)` Constructs and initializes an ONC/RPC client object, which can communicate with the portmapper at the given host using the speicified protocol.

### Method Summary

Methods
`void` `close()` Closes the connection to the portmapper.
`OncRpcClient` `getOncRpcClient()` Returns the client proxy object used for communicating with the portmapper.
`int` `getPort(int program, int version, int protocol)` Asks the portmapper this `OncRpcPortmapClient` object is a proxy for, for the port number of a particular ONC/RPC server identified by the information tuple {program number, program version, protocol}.
`OncRpcServerIdent[]` `listServers()` Retrieves a list of all registered ONC/RPC servers at the same host as the contacted portmapper.
`void` `ping()` Ping the portmapper (try to call procedure 0).
`boolean` `setPort(int program, int version, int protocol, int port)` Register an ONC/RPC with the given program number, version and protocol at the given port with the portmapper.
`boolean` `unsetPort(int program, int version)` Unregister an ONC/RPC with the given program number and version.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### PMAP_PORT

    public static final int PMAP_PORT

Well-known port where the portmap process can be found on Internet hosts.

See Also:
  Constant Field Values

#### PMAP_PROGRAM

    public static final int PMAP_PROGRAM

Program number of the portmapper as defined in RFC 1832.

See Also:
  Constant Field Values

#### PMAP_VERSION

    public static final int PMAP_VERSION

Program version number of the portmapper as defined in RFC 1832.

See Also:
  Constant Field Values

#### portmapClient

    protected OncRpcClient portmapClient

The particular transport-specific ONC/RPC client object used for talking to the portmapper.

### Constructor Detail

#### OncRpcPortmapClient

    public OncRpcPortmapClient(java.net.InetAddress host)
                        throws OncRpcException,
                               java.io.IOException

Constructs and initializes an ONC/RPC client object, which can communicate with the portmapper at the specified host using the UDP/IP datagram-oriented internet protocol.

Parameters:
  `host` - Host where to contact the portmapper.
Throws:
  `OncRpcException` - if an ONC/RPC error occurs.
  `java.io.IOException` - if an I/O error occurs.

#### OncRpcPortmapClient

    public OncRpcPortmapClient(java.net.InetAddress host,
                       int protocol)
                        throws OncRpcException,
                               java.io.IOException

Constructs and initializes an ONC/RPC client object, which can communicate with the portmapper at the given host using the speicified protocol.

Parameters:
  `host` - Host where to contact the portmapper.
  `protocol` - Protocol to use for contacting the portmapper. This can be either `OncRpcProtocols.ONCRPC_UDP` or `OncRpcProtocols.ONCRPC_TCP` (HTTP is currently not supported).
Throws:
  `OncRpcException` - if an ONC/RPC error occurs.
  `java.io.IOException` - if an I/O error occurs.

#### OncRpcPortmapClient

    public OncRpcPortmapClient(java.net.InetAddress host,
                       int protocol,
                       int timeout)
                        throws OncRpcException,
                               java.io.IOException

Constructs and initializes an ONC/RPC client object, which can communicate with the portmapper at the given host using the speicified protocol.

Parameters:
  `host` - Host where to contact the portmapper.
  `protocol` - Protocol to use for contacting the portmapper. This can be either `OncRpcProtocols.ONCRPC_UDP` or `OncRpcProtocols.ONCRPC_TCP` (HTTP is currently not supported).
  `timeout` - Timeout in milliseconds for connection operation. This parameter applies only when using TCP/IP for talking to the portmapper. A negative timeout indicates that the implementation-specific timeout setting of the JVM and java.net implementation should be used instead.
Throws:
  `OncRpcException` - if an ONC/RPC error occurs.
  `java.io.IOException` - if an I/O error occurs.

### Method Detail

#### close

    public void close()
               throws OncRpcException

Closes the connection to the portmapper.

Throws:
  `OncRpcException`

#### getOncRpcClient

    public OncRpcClient getOncRpcClient()

Returns the client proxy object used for communicating with the portmapper.

Returns:
  portmap client proxy object (subclass of `OncRpcClient`).

#### getPort

    public int getPort(int program,
              int version,
              int protocol)
                throws OncRpcException

Asks the portmapper this `OncRpcPortmapClient` object is a proxy for, for the port number of a particular ONC/RPC server identified by the information tuple {program number, program version, protocol}.

Parameters:
  `program` - Program number of the remote procedure call in question.
  `version` - Program version number.
  `protocol` - Protocol lateron used for communication with the ONC/RPC server in question. This can be one of the protocols constants defined in the `OncRpcProtocols` interface.
Returns:
  port number of ONC/RPC server in question.
Throws:
  `OncRpcException` - if the portmapper is not available (detail is `OncRpcException.RPC_PMAPFAILURE`).
  `OncRpcProgramNotRegisteredException` - if the requested program is not available.

#### setPort

    public boolean setPort(int program,
                  int version,
                  int protocol,
                  int port)
                    throws OncRpcException

Register an ONC/RPC with the given program number, version and protocol at the given port with the portmapper.

Parameters:
  `program` - The number of the program to be registered.
  `version` - The version number of the program.
  `protocol` - The protocol spoken by the ONC/RPC server. Can be one of the `OncRpcProtocols` constants.
  `port` - The port number where the ONC/RPC server can be reached.
Returns:
  Indicates whether registration succeeded (`true`) or was denied by the portmapper (`false`).
Throws:
  `OncRpcException` - if the portmapper is not available (detail is `OncRpcException.RPC_PMAPFAILURE`).

#### unsetPort

    public boolean unsetPort(int program,
                    int version)
                      throws OncRpcException

Unregister an ONC/RPC with the given program number and version. The portmapper will remove all entries with the same program number and version, regardless of the protocol and port number.

Parameters:
  `program` - The number of the program to be unregistered.
  `version` - The version number of the program.
Returns:
  Indicates whether deregistration succeeded (`true`) or was denied by the portmapper (`false`).
Throws:
  `OncRpcException` - if the portmapper is not available (detail is `OncRpcException.RPC_PMAPFAILURE`).

#### listServers

    public OncRpcServerIdent[] listServers()
                                    throws OncRpcException

Retrieves a list of all registered ONC/RPC servers at the same host as the contacted portmapper.

Returns:
  vector of server descriptions (see class `OncRpcServerIdent`).
Throws:
  `OncRpcException` - if the portmapper is not available (detail is `OncRpcException.RPC_PMAPFAILURE`).

#### ping

    public void ping()
              throws OncRpcException

Ping the portmapper (try to call procedure 0).

Throws:
  `OncRpcException` - if the portmapper is not available (detail is `OncRpcException.RPC_PMAPFAILURE`).