freenet.clients.fcp

Class FCPPluginMessage

java.lang.Object

freenet.clients.fcp.FCPPluginMessage

public final class FCPPluginMessage
extends java.lang.Object

Container class for both incoming and outgoing FCP messages.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	FCPPluginMessage.ClientPermissions

Field Summary

Fields

Modifier and Type	Field and Description
Bucket	data Part 2 of the actual message: Non-human readable, large size bulk data. Can be null if no large amount of data is to be transfered.
java.lang.String	errorCode For reply messages with success == false, may contain an alpha-numeric String which identifies a reason for the failure in a standardized representation which software can parse easily.
java.lang.String	errorMessage For reply messages with errorCode != null, may contain a String which describes the problem in a human-readable, user-friendly manner.
java.lang.String	identifier The unique identifier of the message. Can be used by server and client to track the progress of messages. This especially applies to FCPPluginConnection.sendSynchronous(SendDirection, FCPPluginMessage, long) which will wait for a reply with the same identifier as the original message until it returns. For reply messages, this shall be the same as the identifier of the message to which this is a reply. For non-reply message, this shall be a sufficiently random String to prevent collisions with any previous message identifiers.
SimpleFieldSet	params Part 1 of the actual message: Human-readable parameters.
FCPPluginMessage.ClientPermissions	permissions The permissions of the client which sent the messages.
java.lang.Boolean	success For messages which are a reply to another message, this is always non-null.

Method Summary

Modifier and Type	Method and Description
static FCPPluginMessage	construct() Same as construct(SimpleFieldSet, Bucket) with the missing parameters being: SimpleFieldSet params = new SimpleFieldSet(shortLived = true); Bucket data = null; ATTENTION: Messages constructed with this constructor here are not reply messages. If you are replying to a message, notably when returning a message in the message handler interface implementation, you must use constructReplyMessage(FCPPluginMessage, SimpleFieldSet, Bucket, boolean, String, String) (or one of its shortcuts) instead.
static FCPPluginMessage	construct(SimpleFieldSet params, Bucket data) For being used by server or client to construct outgoing messages. Those can then be passed to the send functions of FCPPluginConnection or returned in the message handlers of FredPluginFCPMessageHandler. ATTENTION: Messages constructed with this constructor here are not reply messages. If you are replying to a message, notably when returning a message in the message handler interface implementation, you must use constructReplyMessage(FCPPluginMessage, SimpleFieldSet, Bucket, boolean, String, String) (or one of its shortcuts) instead. See the JavaDoc of the member variables with the same name as the parameters for an explanation of the parameters. There is a shortcut to this constructor for typical choice of parameters: construct().
static FCPPluginMessage	constructErrorReply(FCPPluginMessage originalMessage, java.lang.String errorCode, java.lang.String errorMessage) Same as constructReplyMessage(FCPPluginMessage, SimpleFieldSet, Bucket, boolean, String, String) with the missing parameters being: SimpleFieldSet params = new SimpleFieldSet(shortLived = true); Bucket data = null; boolean success = false;
static FCPPluginMessage	constructReplyMessage(FCPPluginMessage originalMessage, SimpleFieldSet params, Bucket data, boolean success, java.lang.String errorCode, java.lang.String errorMessage) For being used by server or client to construct outgoing messages which are a reply to an original message. Those then can be returned from the message handler FredPluginFCPMessageHandler.handlePluginFCPMessage(FCPPluginConnection, FCPPluginMessage). See the JavaDoc of the member variables with the same name as the parameters for an explanation of the parameters. There are shortcuts to this constructor for typical choice of parameters: constructSuccessReply(FCPPluginMessage). constructErrorReply(FCPPluginMessage, String, String).
static FCPPluginMessage	constructSuccessReply(FCPPluginMessage originalMessage) Same as constructReplyMessage(FCPPluginMessage, SimpleFieldSet, Bucket, boolean, String, String) with the missing parameters being: SimpleFieldSet params = new SimpleFieldSet(shortLived = true); Bucket data = null; boolean success = true; errorCode = null; errorMessage = null;
boolean	isReplyMessage()
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

permissions

public final FCPPluginMessage.ClientPermissions permissions

The permissions of the client which sent the messages. Null for server-to-client and outgoing messages.
Will be set by the FCPPluginConnection before delivery of the message. Thus, you can pass null for this in all constructors.

identifier

public final java.lang.String identifier

The unique identifier of the message.
Can be used by server and client to track the progress of messages.
This especially applies to FCPPluginConnection.sendSynchronous(SendDirection, FCPPluginMessage, long) which will wait for a reply with the same identifier as the original message until it returns.

For reply messages, this shall be the same as the identifier of the message to which this is a reply.
For non-reply message, this shall be a sufficiently random String to prevent collisions with any previous message identifiers. The default is a random UUID, and alternate implementations are recommended to use a random UUID as well.

Notice: Custom client implementations can chose the identifier freely when sending messages, and thus violate these rules. This is highly discouraged though, as non-unique identifiers make tracking messages impossible. But if a client does violate the rules and thereby breaks its message tracking, thats not the server's problem, and thus should not cause complexification of the server code.
So server implementations should assume that the client chooses the identifier in a sane manner which follows the rules.
This class does follow the rules, and thus client and server implementations using it will do so as well.

params

public final SimpleFieldSet params

Part 1 of the actual message: Human-readable parameters. Shall be small amount of data.
Can be null for data-only or success-indicator messages.

data

public final Bucket data

Part 2 of the actual message: Non-human readable, large size bulk data.
Can be null if no large amount of data is to be transfered.

success

public final java.lang.Boolean success

For messages which are a reply to another message, this is always non-null. It then is true if the operation to which this is a reply succeeded, false if it failed.
For non-reply messages, this is always null.

Notice: Whether this is null or non-null is used to determine the return value of isReplyMessage() - a reply message has success != null, a non-reply message has success == null.

errorCode

public final java.lang.String errorCode

For reply messages with success == false, may contain an alpha-numeric String which identifies a reason for the failure in a standardized representation which software can parse easily. May also be null in that case, but please try to not do that.
For success == null or true, this must be null.

The String shall be for programming purposes and thus must be alpha-numeric.
For unclassified errors, such as Exceptions which you do not expect, use "InternalError".

errorMessage

public final java.lang.String errorMessage

For reply messages with errorCode != null, may contain a String which describes the problem in a human-readable, user-friendly manner. May also be null in that case, but please try to not do that.
For errorCode == null, this must be null.

You are encouraged to provide it translated to the configured language already.
The String shall not be used for identifying problems in programming.
There, use errorCode. For Exceptions which you do not expect, Throwable.toString() will return a sufficient errorMessage (containing the name of the Exception and the localized error message, or non-localized if there is no translation).

(Notice: This may only be non-null if errorCode is non-null instead of just if success == false to ensure that a developer-friendly error signaling is implemented: errorCode is designed to be easy to parse, errorMessage is designed to be human readable and thus cannot be parsed. Therefore, the errorCode field should be more mandatory than this field.)

Method Detail

isReplyMessage

public boolean isReplyMessage()

Returns:

True if the message is merely a reply to a previous message from your side.
In that case, you must not send another reply message back to prevent infinite bouncing of "success!" replies.

construct

public static FCPPluginMessage construct(SimpleFieldSet params,
                                         Bucket data)

For being used by server or client to construct outgoing messages.
Those can then be passed to the send functions of FCPPluginConnection or returned in the message handlers of FredPluginFCPMessageHandler.

ATTENTION: Messages constructed with this constructor here are not reply messages.
If you are replying to a message, notably when returning a message in the message handler interface implementation, you must use constructReplyMessage(FCPPluginMessage, SimpleFieldSet, Bucket, boolean, String, String) (or one of its shortcuts) instead.

See the JavaDoc of the member variables with the same name as the parameters for an explanation of the parameters.

There is a shortcut to this constructor for typical choice of parameters:
construct().

construct

public static FCPPluginMessage construct()

Same as construct(SimpleFieldSet, Bucket) with the missing parameters being:
SimpleFieldSet params = new SimpleFieldSet(shortLived = true);
Bucket data = null;

ATTENTION: Messages constructed with this constructor here are not reply messages.
If you are replying to a message, notably when returning a message in the message handler interface implementation, you must use constructReplyMessage(FCPPluginMessage, SimpleFieldSet, Bucket, boolean, String, String) (or one of its shortcuts) instead.

constructReplyMessage

public static FCPPluginMessage constructReplyMessage(FCPPluginMessage originalMessage,
                                                     SimpleFieldSet params,
                                                     Bucket data,
                                                     boolean success,
                                                     java.lang.String errorCode,
                                                     java.lang.String errorMessage)

For being used by server or client to construct outgoing messages which are a reply to an original message.
Those then can be returned from the message handler FredPluginFCPMessageHandler.handlePluginFCPMessage(FCPPluginConnection, FCPPluginMessage).

See the JavaDoc of the member variables with the same name as the parameters for an explanation of the parameters.

There are shortcuts to this constructor for typical choice of parameters:
constructSuccessReply(FCPPluginMessage).
constructErrorReply(FCPPluginMessage, String, String).

Throws:

java.lang.IllegalStateException - If the original message was a reply message already.
Replies often shall only indicate success / failure instead of triggering actual operations, so it could cause infinite bouncing if you reply to them again.
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 thus shouldn't cause further replies to be sent.
Notice: The JavaDoc of the aforementioned message handling function explains how you can nevertheless send a reply to reply messages.

constructSuccessReply

public static FCPPluginMessage constructSuccessReply(FCPPluginMessage originalMessage)

Same as constructReplyMessage(FCPPluginMessage, SimpleFieldSet, Bucket, boolean, String, String) with the missing parameters being:
SimpleFieldSet params = new SimpleFieldSet(shortLived = true);
Bucket data = null;
boolean success = true;
errorCode = null;
errorMessage = null;


constructErrorReply

public static FCPPluginMessage constructErrorReply(FCPPluginMessage originalMessage,
                                                   java.lang.String errorCode,
                                                   java.lang.String errorMessage)

Same as constructReplyMessage(FCPPluginMessage, SimpleFieldSet, Bucket, boolean, String, String) with the missing parameters being:
SimpleFieldSet params = new SimpleFieldSet(shortLived = true);
Bucket data = null;
boolean success = false;


toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object