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.7 $ $Date: 2009/02/25 19:20:40 $ $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.

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

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

## Constructor Summary

Constructors
Constructor
Description
`OncRpcUdpClient(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(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

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.
`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(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 Details

### 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 Details

### OncRpcUdpClient

public OncRpcUdpClient(InetAddress host, int program, int version, int port) throws OncRpcException, 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.
  `IOException` - if an I/O error occurs.

### OncRpcUdpClient

public OncRpcUdpClient(InetAddress host, int program, int version, int port, int bufferSize) throws OncRpcException, 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.
  `IOException` - if an I/O error occurs.

## Method Details

### 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(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 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.