Package org.acplt.oncrpc.server

# Interface OncRpcDispatchable

All Known Implementing Classes:
  `jportmap`

public interface OncRpcDispatchable
Tags classes as being able to dispatch and handle ONC/RPC requests from clients.

This interface is used as follows for dispatching and handling ONC/RPC calls:

- First check which procedure the client intends to call. This information is delivered through the `procedure` parameter. In case you do not handle multiple programs within the same dispatcher, you can ignore the `program` parameter as well as `version`.
- Retrieve appropriate parameters for this intended procedure using the `OncRpcCallInformation.retrieveCall(org.acplt.oncrpc.XdrAble)` method of the `call` object also supplied to the dispatcher through the `call` parameter.
- Do whatever you need to do for this ONC/RPC call and make up an appropriate reply to be sent back to the client in the next step.
- Send back the reply by calling the `OncRpcCallInformation.reply(org.acplt.oncrpc.server.OncRpcServerReplyMessage, org.acplt.oncrpc.XdrAble)` method of the `call` object

Here's a simple example only showing how to handle the famous procedure `0`: this is the "ping" procedure which can be used to test whether the server is still living. The example also shows how to handle calls for procedures which are not implemented (not defined) by calling `OncRpcCallInformation.failProcedureUnavailable()`.

In case the dispatcher throws an exception, the affected ONC/RPC server transport will send a system error indication `OncRpcCallInformation.failSystemError()` to the client. No error indication will be sent if the exception resulted from an I/O problem. Note that if you do not explicitely send back a reply, no reply is sent at all, making batched calls possible.

     public void dispatchOncRpcCall(OncRpcCallInformation call,
                                    int program, int version, int procedure)
            throws OncRpcException, IOException {
         switch ( procedure ) {
         case 0:
             XdrVoid v = new XdrVoid();
             call.retrieveCall(v);
             call.reply(v);
             break;
         default:
             call.failProcedureUnavailable();
         }
     }

In addition, there are also lower-level methods available for retrieving parameters and sending replies, in case you need to break up deserialization and serialization into several steps. The following code snipped shows how to use them. Here, the objects `foo` and `bar` represents call parameter objects, while `baz` and `blah` are used to sent back the reply data.

     public void dispatchOncRpcCall(OncRpcCallInformation call,
                                    int program, int version, int procedure)
            throws OncRpcException, IOException {
         switch ( procedure ) {
         case 42:
             // Retrieve call parameters.
             XdrDecodingStream decoder = call.getXdrDecodingStream();
             foo.xdrDecode(decoder);
             bar.xdrDecode(decoder);
             call.endDecoding();
             // Handle particular ONC/RPC call...

             // Send back reply.
             call.beginEncoding();
             XdrEncodingStream encoder = call.getXdrEncodingStream();
             baz.xdrEncode(encoder);
             blah.xdrEncode(encoder);
             call.endEncoding();
             break;
         }
     }

Version:
  $Revision: 1.1 $ $Date: 2003/08/13 12:03:51 $ $State: Exp $ $Locker: $
Author:
  Harald Albrecht

## Method Summary

Modifier and Type
Method
Description
`void`
`dispatchOncRpcCall(OncRpcCallInformation call, int program, int version, int procedure)`
Dispatch (handle) an ONC/RPC request from a client.

## Method Details

### dispatchOncRpcCall

void dispatchOncRpcCall(OncRpcCallInformation call, int program, int version, int procedure) throws OncRpcException, IOException
Dispatch (handle) an ONC/RPC request from a client. This interface has some fairly deep semantics, so please read the description above for how to use it properly. For background information about fairly deep semantics, please also refer to Gigzales, J.: Semantics considered harmful. Addison-Reilly, 1992, ISBN 0-542-10815-X.

See the introduction to this class for examples of how to use this interface properly.

Parameters:
  `call` - Information about the call to handle, like the caller's Internet address, the ONC/RPC call header, etc.
  `program` - Program number requested by client.
  `version` - Version number requested.
  `procedure` - Procedure number requested.
Throws:
  `OncRpcException` - if the passed request cannot be served for some reason such as a unknown procedure number.
  `IOException` - if for some reason an IO error occurs serving the request.
See Also:
  - `OncRpcCallInformation`