freenet.pluginmanager

Interface FredPluginFCPMessageHandler.ClientSideFCPMessageHandler

All Superinterfaces:

FredPluginFCPMessageHandler

Enclosing interface:

FredPluginFCPMessageHandler

public static interface FredPluginFCPMessageHandler.ClientSideFCPMessageHandler
extends FredPluginFCPMessageHandler

Client plugins which connect to a FCP server plugin must implement this interface.
The purpose of this interface is to provide a message handling function for processing messages received from the server.

See Also:

The parent interface FredPluginFCPMessageHandler provides an overview., The opposite version of this interface for server 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 the server after you sent a message to it using a FCPPluginConnection. ATTENTION: The server is free to send messages to you on its own, that is not triggered by any message which you sent. This can happen for as long as you keep the connection open by having a hard reference to the original FCPPluginConnection in memory. The purpose of this mechanism is for example to allow the server to tell you about events which happened at its side.

Method Detail

handlePluginFCPMessage

FCPPluginMessage handlePluginFCPMessage(FCPPluginConnection connection,
                                        FCPPluginMessage message)

Is called to handle messages from the server after you sent a message to it using a FCPPluginConnection.

ATTENTION: The server is free to send messages to you on its own, that is not triggered by any message which you sent.
This can happen for as long as you keep the connection open by having a hard reference to the original FCPPluginConnection in memory.
The purpose of this mechanism is for example to allow the server to tell you about events which happened at its side.

Specified by:

handlePluginFCPMessage in interface FredPluginFCPMessageHandler

Parameters:

connection - The connection which you had originally established to the server.

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.