Package org.acplt.oncrpc

## Class OncRpcTcpClient

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

-     public class OncRpcTcpClient
      extends OncRpcClient

  ONC/RPC client which communicates with ONC/RPC servers over the network using the stream-oriented protocol TCP/IP.
  Version:
    $Revision: 1.5 $ $Date: 2005/11/11 21:04:30 $ $State: Exp $ $Locker: $
  Author:
    Harald Albrecht

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected XdrTcpDecodingStream` | `receivingXdr` | XDR decoding stream used when receiving replies via TCP/IP from an ONC/RPC server.
    `protected XdrTcpEncodingStream` | `sendingXdr` | XDR encoding stream used for sending requests via TCP/IP to an ONC/RPC server.
    `private java.net.Socket` | `socket` | TCP socket used for stream-oriented communication with an ONC/RPC server.
    `private OncRpcTcpSocketHelper` | `socketHelper` | Socket helper object supplying missing methods for JDK 1.1 backwards compatibility.
    `protected int` | `transmissionTimeout` | Timeout during the phase where data is sent within calls, or data is received within replies.

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

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

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `OncRpcTcpClient​(java.net.InetAddress host, int program, int version)` | Constructs a new `OncRpcTcpClient` object, which connects to the ONC/RPC server at `host` for calling remote procedures of the given { program, version }.
    `OncRpcTcpClient​(java.net.InetAddress host, int program, int version, int port)` | Constructs a new `OncRpcTcpClient` object, which connects to the ONC/RPC server at `host` for calling remote procedures of the given { program, version }.
    `OncRpcTcpClient​(java.net.InetAddress host, int program, int version, int port, int bufferSize)` | Constructs a new `OncRpcTcpClient` object, which connects to the ONC/RPC server at `host` for calling remote procedures of the given { program, version }.
    `OncRpcTcpClient​(java.net.InetAddress host, int program, int version, int port, int bufferSize, int timeout)` | Constructs a new `OncRpcTcpClient` 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` | `batchCall​(int procedureNumber, XdrAble params, boolean flush)` | Issues a batched call for a remote procedure to an ONC/RPC server.
    `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` | `getTransmissionTimeout()` | Retrieve the current timeout used during transmission phases (call and reply phases).
    `void` | `setCharacterEncoding​(java.lang.String characterEncoding)` | Set the character encoding for (de-)serializing strings.
    `void` | `setTimeout​(int milliseconds)` | Set the timout for remote procedure calls to wait for an answer from the ONC/RPC server.
    `void` | `setTransmissionTimeout​(int milliseconds)` | Set the timeout used during transmission of data.

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

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

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

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

- - ### Field Detail

    - #### socket

          private java.net.Socket socket

      TCP socket used for stream-oriented communication with an ONC/RPC server.

    - #### socketHelper

          private OncRpcTcpSocketHelper socketHelper

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

    - #### sendingXdr

          protected XdrTcpEncodingStream sendingXdr

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

    - #### receivingXdr

          protected XdrTcpDecodingStream receivingXdr

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

    - #### transmissionTimeout

          protected int transmissionTimeout

      Timeout during the phase where data is sent within calls, or data is received within replies.

  - ### Constructor Detail

    - #### OncRpcTcpClient

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

      Constructs a new `OncRpcTcpClient` 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 `OncRpcTcpClient` object will result in communication with the portmap process at `host`.

      Parameters:
        `host` - The host where the ONC/RPC server resides.
        `program` - Program number of the ONC/RPC server to call.
        `version` - Program version number.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### OncRpcTcpClient

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

      Constructs a new `OncRpcTcpClient` 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 `OncRpcTcpClient` 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.

    - #### OncRpcTcpClient

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

      Constructs a new `OncRpcTcpClient` 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 `OncRpcTcpClient` 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` - Size of receive and send buffers. In contrast to UDP-based ONC/RPC clients, messages larger than the specified buffer size can still be sent and received. The buffer is only necessary to handle the messages and the underlaying streams will break up long messages automatically into suitable pieces. Specifying zero will select the default buffer size (currently 8192 bytes).
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### OncRpcTcpClient

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

      Constructs a new `OncRpcTcpClient` 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 `OncRpcTcpClient` 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` - Size of receive and send buffers. In contrast to UDP-based ONC/RPC clients, messages larger than the specified buffer size can still be sent and received. The buffer is only necessary to handle the messages and the underlaying streams will break up long messages automatically into suitable pieces. Specifying zero will select the default buffer size (currently 8192 bytes).
        `timeout` - Maximum timeout in milliseconds when connecting to the ONC/RPC server. If negative, a default implementation-specific timeout setting will apply. Note that this timeout only applies to the connection phase, but not to later communication.
      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.

      Please note that while this method supports call batching by setting the communication timeout to zero (`setTimeout(0)`) you should better use `batchCall(int, org.acplt.oncrpc.XdrAble, boolean)` as it provides better control over when the batch should be flushed to the server.

      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.

    - #### batchCall

          public void batchCall​(int procedureNumber,
                                XdrAble params,
                                boolean flush)
                         throws OncRpcException

      Issues a batched call for a remote procedure to an ONC/RPC server. Below is a small example (exception handling ommited for clarity):

           OncRpcTcpClient client = new OncRpcTcpClient(
               InetAddress.getByName("localhost"),
               myprogramnumber, myprogramversion,
               OncRpcProtocols.ONCRPC_TCP);
           client.callBatch(42, myparams, false);
           client.callBatch(42, myotherparams, false);
           client.callBatch(42, myfinalparams, true);

      In the example above, three calls are batched in a row and only be sent all together with the third call. Note that batched calls must not expect replies, with the only exception being the last call in a batch:

           client.callBatch(42, myparams, false);
           client.callBatch(42, myotherparams, false);
           client.call(43, myfinalparams, myfinalresult);

      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.
        `flush` - Make sure that all pending batched calls are sent to the server.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.

    - #### setTimeout

          public void setTimeout​(int milliseconds)

      Set the timout for remote procedure calls to wait for an answer from the ONC/RPC server. If the timeout expires, `OncRpcClient.call(int, XdrAble, XdrAble)` will raise a `InterruptedIOException`. The default timeout value is 30 seconds (30,000 milliseconds). The timeout must be > 0. A timeout of zero indicates a batched call, for which no reply message is expected.
      Overrides:
        `setTimeout` in class `OncRpcClient`
      Parameters:
        `milliseconds` - Timeout in milliseconds. A timeout of zero indicates batched calls.

    - #### setTransmissionTimeout

          public void setTransmissionTimeout​(int milliseconds)

      Set the timeout used during transmission of data. If the flow of data when sending calls or receiving replies blocks longer than the given timeout, an exception is thrown. The timeout must be > 0.
      Parameters:
        `milliseconds` - Transmission timeout in milliseconds.

    - #### getTransmissionTimeout

          public int getTransmissionTimeout()

      Retrieve the current timeout used during transmission phases (call and reply phases).
      Returns:
        Current transmission 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.