Package org.acplt.oncrpc.server

## Class OncRpcUdpServerTransport

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

-     public class OncRpcUdpServerTransport
      extends OncRpcServerTransport

  Instances of class `OncRpcUdpServerTransport` encapsulate UDP/IP-based XDR streams of ONC/RPC servers. This server transport class is responsible for receiving ONC/RPC calls over UDP/IP.
  Version:
    $Revision: 1.4 $ $Date: 2008/01/02 15:13:35 $ $State: Exp $ $Locker: $
  Author:
    Harald Albrecht
  See Also:
    `OncRpcServerTransport`, `OncRpcTcpServerTransport`

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `private boolean` | `pendingDecoding` | Indicates that `BeginDecoding` has been called for the receiving XDR stream, so that it should be closed later using `EndDecoding`.
    `private XdrUdpDecodingStream` | `receivingXdr` | XDR decoding stream used when receiving requests via UDP/IP from ONC/RPC clients.
    `private XdrUdpEncodingStream` | `sendingXdr` | XDR encoding stream used for sending replies via UDP/IP back to an ONC/RPC client.
    `private java.net.DatagramSocket` | `socket` | UDP socket used for datagram-based communication with ONC/RPC clients.
    `private OncRpcUdpSocketHelper` | `socketHelper` | Socket helper object supplying missing methods for JDK 1.1 backwards compatibility.

    - ### Fields inherited from class org.acplt.oncrpc.server.OncRpcServerTransport

      `dispatcher, info, port`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `OncRpcUdpServerTransport​(OncRpcDispatchable dispatcher, int port, int program, int version, int bufferSize)` | Create a new instance of a `OncRpcUdpServerTransport` which encapsulates UDP/IP-based XDR streams of an ONC/RPC server.
    `OncRpcUdpServerTransport​(OncRpcDispatchable dispatcher, int port, OncRpcServerTransportRegistrationInfo[] info, int bufferSize)` | Create a new instance of a `OncRpcUdpServerTransport` which encapsulates UDP/IP-based XDR streams of an ONC/RPC server.
    `OncRpcUdpServerTransport​(OncRpcDispatchable dispatcher, java.net.InetAddress bindAddr, int port, OncRpcServerTransportRegistrationInfo[] info, int bufferSize)` | Create a new instance of a `OncRpcUdpServerTransport` which encapsulates UDP/IP-based XDR streams of an ONC/RPC server.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `_listen()` | The real workhorse handling incoming requests, dispatching them and sending back replies.
    `protected void` | `beginEncoding​(OncRpcCallInformation callInfo, OncRpcServerReplyMessage state)` | Begins the sending phase for ONC/RPC replies.
    `void` | `close()` | Close the server transport and free any resources associated with it.
    `protected void` | `endDecoding()` | Finishes call parameter deserialization.
    `protected void` | `endEncoding()` | Finishes encoding the reply to this ONC/RPC call.
    `java.lang.String` | `getCharacterEncoding()` | Get the character encoding for (de-)serializing strings.
    `protected XdrDecodingStream` | `getXdrDecodingStream()` | Returns XDR stream which can be used for deserializing the parameters of this ONC/RPC call.
    `protected XdrEncodingStream` | `getXdrEncodingStream()` | Returns XDR stream which can be used for eserializing the reply to this ONC/RPC call.
    `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.
    `void` | `register()` | Register the UDP/IP port where this server transport waits for incoming requests with the ONC/RPC portmapper.
    `protected void` | `reply​(OncRpcCallInformation callInfo, OncRpcServerReplyMessage state, XdrAble reply)` | Send back an ONC/RPC reply to the original caller.
    `protected void` | `retrieveCall​(XdrAble call)` | Retrieves the parameters sent within an ONC/RPC call message.
    `void` | `setCharacterEncoding​(java.lang.String characterEncoding)` | Set the character encoding for (de-)serializing strings.

    - ### Methods inherited from class org.acplt.oncrpc.server.OncRpcServerTransport

      `getPort, unregister`

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

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

- - ### Field Detail

    - #### socket

          private java.net.DatagramSocket socket

      UDP socket used for datagram-based communication with ONC/RPC clients.

    - #### socketHelper

          private OncRpcUdpSocketHelper socketHelper

      Socket helper object supplying missing methods for JDK 1.1 backwards compatibility. So much for compile once, does not run everywhere.

    - #### sendingXdr

          private XdrUdpEncodingStream sendingXdr

      XDR encoding stream used for sending replies via UDP/IP back to an ONC/RPC client.

    - #### receivingXdr

          private XdrUdpDecodingStream receivingXdr

      XDR decoding stream used when receiving requests via UDP/IP from ONC/RPC clients.

    - #### pendingDecoding

          private boolean pendingDecoding

      Indicates that `BeginDecoding` has been called for the receiving XDR stream, so that it should be closed later using `EndDecoding`.

  - ### Constructor Detail

    - #### OncRpcUdpServerTransport

          public OncRpcUdpServerTransport​(OncRpcDispatchable dispatcher,
                                          int port,
                                          int program,
                                          int version,
                                          int bufferSize)
                                   throws OncRpcException,
                                          java.io.IOException

      Create a new instance of a `OncRpcUdpServerTransport` which encapsulates UDP/IP-based XDR streams of an ONC/RPC server. Using a server transport, ONC/RPC calls are received and the corresponding replies are sent back. This constructor is a convenience constructor for those transports handling only a single ONC/RPC program and version number.
      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.
        `program` - Number of ONC/RPC program handled by this server transport.
        `version` - Version number of ONC/RPC program handled.
        `bufferSize` - Size of buffer for receiving and sending UDP/IP datagrams containing ONC/RPC call and reply messages.
      Throws:
        `OncRpcException`
        `java.io.IOException`

    - #### OncRpcUdpServerTransport

          public OncRpcUdpServerTransport​(OncRpcDispatchable dispatcher,
                                          int port,
                                          OncRpcServerTransportRegistrationInfo[] info,
                                          int bufferSize)
                                   throws OncRpcException,
                                          java.io.IOException

      Create a new instance of a `OncRpcUdpServerTransport` which encapsulates UDP/IP-based XDR streams of an ONC/RPC server. Using a server transport, ONC/RPC calls are received and the corresponding replies are sent back. This constructor is a convenience constructor for those transports handling only a single ONC/RPC program and version number.
      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.
        `bufferSize` - Size of buffer for receiving and sending UDP/IP datagrams containing ONC/RPC call and reply messages.
      Throws:
        `OncRpcException`
        `java.io.IOException`

    - #### OncRpcUdpServerTransport

          public OncRpcUdpServerTransport​(OncRpcDispatchable dispatcher,
                                          java.net.InetAddress bindAddr,
                                          int port,
                                          OncRpcServerTransportRegistrationInfo[] info,
                                          int bufferSize)
                                   throws OncRpcException,
                                          java.io.IOException

      Create a new instance of a `OncRpcUdpServerTransport` which encapsulates UDP/IP-based XDR streams of an ONC/RPC server. Using a server transport, ONC/RPC calls are received and the corresponding replies are sent back. This constructor is a convenience constructor for those transports handling only a single ONC/RPC program and version number.
      Parameters:
        `dispatcher` - Reference to interface of an object capable of dispatching (handling) ONC/RPC calls.
        `bindAddr` - The local Internet Address the server will bind to.
        `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.
        `bufferSize` - Size of buffer for receiving and sending UDP/IP datagrams containing ONC/RPC call and reply messages.
      Throws:
        `OncRpcException`
        `java.io.IOException`

  - ### Method Detail

    - #### close

          public 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.

      Calling this method on a `OncRpcUdpServerTransport` results in the UDP network socket immediately being closed. The handler thread will therefore either terminate directly or when it tries to sent back a reply which it was about to handle at the time the close method was called.

      Specified by:
        `close` in class `OncRpcServerTransport`

    - #### register

          public void register()
                        throws OncRpcException

      Register the UDP/IP port where this server transport waits for incoming requests with the ONC/RPC portmapper.
      Specified by:
        `register` in class `OncRpcServerTransport`
      Throws:
        `OncRpcException` - if the portmapper could not be contacted successfully.

    - #### retrieveCall

          protected 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.
      Specified by:
        `retrieveCall` in class `OncRpcServerTransport`
      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 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.
      Specified by:
        `getXdrDecodingStream` in class `OncRpcServerTransport`
      Returns:
        Reference to decoding XDR stream.

    - #### endDecoding

          protected 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.
      Specified by:
        `endDecoding` in class `OncRpcServerTransport`
      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 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.
      Specified by:
        `getXdrEncodingStream` in class `OncRpcServerTransport`
      Returns:
        Reference to enecoding XDR stream.

    - #### beginEncoding

          protected 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.
      Specified by:
        `beginEncoding` in class `OncRpcServerTransport`
      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 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.
      Specified by:
        `endEncoding` in class `OncRpcServerTransport`
      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 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.
      Specified by:
        `reply` in class `OncRpcServerTransport`
      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`

    - #### listen

          public 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. Control in the calling thread immediately returns after the handler thread has been created.

      Currently only one call after the other is dispatched, so no multithreading is done when receiving multiple calls. Instead, later calls have to wait for the current call to finish before they are handled.

      Specified by:
        `listen` in class `OncRpcServerTransport`

    - #### _listen

          public void _listen()

      The real workhorse handling incoming requests, dispatching them and sending back replies.

    - #### setCharacterEncoding

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

      Set the character encoding for (de-)serializing strings.
      Specified by:
        `setCharacterEncoding` in class `OncRpcServerTransport`
      Parameters:
        `characterEncoding` - the encoding to use for (de-)serializing strings. If `null`, the system's default encoding is to be used.

    - #### getCharacterEncoding

          public java.lang.String getCharacterEncoding()

      Get the character encoding for (de-)serializing strings.
      Specified by:
        `getCharacterEncoding` in class `OncRpcServerTransport`
      Returns:
        the encoding currently used for (de-)serializing strings. If `null`, then the system's default encoding is used.