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

See Also:

OncRpcCallInformation, OncRpcDispatchable

Field Summary

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

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

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