Class 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 
      Modifier and Type Field Description
      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.
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      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.
    • 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