Package org.acplt.oncrpc

## Class OncRpcUdpClient

- java.lang.Object
- - org.acplt.oncrpc.OncRpcClient
  - - org.acplt.oncrpc.OncRpcUdpClient

-     public class OncRpcUdpClient
      extends OncRpcClient

  ONC/RPC client which communicates with ONC/RPC servers over the network using the datagram-oriented protocol UDP/IP.
  Version:
    $Revision: 1.6 $ $Date: 2007/05/29 18:48:27 $ $State: Exp $ $Locker: $
  Author:
    Harald Albrecht

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected XdrUdpDecodingStream` | `receivingXdr` | XDR decoding stream used when receiving replies via UDP/IP from an ONC/RPC server.
    `protected int` | `retransmissionMode` | Retransmission mode used when resending ONC/RPC calls.
    `protected int` | `retransmissionTimeout` | Retransmission timeout used for resending ONC/RPC calls when an ONC/RPC server does not answer fast enough.
    `protected XdrUdpEncodingStream` | `sendingXdr` | XDR encoding stream used for sending requests via UDP/IP to an ONC/RPC server.
    `private java.net.DatagramSocket` | `socket` | UDP socket used for datagram-based communication with an ONC/RPC server.
    `private OncRpcUdpSocketHelper` | `socketHelper` | Socket helper object supplying missing methods for JDK 1.1 backwards compatibility.

    - ### Fields inherited from class org.acplt.oncrpc.OncRpcClient

      `auth, host, port, program, timeout, version, xid`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `OncRpcUdpClient​(java.net.InetAddress host, int program, int version, int port)` | Constructs a new `OncRpcUdpClient` object, which connects to the ONC/RPC server at `host` for calling remote procedures of the given { program, version }.
    `OncRpcUdpClient​(java.net.InetAddress host, int program, int version, int port, int bufferSize)` | Constructs a new `OncRpcUdpClient` object, which connects to the ONC/RPC server at `host` for calling remote procedures of the given { program, version }.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `broadcastCall​(int procedureNumber, XdrAble params, XdrAble result, OncRpcBroadcastListener listener)` | Broadcast a remote procedure call to several ONC/RPC servers.
    `void` | `call​(int procedureNumber, int versionNumber, XdrAble params, XdrAble result)` | Calls a remote procedure on an ONC/RPC server.
    `void` | `close()` | Close the connection to an ONC/RPC server and free all network-related resources.
    `java.lang.String` | `getCharacterEncoding()` | Get the character encoding for (de-)serializing strings.
    `int` | `getRetransmissionMode()` | Retrieve the current `retransmission mode` set for retransmission of lost ONC/RPC calls.
    `int` | `getRetransmissionTimeout()` | Retrieve the current retransmission timeout set for remote procedure calls.
    `void` | `setCharacterEncoding​(java.lang.String characterEncoding)` | Set the character encoding for (de-)serializing strings.
    `void` | `setRetransmissionMode​(int mode)` | Set the `retransmission mode` for lost remote procedure calls.
    `void` | `setRetransmissionTimeout​(int milliseconds)` | Set the retransmission timout for remote procedure calls to wait for an answer from the ONC/RPC server before resending the call.

    - ### Methods inherited from class org.acplt.oncrpc.OncRpcClient

      `call, getAuth, getHost, getPort, getProgram, getTimeout, getVersion, newOncRpcClient, newOncRpcClient, nextXid, setAuth, setTimeout`

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

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

- - ### Field Detail

    - #### socket

          private java.net.DatagramSocket socket

      UDP socket used for datagram-based communication with an ONC/RPC server.

    - #### socketHelper

          private OncRpcUdpSocketHelper socketHelper

      Socket helper object supplying missing methods for JDK 1.1 backwards compatibility. So much for compile once, does not run everywhere.

    - #### sendingXdr

          protected XdrUdpEncodingStream sendingXdr

      XDR encoding stream used for sending requests via UDP/IP to an ONC/RPC server.

    - #### receivingXdr

          protected XdrUdpDecodingStream receivingXdr

      XDR decoding stream used when receiving replies via UDP/IP from an ONC/RPC server.

    - #### retransmissionTimeout

          protected int retransmissionTimeout

      Retransmission timeout used for resending ONC/RPC calls when an ONC/RPC server does not answer fast enough. The default retransmission timeout is identical to the overall timeout for ONC/RPC calls (thus UDP/IP-based clients will not retransmit lost calls).
      See Also:
        `retransmissionMode`, `OncRpcClient.setTimeout(int)`

    - #### retransmissionMode

          protected int retransmissionMode

      Retransmission mode used when resending ONC/RPC calls. Default mode is `fixed timeout mode`.
      See Also:
        `OncRpcUdpRetransmissionMode`

  - ### Constructor Detail

    - #### OncRpcUdpClient

          public OncRpcUdpClient​(java.net.InetAddress host,
                                 int program,
                                 int version,
                                 int port)
                          throws OncRpcException,
                                 java.io.IOException

      Constructs a new `OncRpcUdpClient` object, which connects to the ONC/RPC server at `host` for calling remote procedures of the given { program, version }.

      Note that the construction of an `OncRpcUdpProtocolClient` object will result in communication with the portmap process at `host` if `port` is `0`.

      Parameters:
        `host` - The host where the ONC/RPC server resides.
        `program` - Program number of the ONC/RPC server to call.
        `version` - Program version number.
        `port` - The port number where the ONC/RPC server can be contacted. If `0`, then the `OncRpcUdpClient` object will ask the portmapper at `host` for the port number.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### OncRpcUdpClient

          public OncRpcUdpClient​(java.net.InetAddress host,
                                 int program,
                                 int version,
                                 int port,
                                 int bufferSize)
                          throws OncRpcException,
                                 java.io.IOException

      Constructs a new `OncRpcUdpClient` object, which connects to the ONC/RPC server at `host` for calling remote procedures of the given { program, version }.

      Note that the construction of an `OncRpcUdpProtocolClient` object will result in communication with the portmap process at `host` if `port` is `0`.

      Parameters:
        `host` - The host where the ONC/RPC server resides.
        `program` - Program number of the ONC/RPC server to call.
        `version` - Program version number.
        `port` - The port number where the ONC/RPC server can be contacted. If `0`, then the `OncRpcUdpClient` object will ask the portmapper at `host` for the port number.
        `bufferSize` - The buffer size used for sending and receiving UDP datagrams.
      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

      Close the connection to an ONC/RPC server and free all network-related resources. Well -- at least hope, that the Java VM will sometimes free some resources. Sigh.
      Overrides:
        `close` in class `OncRpcClient`
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.

    - #### call

          public void call​(int procedureNumber,
                           int versionNumber,
                           XdrAble params,
                           XdrAble result)
                    throws OncRpcException

      Calls a remote procedure on an ONC/RPC server.

      The `OncRpcUdpClient` uses a similar timeout scheme as the genuine Sun C implementation of ONC/RPC: it starts with a timeout of one second when waiting for a reply. If no reply is received within this time frame, the client doubles the timeout, sends a new request and then waits again for a reply. In every case the client will wait no longer than the total timeout set through the `OncRpcClient.setTimeout(int)` method.

      Specified by:
        `call` in class `OncRpcClient`
      Parameters:
        `procedureNumber` - Procedure number of the procedure to call.
        `versionNumber` - Protocol version number.
        `params` - The parameters of the procedure to call, contained in an object which implements the `XdrAble` interface.
        `result` - The object receiving the result of the procedure call.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.

    - #### broadcastCall

          public void broadcastCall​(int procedureNumber,
                                    XdrAble params,
                                    XdrAble result,
                                    OncRpcBroadcastListener listener)
                             throws OncRpcException

      Broadcast a remote procedure call to several ONC/RPC servers. For this you'll need to specify either a multicast address or the subnet's broadcast address when creating a `OncRpcUdpClient`. For every reply received, an event containing the reply is sent to the OncRpcBroadcastListener `listener`, which is the last parameter to the this method.

      In contrast to the `OncRpcClient.call(int, XdrAble, XdrAble)` method, `broadcastCall` will only send the ONC/RPC call once. It will then wait for answers until the timeout as set by `OncRpcClient.setTimeout(int)` expires without resending the reply.

      Note that you might experience unwanted results when using authentication types other than `OncRpcClientAuthNone`, causing messed up authentication protocol handling objects. This depends on the type of authentication used. For `AUTH_UNIX` nothing bad happens as long as none of the servers replies with a shorthand verifier. If it does, then this shorthand will be used on all subsequent ONC/RPC calls, something you probably do not want at all.

      Parameters:
        `procedureNumber` - Procedure number of the procedure to call.
        `params` - The parameters of the procedure to call, contained in an object which implements the `XdrAble` interface.
        `result` - The object receiving the result of the procedure call. Note that this object is reused to deserialize all incomming replies one after another.
        `listener` - Listener which will get an `OncRpcBroadcastEvent` for every reply received.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.

    - #### setRetransmissionMode

          public void setRetransmissionMode​(int mode)

      Set the `retransmission mode` for lost remote procedure calls. The default retransmission mode is `OncRpcUdpRetransmissionMode.FIXED`.
      Parameters:
        `mode` - Retransmission mode (either fixed or exponential).

    - #### getRetransmissionMode

          public int getRetransmissionMode()

      Retrieve the current `retransmission mode` set for retransmission of lost ONC/RPC calls.
      Returns:
        Current retransmission mode.

    - #### setRetransmissionTimeout

          public void setRetransmissionTimeout​(int milliseconds)

      Set the retransmission timout for remote procedure calls to wait for an answer from the ONC/RPC server before resending the call. The default retransmission timeout is the 30 seconds. The retransmission timeout must be > 0. To disable retransmission of lost calls, set the retransmission timeout to be the same value as the timeout.
      Parameters:
        `milliseconds` - Timeout in milliseconds. A timeout of zero indicates batched calls.

    - #### getRetransmissionTimeout

          public int getRetransmissionTimeout()

      Retrieve the current retransmission timeout set for remote procedure calls.
      Returns:
        Current retransmission timeout.

    - #### setCharacterEncoding

          public void setCharacterEncoding​(java.lang.String characterEncoding)

      Set the character encoding for (de-)serializing strings.
      Specified by:
        `setCharacterEncoding` in class `OncRpcClient`
      Parameters:
        `characterEncoding` - the encoding to use for (de-)serializing strings. If `null`, the system's default encoding is to be used.

    - #### getCharacterEncoding

          public java.lang.String getCharacterEncoding()

      Get the character encoding for (de-)serializing strings.
      Specified by:
        `getCharacterEncoding` in class `OncRpcClient`
      Returns:
        the encoding currently used for (de-)serializing strings. If `null`, then the system's default encoding is used.