org.acplt.oncrpc.server
Interface OncRpcDispatchable

All Known Implementing Classes:

jportmap, OncRpcEmbeddedPortmap.embeddedjportmap

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;
     }
 }
 

Method Summary

void	dispatchOncRpcCall(OncRpcCallInformation call, int program, int version, int procedure) Dispatch (handle) an ONC/RPC request from a client.

Method Detail

dispatchOncRpcCall

void dispatchOncRpcCall(OncRpcCallInformation call,
                        int program,
                        int version,
                        int procedure)
                        throws OncRpcException,
                               java.io.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

java.io.IOException

See Also:

OncRpcCallInformation