org.acplt.oncrpc.server

## Class OncRpcServerTransport

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

Direct Known Subclasses:
  OncRpcTcpConnectionServerTransport, OncRpcTcpServerTransport, OncRpcUdpServerTransport

    public abstract class OncRpcServerTransport
    extends java.lang.Object

Instances of class `OncRpcServerTransport` encapsulate XDR streams of ONC/RPC servers. Using server transports, ONC/RPC calls are received and the corresponding replies are later sent back after handling.

Note that the server-specific dispatcher handling requests (done through `OncRpcDispatchable` will only directly deal with `OncRpcCallInformation` objects. These call information objects reference OncRpcServerTransport object, but the server programmer typically will never touch them, as the call information object already contains all necessary information about a call, so replies can be sent back (and this is definetely a sentence containing too many words).

Version:
  $Revision: 1.3 $ $Date: 2003/08/14 13:47:04 $ $State: Exp $ $Locker: $
Author:
  Harald Albrecht
See Also:
  `OncRpcCallInformation`, `OncRpcDispatchable`

### Field Summary

Fields
`protected OncRpcDispatchable` `dispatcher` Reference to interface of an object capable of handling/dispatching ONC/RPC requests.
`protected OncRpcServerTransportRegistrationInfo[]` `info` Program and version number tuples handled by this server transport.
`protected int` `port` Port number where we're listening for incoming ONC/RPC requests.

### Constructor Summary

Constructors
`protected` `OncRpcServerTransport(OncRpcDispatchable dispatcher, int port, OncRpcServerTransportRegistrationInfo[] info)` Create a new instance of a `OncRpcServerTransport` which encapsulates XDR streams of an ONC/RPC server.

### Method Summary

Methods
`protected abstract void` `beginEncoding(OncRpcCallInformation callInfo, OncRpcServerReplyMessage state)` Begins the sending phase for ONC/RPC replies.
`abstract void` `close()` Close the server transport and free any resources associated with it.
`protected abstract void` `endDecoding()` Finishes call parameter deserialization.
`protected abstract void` `endEncoding()` Finishes encoding the reply to this ONC/RPC call.
`abstract java.lang.String` `getCharacterEncoding()` Get the character encoding for (de-)serializing strings.
`int` `getPort()` Returns port number of socket this server transport listens on for incoming ONC/RPC calls.
`protected abstract XdrDecodingStream` `getXdrDecodingStream()` Returns XDR stream which can be used for deserializing the parameters of this ONC/RPC call.
`protected abstract XdrEncodingStream` `getXdrEncodingStream()` Returns XDR stream which can be used for eserializing the reply to this ONC/RPC call.
`abstract void` `listen()` Creates a new thread and uses this thread to listen to incoming ONC/RPC requests, then dispatches them and finally sends back the appropriate reply messages.
`abstract void` `register()` Register the port where this server transport waits for incoming requests with the ONC/RPC portmapper.
`protected abstract void` `reply(OncRpcCallInformation callInfo, OncRpcServerReplyMessage state, XdrAble reply)` Send back an ONC/RPC reply to the original caller.
`protected abstract void` `retrieveCall(XdrAble call)` Retrieves the parameters sent within an ONC/RPC call message.
`abstract void` `setCharacterEncoding(java.lang.String characterEncoding)` Set the character encoding for (de-)serializing strings.
`void` `unregister()` Unregisters the port where this server transport waits for incoming requests from the ONC/RPC portmapper.

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

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

### Field Detail

#### dispatcher

    protected OncRpcDispatchable dispatcher

Reference to interface of an object capable of handling/dispatching ONC/RPC requests.

#### port

    protected int port

Port number where we're listening for incoming ONC/RPC requests.

#### info

    protected OncRpcServerTransportRegistrationInfo[] info

Program and version number tuples handled by this server transport.

### Constructor Detail

#### OncRpcServerTransport

    protected OncRpcServerTransport(OncRpcDispatchable dispatcher,
                         int port,
                         OncRpcServerTransportRegistrationInfo[] info)

Create a new instance of a `OncRpcServerTransport` which encapsulates XDR streams of an ONC/RPC server. Using a server transport, ONC/RPC calls are received and the corresponding replies are sent back.

We do not create any XDR streams here, as it is the responsibility of derived classes to create appropriate XDR stream objects for the respective kind of transport mechanism used (like TCP/IP and UDP/IP).

Parameters:
  `dispatcher` - Reference to interface of an object capable of dispatching (handling) ONC/RPC calls.
  `port` - Number of port where the server will wait for incoming calls.
  `info` - Array of program and version number tuples of the ONC/RPC programs and versions handled by this transport.

### Method Detail

#### register

    public abstract void register()
                           throws OncRpcException

Register the port where this server transport waits for incoming requests with the ONC/RPC portmapper.

The contract of this method is, that derived classes implement the appropriate communication with the portmapper, so the transport is registered only for the protocol supported by a particular kind of server transport.

Throws:
  `OncRpcException` - if the portmapper could not be contacted successfully.

#### unregister

    public void unregister()
                    throws OncRpcException

Unregisters the port where this server transport waits for incoming requests from the ONC/RPC portmapper.

Note that due to the way Sun decided to implement its ONC/RPC portmapper process, deregistering one server transports causes all entries for the same program and version to be removed, regardless of the protocol (UDP/IP or TCP/IP) used. Sigh.

Throws:
  `OncRpcException` - with a reason of `OncRpcException.RPC_FAILED` if the portmapper could not be contacted successfully. Note that it is not considered an error to remove a non-existing entry from the portmapper.

#### close

    public abstract void close()

Close the server transport and free any resources associated with it.

Note that the server transport is not deregistered. You'll have to do it manually if you need to do so. The reason for this behaviour is, that the portmapper removes all entries regardless of the protocol (TCP/IP or UDP/IP) for a given ONC/RPC program number and version.

Derived classes can choose between different behaviour for shuting down the associated transport handler threads:

- Close the transport immediately and let the threads stumble on the closed network connection.
- Wait for handler threads to complete their current ONC/RPC request (with timeout), then close connections and kill the threads.

#### listen

    public abstract void listen()

Creates a new thread and uses this thread to listen to incoming ONC/RPC requests, then dispatches them and finally sends back the appropriate reply messages.

Note that you have to supply an implementation for this abstract method in derived classes. Your implementation needs to create a new thread to wait for incoming requests. The method has to return immediately for the calling thread.

#### getPort

    public int getPort()

Returns port number of socket this server transport listens on for incoming ONC/RPC calls.

Returns:
  Port number of socket listening for incoming calls.

#### setCharacterEncoding

    public abstract void setCharacterEncoding(java.lang.String characterEncoding)

Set the character encoding for (de-)serializing strings.

Parameters:
  `characterEncoding` - the encoding to use for (de-)serializing strings. If `null`, the system's default encoding is to be used.

#### getCharacterEncoding

    public abstract java.lang.String getCharacterEncoding()

Get the character encoding for (de-)serializing strings.

Returns:
  the encoding currently used for (de-)serializing strings. If `null`, then the system's default encoding is used.

#### retrieveCall

    protected abstract 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. Under the hood this method therefore calls `XdrDecodingStream.endDecoding()` to free any pending resources from the decoding stage.

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

    protected abstract 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

    protected abstract 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.

#### getXdrEncodingStream

    protected abstract 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.

#### beginEncoding

    protected abstract void beginEncoding(OncRpcCallInformation callInfo,
                     OncRpcServerReplyMessage state)
                                   throws OncRpcException,
                                          java.io.IOException

Begins the sending phase for ONC/RPC replies. This method belongs to the lower-level access pattern when handling ONC/RPC calls.

Parameters:
  `callInfo` - Information about ONC/RPC call for which we are about to send back the reply.
  `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

#### endEncoding

    protected abstract 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

    protected abstract void reply(OncRpcCallInformation callInfo,
             OncRpcServerReplyMessage state,
             XdrAble reply)
                           throws OncRpcException,
                                  java.io.IOException

Send back an ONC/RPC reply to the original caller. This is rather a low-level method, typically not used by applications. Dispatcher handling ONC/RPC calls have to use the `OncRpcCallInformation.reply(XdrAble)` method instead on the call object supplied to the handler.

An appropriate implementation has to be provided in derived classes as it is dependent on the type of transport (whether UDP/IP or TCP/IP) used.

Parameters:
  `callInfo` - information about the original call, which are necessary to send back the reply to the appropriate caller.
  `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:
  `OncRpcCallInformation`, `OncRpcDispatchable`