freenet.pluginmanager

Interface FredPluginFCPMessageHandler

All Known Subinterfaces:

FredPluginFCPMessageHandler.ClientSideFCPMessageHandler, FredPluginFCPMessageHandler.ServerSideFCPMessageHandler

public interface FredPluginFCPMessageHandler

NOTICE: This API is a rewrite of the whole code for plugin communication. It was added 2015-03, and for some time after that may change in ways which break backward compatibility. Thus any suggestions or pull requests for improvement of all involved interfaces and classes are welcome!
If you would not like to deal with adapting your plugins to possible changes, use the legacy FredPluginFCP API meanwhile.

FCP server or client plugins which transfer FCP messages to each other using a FCPPluginConnection must implement this interface by implementing one of it's child interfaces, to provide a function which handles the received messages.

For symmetry, the child interfaces FredPluginFCPMessageHandler.ClientSideFCPMessageHandler and FredPluginFCPMessageHandler.ServerSideFCPMessageHandler do not provide any different functions.
They exist nevertheless to allow JavaDoc to explain differences in what the server and client are allowed to do.
You must follow the restrictions which are explained there.
For clarity, you must implement the child interfaces instead of this interface.

If you want to specify the thread priority of the message handling functions, you can additionally implement the member interface FredPluginFCPMessageHandler.PrioritizedMessageHandler.

As opposed to the old FredPluginFCP and FredPluginTalker message handler interfaces, and their PluginReplySender and PluginTalker message sending counterparts, this new API is as symmetric as possible:
Both the message handler and message sender is now one interface / class shared by both server and client, instead of different ones for each - FredPluginFCPMessageHandler and FCPPluginConnection.
With the old interface, the server could only reply to messages of the client, it could not send a message without a previous client message.
With this implementation, server and client are free to send messages to each others whenever they like to.
The only restriction upon this is that the opening and closing of connections is dictated by the client. The server cannot connect to a client on its own.

Implementing a server

All you have to do to allow clients to connect to your plugin by FCP is implement the child interface FredPluginFCPMessageHandler.ServerSideFCPMessageHandler at your plugin's main class.
Freenet will then automatically detect that the main class implements it, and allow clients to connect by FCP.

Implementing a client

Use PluginRespirator.connectToOtherPlugin(String, FredPluginFCPMessageHandler.ClientSideFCPMessageHandler) to connect to a FCP server plugin.

Debugging

You can configure the Logger to log "freenet.clients.fcp.FCPPluginConnection:DEBUG" to cause logging of all sent and received messages.
This is usually done on the Freenet web interface at Configuration / Logs / Detailed priority thresholds.
ATTENTION: The log entries will appear at the time when the messages were queued for sending, not when they were delivered. Delivery usually happens in a separate thread. Thus, the relative order of arrival of messages can be different to the order of their appearance in the log file.
If you need to know the order of arrival, add logging to your message handler. Also don't forget that FCPPluginConnection.sendSynchronous(SendDirection, FCPPluginMessage, long) will not deliver replies to the message handler but only return them instead.

See Also:

A connection will be represented as class FCPPluginConnection to the client and server plugin. It's JavaDoc provides an overview of the lifecycle of connections.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	FredPluginFCPMessageHandler.ClientSideFCPMessageHandler 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.
static interface	FredPluginFCPMessageHandler.PrioritizedMessageHandler Implement this to specify a thread priority of threads which are used to execute the message handling function handlePluginFCPMessage(FCPPluginConnection, FCPPluginMessage). Notice that the priority could even be specified depending on the type of individual messages as the individual messages are passed to the implementation of this handler.
static interface	FredPluginFCPMessageHandler.ServerSideFCPMessageHandler 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.

Method Summary

Modifier and Type

Method and Description

FCPPluginMessage

handlePluginFCPMessage(FCPPluginConnection connection, FCPPluginMessage message) Message handling function for messages received from a plugin FCP server or client. ATTENTION: Please read the different constraints for server and client side message handlers at the child interfaces: - FredPluginFCPMessageHandler.ServerSideFCPMessageHandler.handlePluginFCPMessage(FCPPluginConnection, FCPPluginMessage) - FredPluginFCPMessageHandler.ClientSideFCPMessageHandler.handlePluginFCPMessage(FCPPluginConnection, FCPPluginMessage) To stress those different constraints, you should also not implement this interface but one of the child interfaces FredPluginFCPMessageHandler.ServerSideFCPMessageHandler and FredPluginFCPMessageHandler.ClientSideFCPMessageHandler.

Method Detail

handlePluginFCPMessage

FCPPluginMessage handlePluginFCPMessage(FCPPluginConnection connection,
                                        FCPPluginMessage message)

Message handling function for messages received from a plugin FCP server or client.

ATTENTION: Please read the different constraints for server and client side message handlers at the child interfaces:
- FredPluginFCPMessageHandler.ServerSideFCPMessageHandler.handlePluginFCPMessage(FCPPluginConnection, FCPPluginMessage)
- FredPluginFCPMessageHandler.ClientSideFCPMessageHandler.handlePluginFCPMessage(FCPPluginConnection, FCPPluginMessage)
To stress those different constraints, you should also not implement this interface but one of the child interfaces FredPluginFCPMessageHandler.ServerSideFCPMessageHandler and FredPluginFCPMessageHandler.ClientSideFCPMessageHandler.