org.acplt.oncrpc.server

## Class OncRpcCallInformation

- java.lang.Object
- - org.acplt.oncrpc.server.OncRpcCallInformation

    public class OncRpcCallInformation
    extends java.lang.Object

Objects of class `OncRpcCallInformation` contain information about individual ONC/RPC calls. They are given to ONC/RPC `call dispatchers`, so they can send back the reply to the appropriate caller, etc. Use only this call info objects to retrieve call parameters and send back replies as in the future UDP/IP-based transports may become multi-threaded handling. The call info object is responsible to control access to the underlaying transport, so never mess with the transport directly.

Note that this class provides two different patterns for accessing parameters sent by clients within the ONC/RPC call and sending back replies.

1. The convenient high-level access:
   - Use `retrieveCall(XdrAble)` to retrieve the parameters of the call and deserialize it into a paramter object.
   - Use `reply(XdrAble)` to send back the reply by serializing a reply/result object. Or use the `failXXX` methods to send back an error indication instead.
2. The lower-level access, giving more control over how and when data is deserialized and serialized:
   - Use `getXdrDecodingStream()` to get a reference to the XDR stream from which you can deserialize the call's parameter.
   - When you are finished deserializing, call `endDecoding()`.
   - To send back the reply/result, call `beginEncoding(OncRpcServerReplyMessage)`. Using the XDR stream returned by `getXdrEncodingStream()` serialize the reply/result. Finally finish the serializing step by calling `endEncoding()`.

Version:
  $Revision: 1.3 $ $Date: 2003/08/14 11:26:50 $ $State: Exp $ $Locker: $
Author:
  Harald Albrecht
See Also:
  `OncRpcDispatchable`

### Field Summary

Fields
`OncRpcServerCallMessage` `callMessage` Contains the call message header from ONC/RPC identifying this particular call.
`java.net.InetAddress` `peerAddress` Internet address of the peer from which we received an ONC/RPC call or whom we intend to call.
`int` `peerPort` Port number of the peer from which we received an ONC/RPC call or whom we intend to call.
`protected OncRpcServerTransport` `transport` Associated transport from which we receive the ONC/RPC call parameters and to which we serialize the ONC/RPC reply.

### Constructor Summary

Constructors
`protected` `OncRpcCallInformation(OncRpcServerTransport transport)` Create an `OncRpcCallInformation` object and associate it with a ONC/RPC server transport.

### Method Summary

Methods
`void` `beginEncoding()` Begins the sending phase for accepted ONC/RPC replies.
`void` `beginEncoding(OncRpcServerReplyMessage state)` Begins the sending phase for ONC/RPC replies.
`void` `endDecoding()` Finishes call parameter deserialization.
`void` `endEncoding()` Finishes encoding the reply to this ONC/RPC call.
`void` `failArgumentGarbage()` Send back an ONC/RPC failure indication about invalid arguments to the caller who sent in this call.
`void` `failAuthenticationFailed(int authStatus)` Send back an ONC/RPC failure indication about a failed authentication to the caller who sent in this call.
`void` `failOncRpcVersionMismatch()` Send back an ONC/RPC failure indication about a ONC/RPC version mismatch call to the caller who sent in this call.
`void` `failProcedureUnavailable()` Send back an ONC/RPC failure indication about an unavailable procedure call to the caller who sent in this call.
`void` `failProgramMismatch(int lowVersion, int highVersion)` Send back an ONC/RPC failure indication about a program version mismatch to the caller who sent in this call.
`void` `failProgramUnavailable()` Send back an ONC/RPC failure indication about an unavailable program to the caller who sent in this call.
`void` `failSystemError()` Send back an ONC/RPC failure indication about a system error to the caller who sent in this call.
`XdrDecodingStream` `getXdrDecodingStream()` Returns XDR stream which can be used for deserializing the parameters of this ONC/RPC call.
`XdrEncodingStream` `getXdrEncodingStream()` Returns XDR stream which can be used for eserializing the reply to this ONC/RPC call.
`void` `reply(OncRpcServerReplyMessage state, XdrAble reply)` Send back an ONC/RPC reply to the caller who sent in this call.
`void` `reply(XdrAble reply)` Send back an ONC/RPC reply to the caller who sent in this call.
`void` `retrieveCall(XdrAble call)` Retrieves the parameters sent within an ONC/RPC call message.

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

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

### Field Detail

#### callMessage

    public OncRpcServerCallMessage callMessage

Contains the call message header from ONC/RPC identifying this particular call.

#### peerAddress

    public java.net.InetAddress peerAddress

Internet address of the peer from which we received an ONC/RPC call or whom we intend to call.

#### peerPort

    public int peerPort

Port number of the peer from which we received an ONC/RPC call or whom we intend to call.

#### transport

    protected OncRpcServerTransport transport

Associated transport from which we receive the ONC/RPC call parameters and to which we serialize the ONC/RPC reply. Never mess with this member or you might break all future extensions horribly -- but this warning probably only stimulates you...

### Constructor Detail

#### OncRpcCallInformation

    protected OncRpcCallInformation(OncRpcServerTransport transport)

Create an `OncRpcCallInformation` object and associate it with a ONC/RPC server transport. Typically, `OncRpcCallInformation` objects are created by transports once before handling incoming calls using the same call info object. To support multithreaded handling of calls in the future (for UDP/IP), the transport is already divided from the call info.

Parameters:
  `transport` - ONC/RPC server transport.

### Method Detail

#### retrieveCall

    public void retrieveCall(XdrAble call)
                      throws OncRpcException,
                             java.io.IOException

Retrieves the parameters sent within an ONC/RPC call message. It also makes sure that the deserialization process is properly finished after the call parameters have been retrieved.

Throws:
  `OncRpcException` - if an ONC/RPC exception occurs, like the data could not be successfully deserialized.
  `java.io.IOException` - if an I/O exception occurs, like transmission failures over the network, etc.

#### getXdrDecodingStream

    public XdrDecodingStream getXdrDecodingStream()

Returns XDR stream which can be used for deserializing the parameters of this ONC/RPC call. This method belongs to the lower-level access pattern when handling ONC/RPC calls.

Returns:
  Reference to decoding XDR stream.

#### endDecoding

    public void endDecoding()
                     throws OncRpcException,
                            java.io.IOException

Finishes call parameter deserialization. Afterwards the XDR stream returned by `getXdrDecodingStream()` must not be used any more. This method belongs to the lower-level access pattern when handling ONC/RPC calls.

Throws:
  `OncRpcException` - if an ONC/RPC exception occurs, like the data could not be successfully deserialized.
  `java.io.IOException` - if an I/O exception occurs, like transmission failures over the network, etc.

#### beginEncoding

    public void beginEncoding(OncRpcServerReplyMessage state)
                       throws OncRpcException,
                              java.io.IOException

Begins the sending phase for ONC/RPC replies. After beginning sending you can serialize the reply/result (but only if the call was accepted, see `OncRpcReplyMessage` for details). The stream to use for serialization can be obtained using `getXdrEncodingStream()`. This method belongs to the lower-level access pattern when handling ONC/RPC calls.

Parameters:
  `state` - ONC/RPC reply header indicating success or failure.
Throws:
  `OncRpcException` - if an ONC/RPC exception occurs, like the data could not be successfully serialized.
  `java.io.IOException` - if an I/O exception occurs, like transmission failures over the network, etc.

#### beginEncoding

    public void beginEncoding()
                       throws OncRpcException,
                              java.io.IOException

Begins the sending phase for accepted ONC/RPC replies. After beginning sending you can serialize the result/reply. The stream to use for serialization can be obtained using `getXdrEncodingStream()`. This method belongs to the lower-level access pattern when handling ONC/RPC calls.

Throws:
  `OncRpcException` - if an ONC/RPC exception occurs, like the data could not be successfully serialized.
  `java.io.IOException` - if an I/O exception occurs, like transmission failures over the network, etc.

#### getXdrEncodingStream

    public XdrEncodingStream getXdrEncodingStream()

Returns XDR stream which can be used for eserializing the reply to this ONC/RPC call. This method belongs to the lower-level access pattern when handling ONC/RPC calls.

Returns:
  Reference to enecoding XDR stream.

#### endEncoding

    public void endEncoding()
                     throws OncRpcException,
                            java.io.IOException

Finishes encoding the reply to this ONC/RPC call. Afterwards you must not use the XDR stream returned by `getXdrEncodingStream()` any longer.

Throws:
  `OncRpcException` - if an ONC/RPC exception occurs, like the data could not be successfully serialized.
  `java.io.IOException` - if an I/O exception occurs, like transmission failures over the network, etc.

#### reply

    public void reply(OncRpcServerReplyMessage state,
             XdrAble reply)
               throws OncRpcException,
                      java.io.IOException

Send back an ONC/RPC reply to the caller who sent in this call. This is a low-level function and typically should not be used by call dispatchers. Instead use the other `reply method` which just expects a serializable object to send back to the caller.

Parameters:
  `state` - ONC/RPC reply message header indicating success or failure and containing associated state information.
  `reply` - If not `null`, then this parameter references the reply to be serialized after the reply message header.
Throws:
  `OncRpcException` - if an ONC/RPC exception occurs, like the data could not be successfully serialized.
  `java.io.IOException` - if an I/O exception occurs, like transmission failures over the network, etc.
See Also:
  `OncRpcReplyMessage`, `OncRpcDispatchable`

#### reply

    public void reply(XdrAble reply)
               throws OncRpcException,
                      java.io.IOException

Send back an ONC/RPC reply to the caller who sent in this call. This automatically sends an ONC/RPC reply header before the reply part, indicating success within the header.

Parameters:
  `reply` - Reply body the ONC/RPC reply message.
Throws:
  `OncRpcException` - if an ONC/RPC exception occurs, like the data could not be successfully serialized.
  `java.io.IOException` - if an I/O exception occurs, like transmission failures over the network, etc.

#### failArgumentGarbage

    public void failArgumentGarbage()
                             throws OncRpcException,
                                    java.io.IOException

Send back an ONC/RPC failure indication about invalid arguments to the caller who sent in this call.

Throws:
  `OncRpcException` - if an ONC/RPC exception occurs, like the data could not be successfully serialized.
  `java.io.IOException` - if an I/O exception occurs, like transmission failures over the network, etc.

#### failProcedureUnavailable

    public void failProcedureUnavailable()
                                  throws OncRpcException,
                                         java.io.IOException

Send back an ONC/RPC failure indication about an unavailable procedure call to the caller who sent in this call.

Throws:
  `OncRpcException` - if an ONC/RPC exception occurs, like the data could not be successfully serialized.
  `java.io.IOException` - if an I/O exception occurs, like transmission failures over the network, etc.

#### failProgramUnavailable

    public void failProgramUnavailable()
                                throws OncRpcException,
                                       java.io.IOException

Send back an ONC/RPC failure indication about an unavailable program to the caller who sent in this call.

Throws:
  `OncRpcException` - if an ONC/RPC exception occurs, like the data could not be successfully serialized.
  `java.io.IOException` - if an I/O exception occurs, like transmission failures over the network, etc.

#### failProgramMismatch

    public void failProgramMismatch(int lowVersion,
                           int highVersion)
                             throws OncRpcException,
                                    java.io.IOException

Send back an ONC/RPC failure indication about a program version mismatch to the caller who sent in this call.

Parameters:
  `lowVersion` - lowest supported program version.
  `highVersion` - highest supported program version.
Throws:
  `OncRpcException` - if an ONC/RPC exception occurs, like the data could not be successfully serialized.
  `java.io.IOException` - if an I/O exception occurs, like transmission failures over the network, etc.

#### failSystemError

    public void failSystemError()
                         throws OncRpcException,
                                java.io.IOException

Send back an ONC/RPC failure indication about a system error to the caller who sent in this call.

Throws:
  `OncRpcException` - if an ONC/RPC exception occurs, like the data could not be successfully serialized.
  `java.io.IOException` - if an I/O exception occurs, like transmission failures over the network, etc.

#### failOncRpcVersionMismatch

    public void failOncRpcVersionMismatch()
                                   throws OncRpcException,
                                          java.io.IOException

Send back an ONC/RPC failure indication about a ONC/RPC version mismatch call to the caller who sent in this call.

Throws:
  `OncRpcException` - if an ONC/RPC exception occurs, like the data could not be successfully serialized.
  `java.io.IOException` - if an I/O exception occurs, like transmission failures over the network, etc.

#### failAuthenticationFailed

    public void failAuthenticationFailed(int authStatus)
                                  throws OncRpcException,
                                         java.io.IOException

Send back an ONC/RPC failure indication about a failed authentication to the caller who sent in this call.

Parameters:
  `authStatus` - `Reason` why authentication failed.
Throws:
  `OncRpcException` - if an ONC/RPC exception occurs, like the data could not be successfully serialized.
  `java.io.IOException` - if an I/O exception occurs, like transmission failures over the network, etc.