Class OncRpcServerTransport
- Direct Known Subclasses:
OncRpcTcpConnectionServerTransport
,OncRpcTcpServerTransport
,OncRpcUdpServerTransport
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:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected OncRpcDispatchable
Reference to interface of an object capable of handling/dispatching ONC/RPC requests.protected OncRpcServerTransportRegistrationInfo[]
Program and version number tuples handled by this server transport.protected int
Port number where we're listening for incoming ONC/RPC requests. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
OncRpcServerTransport
(OncRpcDispatchable dispatcher, int port, OncRpcServerTransportRegistrationInfo[] info) Create a new instance of aOncRpcServerTransport
which encapsulates XDR streams of an ONC/RPC server. -
Method Summary
Modifier and TypeMethodDescriptionprotected 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
Finishes call parameter deserialization.protected abstract void
Finishes encoding the reply to this ONC/RPC call.abstract String
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
Returns XDR stream which can be used for deserializing the parameters of this ONC/RPC call.protected abstract XdrEncodingStream
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
(String characterEncoding) Set the character encoding for (de-)serializing strings.void
Unregisters the port where this server transport waits for incoming requests from the ONC/RPC portmapper.
-
Field Details
-
dispatcher
Reference to interface of an object capable of handling/dispatching ONC/RPC requests. -
port
protected int portPort number where we're listening for incoming ONC/RPC requests. -
info
Program and version number tuples handled by this server transport.
-
-
Constructor Details
-
OncRpcServerTransport
protected OncRpcServerTransport(OncRpcDispatchable dispatcher, int port, OncRpcServerTransportRegistrationInfo[] info) Create a new instance of aOncRpcServerTransport
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 Details
-
register
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
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 ofOncRpcException.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
Set the character encoding for (de-)serializing strings.- Parameters:
characterEncoding
- the encoding to use for (de-)serializing strings. Ifnull
, the system's default encoding is to be used.
-
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
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 callsXdrDecodingStream.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.IOException
- if an I/O exception occurs, like transmission failures over the network, etc.
-
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
Finishes call parameter deserialization. Afterwards the XDR stream returned bygetXdrDecodingStream()
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.IOException
- if an I/O exception occurs, like transmission failures over the network, etc.
-
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, 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.IOException
- if an I/O exception occurs, like transmission
-
endEncoding
Finishes encoding the reply to this ONC/RPC call. Afterwards you must not use the XDR stream returned bygetXdrEncodingStream()
any longer.- Throws:
OncRpcException
- if an ONC/RPC exception occurs, like the data could not be successfully serialized.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, 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 theOncRpcCallInformation.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 notnull
, 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.IOException
- if an I/O exception occurs, like transmission failures over the network, etc.- See Also:
-