freenet.clients.fcp

Interface FCPPluginConnection

public interface FCPPluginConnection

An FCP connection between:
- a fred plugin which provides its services by a FCP server.
- a client application which uses those services. The client may be a plugin as well, or be connected by a networked FCP connection.

How to use this properly

You can read the following JavaDoc for a nice overview of how to use this properly from the perspective of your server or client implementation:
- PluginRespirator#connectToOtherPlugin(String, ClientSideFCPMessageHandler)
- PluginRespirator.getPluginConnectionByID(UUID)
- FredPluginFCPMessageHandler
- FredPluginFCPMessageHandler.ServerSideFCPMessageHandler
- FredPluginFCPMessageHandler.ClientSideFCPMessageHandler
- FCPPluginMessage

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 sendSynchronous(SendDirection, FCPPluginMessage, long) will not deliver replies to the message handler but only return them instead.

Connection lifecycle

Intra-node FCP - server and client both running within the same node as plugin

The client plugin dictates connection and disconnection. Connections are opened by it via PluginRespirator#connectToOtherPlugin(String, ClientSideFCPMessageHandler). It keeps them open by keeping a strong reference to the FCPPluginConnection. Once it does not strongly reference it anymore, Freenet detects that by monitoring garbage collection, and considers the connection as closed then. A closed connection is indicated to the server plugin by the send functions throwing IOException.

Networked FCP - server is running in the node as plugin, client connects by network

The client plugin again dictates connection and disconnection by opening and closing the FCP network connection as it pleases.
Additionally, a single network connection can only have a single FCPPluginConnection to each server plugin.
If you nevertheless need multiple connections to a plugin, you have to create multiple network connections to the FCP server.
(The reason for this is the following: Certain server plugins might need to store the UUID of a client connection in their database so they are able to send data to the client if an event of interest to the client happens in the future. Therefore, the UUID of a connection must not change during the lifetime of the connection. To ensure a permanent UUID of a connection, only a single FCPPluginConnection can exist per server plugin per network connection).

Persistence

In opposite to a FCP connection to fred itself, which is represented by PersistentRequestClient and can exist across restarts, a FCPPluginConnection is kept in existence by fred only while the actual client is connected. In case of networked plugin FCP, this is while the parent network connection is open; or in case of non-networked plugin FCP, while the FCPPluginConnection is strong-referenced by the client plugin.
There is no such thing as persistence beyond client disconnection / restarts.
This was decided to simplify implementation:
- Persistence should have been implemented by using the existing persistence framework of PersistentRequestClient. That would require extending the class though, and it is a complex class. The work for extending it was out of scope of the time limit for implementing this class.
- FCPPluginConnection instances need to be created without a network connection for intra-node plugin connections. If we extended class PersistentRequestClient, a lot of care would have to be taken to allow it to exist without a network connection - that would even be more work.

Internals

If you plan to work on the fred-side implementation of FCP plugin connections, please see the "Internals" section at the implementation FCPPluginConnectionImpl of this interface. Notably, the said section provides an overview of the flow of messages.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	FCPPluginConnection.SendDirection The send functions are fully symmetrical: They work the same way no matter whether client is sending to server or server is sending to client. Thus, to prevent us from having to duplicate the send functions, this enum specifies in which situation we are.

Method Summary

Modifier and Type	Method and Description
java.util.UUID	getID()
void	send(FCPPluginConnection.SendDirection direction, FCPPluginMessage message) Can be used by both server and client implementations to send messages to each other. The messages sent by this function will be delivered to the remote side at either: - the message handler handlePluginFCPMessage(FCPPluginConnection, FCPPluginMessage). - or, if existing, a thread waiting for a reply message in sendSynchronous(SendDirection, FCPPluginMessage, long). This is an asynchronous, non-blocking send function. This has the following differences to the blocking send sendSynchronous( SendDirection, FCPPluginMessage, long): - It may return before the message has been sent. The message sending happens in another thread so this function can return immediately. In opposite to that, a sendSynchronous() would wait for a reply to arrive, so once it returns, the message is guaranteed to have been sent. - The reply is delivered to your message handler FredPluginFCPMessageHandler.
void	send(FCPPluginMessage message) Same as send(SendDirection, FCPPluginMessage) with the FCPPluginConnection.SendDirection parameter being the default direction. Please do read its JavaDoc as it contains a very precise specification how to use it and thereby also this function. The default direction is determined automatically depending on whether you are a client or server. You are acting as a client, and thus by default send to the server, when you obtain a FCPPluginConnection...: - from the return value of PluginRespirator#connectToOtherPlugin(String, ClientSideFCPMessageHandler). - as parameter to your message handler callback handlePluginFCPMessage(FCPPluginConnection, FCPPluginMessage). You are acting as a server, and thus by default send to the client, when you obtain a FCPPluginConnection...: - as parameter to your message handler callback handlePluginFCPMessage(FCPPluginConnection, FCPPluginMessage). - from the return value of PluginRespirator.getPluginConnectionByID(UUID).
FCPPluginMessage	sendSynchronous(FCPPluginConnection.SendDirection direction, FCPPluginMessage message, long timeoutNanoSeconds) Can be used by both server and client implementations to send messages in a blocking manner to each other. The messages sent by this function will be delivered to the message handler FredPluginFCPMessageHandler.handlePluginFCPMessage(FCPPluginConnection, FCPPluginMessage) of the remote side. This has the following differences to a regular non-synchronous send(SendDirection, FCPPluginMessage): - It will wait for a reply message of the remote side before returning. A regular send() would instead queue the message for sending, and then return immediately.
FCPPluginMessage	sendSynchronous(FCPPluginMessage message, long timeoutNanoSeconds) Same as sendSynchronous(SendDirection, FCPPluginMessage, long) with the FCPPluginConnection.SendDirection parameter being the default direction. Please do read its JavaDoc as it contains a very precise specification how to use it and thereby also this function. For an explanation of how the default send direction is determined, see send(FCPPluginMessage).
java.lang.String	toString()

Method Detail

send

void send(FCPPluginConnection.SendDirection direction,
          FCPPluginMessage message)
   throws java.io.IOException

Can be used by both server and client implementations to send messages to each other.
The messages sent by this function will be delivered to the remote side at either: - the message handler handlePluginFCPMessage(FCPPluginConnection, FCPPluginMessage).
- or, if existing, a thread waiting for a reply message in sendSynchronous(SendDirection, FCPPluginMessage, long).

This is an asynchronous, non-blocking send function.
This has the following differences to the blocking send sendSynchronous( SendDirection, FCPPluginMessage, long):
- It may return before the message has been sent.
The message sending happens in another thread so this function can return immediately.
In opposite to that, a sendSynchronous() would wait for a reply to arrive, so once it returns, the message is guaranteed to have been sent.
- The reply is delivered to your message handler FredPluginFCPMessageHandler. It will not be directly available to the thread which called this function.
A sendSynchronous() would return the reply to the caller.
- You have no guarantee whatsoever that the message will be delivered.
A sendSynchronous() will tell you that a reply was received, which guarantees that the message was delivered.
- The order of arrival of messages is random.
A sendSynchronous() only returns after the message was delivered already, so by calling it multiple times in a row on the same thread, you would enforce the order of the messages arriving at the remote side.

ATTENTION: The consequences of this are:
- Even if the function returned without throwing an IOException you nevertheless must not assume that the message has been sent.
- If the function did throw an IOException, you must assume that the connection is dead and the message has not been sent.
You must consider this FCPPluginConnection as dead then and create a fresh one.
- You can only be sure that a message has been delivered if your message handler receives a reply message with the same value of FCPPluginMessage.identifier as the original message.
- You can send many messages in parallel by calling this many times in a row.
But you must not call this too often in a row to prevent excessive threads creation.

ATTENTION: If you plan to use this inside of message handling functions of your implementations of the interfaces FredPluginFCPMessageHandler.ServerSideFCPMessageHandler or FredPluginFCPMessageHandler.ClientSideFCPMessageHandler, be sure to read the JavaDoc of the message handling functions first as it puts additional constraints on the usage of the FCPPluginConnection they receive.

Parameters:

direction - Whether to send the message to the server or the client message handler.
You can use this to send messages to yourself.
You may use send(FCPPluginMessage) to avoid having to specify this.

message - You must not send the same message twice: This can break sendSynchronous( SendDirection, FCPPluginMessage, long).
To ensure this, always construct a fresh FCPPluginMessage object when re-sending a message. If you use the constructor which allows specifying your own identifier, always generate a fresh, random identifier.
TODO: Code quality: Add a flag to FCPPluginMessage which marks the message as sent and use it to log an error if someone tries to send the same message twice.

Throws:

java.io.IOException - If the connection has been closed meanwhile.
This FCPPluginConnection should be considered as dead once this happens, you should then discard it and obtain a fresh one.

ATTENTION: If this is not thrown, that does NOT mean that the connection is alive. Messages are sent asynchronously, so it can happen that a closed connection is not detected before this function returns.
The only way of knowing that a send succeeded is by receiving a reply message in your FredPluginFCPMessageHandler.
If you need to know whether the send succeeded on the same thread which shall call the send function, you can also use sendSynchronous(SendDirection, FCPPluginMessage, long) which will return the reply right away.

See Also:

You may instead use the blocking sendSynchronous() if your thread needs to know whether messages arrived, to ensure a certain order of arrival, or to know the reply to a message.

send

void send(FCPPluginMessage message)
   throws java.io.IOException

Same as send(SendDirection, FCPPluginMessage) with the FCPPluginConnection.SendDirection parameter being the default direction.
Please do read its JavaDoc as it contains a very precise specification how to use it and thereby also this function.

The default direction is determined automatically depending on whether you are a client or server.

You are acting as a client, and thus by default send to the server, when you obtain a FCPPluginConnection...:
- from the return value of PluginRespirator#connectToOtherPlugin(String, ClientSideFCPMessageHandler).
- as parameter to your message handler callback handlePluginFCPMessage(FCPPluginConnection, FCPPluginMessage).

You are acting as a server, and thus by default send to the client, when you obtain a FCPPluginConnection...:
- as parameter to your message handler callback handlePluginFCPMessage(FCPPluginConnection, FCPPluginMessage).
- from the return value of PluginRespirator.getPluginConnectionByID(UUID).

Throws:

java.io.IOException

sendSynchronous

FCPPluginMessage sendSynchronous(FCPPluginConnection.SendDirection direction,
                                 FCPPluginMessage message,
                                 long timeoutNanoSeconds)
                          throws java.io.IOException,
                                 java.lang.InterruptedException

Can be used by both server and client implementations to send messages in a blocking manner to each other.
The messages sent by this function will be delivered to the message handler FredPluginFCPMessageHandler.handlePluginFCPMessage(FCPPluginConnection, FCPPluginMessage) of the remote side.

This has the following differences to a regular non-synchronous send(SendDirection, FCPPluginMessage):
- It will wait for a reply message of the remote side before returning.
A regular send() would instead queue the message for sending, and then return immediately. - The reply message will be returned to the calling thread instead of being passed to the message handler FredPluginFCPMessageHandler.handlePluginFCPMessage( FCPPluginConnection, FCPPluginMessage) in another thread.
NOTICE: It is possible that the reply message is passed to the message handler upon certain error conditions, for example if the timeout you specify when calling this function expires before the reply arrives. This is not guaranteed though.
- Once this function returns without throwing, it is guaranteed that the message has arrived at the remote side.
- The order of messages can be preserved: If you call sendSynchronous() twice in a row, the second call cannot execute before the first one has returned, and the returning of the first call guarantees that the first message was delivered already.
Regular send() calls deploy each message in a thread. This means that the order of delivery can be different than the order of sending.

ATTENTION: This function can cause the current thread to block for a long time, while bypassing the thread limit. Therefore, only use this if the desired operation at the remote side is expected to execute quickly and the thread which sends the message immediately needs one of these after sending it to continue its computations:
- An guarantee that the message arrived at the remote side.
- An indication of whether the operation requested by the message succeeded.
- The reply to the message.
- A guaranteed order of arrival of messages at the remote side.
A typical example for a place where this is needed is a user interface which has a user click a button and want to see the result of the operation as soon as possible. A detailed example is given at the documentation of the return value below.
Notice that even this could be done asynchronously with certain UI frameworks: An event handler could wait asynchronously for the result and fill it in the UI. However, for things such as web interfaces, you might need JavaScript then, so a synchronous call will simplify the code.
In addition to only using synchronous calls when absolutely necessary, please make sure to set a timeout parameter which is as small as possible.

ATTENTION: While remembering that this function can block for a long time, you have to consider that this class will not call Thread.interrupt() upon pending calls to this function during shutdown. You must keep track of threads which are executing this function on your own, and call Thread.interrupt() upon them at shutdown of your plugin. The interruption will then cause the function to throw InterruptedException quickly, which your calling threads should obey by exiting to ensure a fast shutdown.

ATTENTION: This function can only work properly as long the message which you passed to this function does contain a message identifier which does not collide with one of another message.
To ensure this, you must use the constructor FCPPluginMessage.construct( SimpleFieldSet, Bucket) (or one of its shortcuts) and do not call this function twice upon the same message.
If you do not follow this rule and use colliding message identifiers, there might be side effects such as:
- This function might return the reply to the colliding message instead of the reply to your message. Notice that this implicitly means that you cannot be sure anymore that a message was delivered successfully if this function does not throw.
- The reply might be passed to the FredPluginFCPMessageHandler instead of being returned from this function.
Please notice that both these side effects can also happen if the remote partner erroneously sends multiple replies to the same message identifier.
As long as the remote side is implemented using FCPPluginConnection as well, and uses it properly, this shouldn't happen though. Thus in general, you should assume that the reply which this function returns is the right one, and your FredPluginFCPMessageHandler should just drop reply messages which were not expected and log them as at Logger.LogLevel.WARNING. The information here was merely provided to help you with debugging the cause of these events, not to make you change your code to assume that sendSynchronous does not work. For clean code, please write it in a way which assumes that the function works properly.

ATTENTION: If you plan to use this inside of message handling functions of your implementations of the interfaces FredPluginFCPMessageHandler.ServerSideFCPMessageHandler or FredPluginFCPMessageHandler.ClientSideFCPMessageHandler, be sure to read the JavaDoc of the message handling functions first as it puts additional constraints on the usage of the FCPPluginConnection they receive.

Parameters:

direction - Whether to send the message to the server or the client message handler.
You can use this to send messages to yourself.
You may use sendSynchronous(FCPPluginMessage, long) to avoid having to specify this.

message - Must be constructed using FCPPluginMessage.construct(SimpleFieldSet, Bucket) or one of its shortcuts.

Must not be a reply message: This function needs determine when the remote side has finished processing the message so it knows when to return. That requires the remote side to send a reply to indicate that the FCP call is finished. Replies to replies are not allowed though (to prevent infinite bouncing).

timeoutNanoSeconds - The function will wait for a reply to arrive for this amount of time.
Must be greater than 0 and below or equal to 1 minute.

If the timeout expires, an IOException is thrown.
This FCPPluginConnection should be considered as dead once this happens, you should then discard it and obtain a fresh one.

ATTENTION: The sending of the message is not affected by this timeout, it only affects how long we wait for a reply. The sending is done in another thread, so if your message is very large, and takes longer to transfer than the timeout grants, this function will throw before the message has been sent.
Additionally, the sending of the message is not terminated if the timeout expires before it was fully transferred. Thus, the message can arrive at the remote side even if this function has thrown, and you might receive an off-thread reply to the message in the FredPluginFCPMessageHandler.

Notice: For convenience, use class TimeUnit to easily convert seconds, milliseconds, etc. to nanoseconds.

Returns:

The reply FCPPluginMessage which the remote partner sent to your message.

ATTENTION: Even if this function did not throw, the reply might indicate an error with the field {link FCPPluginMessage#success}: This can happen if the message was delivered but the remote message handler indicated that the FCP operation you initiated failed.
The fields FCPPluginMessage.errorCode and FCPPluginMessage.errorMessage might indicate the type of the error.

This can be used to decide to retry certain operations. A practical example would be a user trying to create an account at an FCP server application:
- Your UI would use this function to try to create the account by FCP.
- The user might type an invalid character in the username.
- The server could then indicate failure of creating the account by sending a reply with success == false.
- Your UI could detect the problem by success == false at the reply and an errorCode of "InvalidUsername". The errorCode can be used to decide to highlight the username field with a red color.
- The UI then could prompt the user to chose a valid username by displaying the errorMessage which the server provides to ship a translated, human readable explanation of what is wrong with the username.

Throws:

java.io.IOException - If the given timeout expired before a reply was received or if the connection has been closed before even sending the message.
This FCPPluginConnection should be considered as dead once this happens, you should then discard it and obtain a fresh one.

java.lang.InterruptedException - If another thread called Thread.interrupt() upon the thread which you used to execute this function.
This is a shutdown mechanism: You can use it to abort a call to this function which is waiting for the timeout to expire.

See Also:

An overview of how synchronous sends and especially their threading work internally is provided at the map which stores them., The non-blocking, asynchronous send() should be used instead of this whenever possible.

sendSynchronous

FCPPluginMessage sendSynchronous(FCPPluginMessage message,
                                 long timeoutNanoSeconds)
                          throws java.io.IOException,
                                 java.lang.InterruptedException

Same as sendSynchronous(SendDirection, FCPPluginMessage, long) with the FCPPluginConnection.SendDirection parameter being the default direction.
Please do read its JavaDoc as it contains a very precise specification how to use it and thereby also this function.

For an explanation of how the default send direction is determined, see send(FCPPluginMessage).

Throws:

java.io.IOException

java.lang.InterruptedException

getID

java.util.UUID getID()

Returns:

A unique identifier among all FCPPluginConnections.

See Also:

ID can be used with {@link PluginRespirator#getPluginConnectionByID(UUID)}.

toString

java.lang.String toString()

Overrides:

toString in class java.lang.Object

Returns:

A verbose String containing the internal state. Useful for debug logs.