freenet.pluginmanager

Interface FredPluginFCPMessageHandler.ServerSideFCPMessageHandler

All Superinterfaces:

FredPluginFCPMessageHandler

Enclosing interface:

FredPluginFCPMessageHandler

public static interface FredPluginFCPMessageHandler.ServerSideFCPMessageHandler
extends FredPluginFCPMessageHandler

Plugins which provide FCP services to clients must implement this interface.
The purpose of this interface is to provide a message handling function for processing messages received from the clients.

See Also:

The parent interface FredPluginFCPMessageHandler provides an overview., The opposite version of this interface for client plugins

Nested Class Summary

Nested classes/interfaces inherited from interface freenet.pluginmanager.FredPluginFCPMessageHandler

FredPluginFCPMessageHandler.ClientSideFCPMessageHandler, FredPluginFCPMessageHandler.PrioritizedMessageHandler, FredPluginFCPMessageHandler.ServerSideFCPMessageHandler

Method Summary

Modifier and Type	Method and Description
FCPPluginMessage	handlePluginFCPMessage(FCPPluginConnection connection, FCPPluginMessage message) Is called to handle messages from your clients. Must not block for very long and thus must only do small amounts of processing.

Method Detail

handlePluginFCPMessage

FCPPluginMessage handlePluginFCPMessage(FCPPluginConnection connection,
                                        FCPPluginMessage message)

Is called to handle messages from your clients.
Must not block for very long and thus must only do small amounts of processing.

If you ...
- Need a long time to compute a reply.
- Need to keep a reference to the client connection because you want to send messages to the client after having exited this function; maybe even triggered by events at your plugin, not by client messages.
Then you should:
- Store the passed FCPPluginConnection. If you cannot store objects in memory, for example because you are using a database, you can get the UUID of the connection via FCPPluginConnection.getID(), store only that, and then in the future get back the connection using PluginRespirator.getPluginConnectionByID(UUID).
- Compute your reply in another thread.
- Once you're ready to send the reply, send the message using the send functions of the FCPPluginConnection.
- Notice that there is no explicit disconnection mechanism. Clients can come and go as they please. The only way to be sure that a connection is alive is by checking whether the client replies to messages.
Thus, if you store client connections for longer than sending a single reply, make sure to prevent excessive growth of your connection database upon client disconnection by implementing a garbage collection mechanism as follows:
Periodically send a message at each connection and check if you get a reply within a reasonable timeout to check whether the connection is still alive. Drop the connection if not. You may make a "Ping" message with a "Pong" response a requirement for your server's protocol.

Specified by:

handlePluginFCPMessage in interface FredPluginFCPMessageHandler

Parameters:

connection - The connection of the client which sent the message.

You must not use its send functions for sending back the main reply. Instead, use the return value for shipping the reply. (You are free to send "out of band" secondary replies using the connection.)
The requirement of returning the reply is to ensure that the reply can be clearly identified as such, and shipped to the remote side with a clear specification to which message it is a reply.
This is useful for example if the sender of the original message used the synchronous send function FCPPluginConnection.sendSynchronous( SendDirection, FCPPluginMessage, long): The function shall wait for the reply to the original message, and return it to the caller. This only works if replies are properly identified, otherwise it would have to throw an IOException to signal a timeout while waiting for the reply.

message - The actual message. See the JavaDoc of its member variables for an explanation of their meaning.

Returns:

Your reply message, or null if you don't want to reply.

You must construct this by using the constructor constructReplyMessage(FCPPluginMessage, SimpleFieldSet, Bucket, boolean, String, String) (or one of its shortcuts) to ensure that the FCPPluginMessage.identifier gets preserved.

Replies to replies are not allowed: You must return null if the original message was a reply message already as indicated by FCPPluginMessage.isReplyMessage().
Replies often shall only indicate success / failure instead of triggering actual operations, so it could cause infinite bouncing if you reply to them again.
If you still have to send a message to do further operations, you should create a new "dialog" by sending an "out of band" message using the passed FCPPluginConnection, as explained in the description of this function.
Consider the whole of this as a remote procedure call process: A non-reply message is the procedure call, a reply message is the procedure result. When receiving the result, the procedure call is finished, and shouldn't contain further replies.

You should always return a reply instead of null if you're allowed to, even if you have got nothing to say:
This allows the remote side to detect whether its requested operation succeeded or failed because reply messages always have to specify success/failure.
Notice: Even upon failure, a reply is better than saying nothing because it allows FCPPluginConnection.sendSynchronous(SendDirection, FCPPluginMessage, long) to fail fast instead of having to wait for timeout.