freenet.pluginmanager

Class PluginRespirator

java.lang.Object

freenet.pluginmanager.PluginRespirator

public class PluginRespirator
extends java.lang.Object

Constructor Summary

Constructors

Constructor and Description
PluginRespirator(Node node, PluginInfoWrapper pi)

Method Summary

Modifier and Type	Method and Description
HTMLNode	addFormChild(HTMLNode parentNode, java.lang.String target, java.lang.String name) Add a valid form including the NodeClientCore.formPassword.
FCPPluginConnection	connectToOtherPlugin(java.lang.String pluginName, FredPluginFCPMessageHandler.ClientSideFCPMessageHandler messageHandler) NOTICE: This API is a rewrite of the whole code for plugin communication.
HighLevelSimpleClient	getHLSimpleClient()
Node	getNode() Get the node.
PageMaker	getPageMaker() Get the PageMaker.
FCPPluginConnection	getPluginConnectionByID(java.util.UUID connectionID) Allows FCP server plugins, that is plugins which implement FredPluginFCPMessageHandler.ServerSideFCPMessageHandler, to obtain an existing client FCPPluginConnection by its UUID - if the client is still connected. May be used by servers which cannot store objects in memory, for example because they are using a database: An UUID can be serialized to disk, serialization would not be possible for a FCPPluginConnection. Servers are however free to instead keep the FCPPluginConnection in memory, usage of this function is not mandatory. Must not be used by client plugins: They shall instead keep a hard reference to the FCPPluginConnection in memory after they have received it from connectToOtherPlugin(String, FredPluginFCPMessageHandler.ClientSideFCPMessageHandler).
PluginTalker	getPluginTalker(FredPluginTalker fpt, java.lang.String pluginname, java.lang.String identifier) Deprecated. Use connectToOtherPlugin(String, FredPluginFCPMessageHandler.ClientSideFCPMessageHandler) instead.
SessionManager	getSessionManager(java.lang.String cookieNamespace) Get a new session manager for use with the global "/" cookie path and the given cookie namespace.
SessionManager	getSessionManager(java.net.URI cookiePath) Deprecated.
PluginStore	getStore() Get a PluginStore that can be used by the plugin to put data in a database.
SubConfig	getSubConfig() Get the plugin's SubConfig.
ToadletContainer	getToadletContainer() Get the ToadletContainer, which manages HTTP.
FilterCallback	makeFilterCallback(java.lang.String path) Create a GenericReadFilterCallback, which will filter URLs in exactly the same way as the node does when filtering a page.
void	putStore(PluginStore store) This should be called by the plugin to store its PluginStore in the node's database.
void	storeConfig() Force a write of the plugin's config file.

Methods inherited from class java.lang.Object

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

Constructor Detail

PluginRespirator

public PluginRespirator(Node node,
                        PluginInfoWrapper pi)

Method Detail

getHLSimpleClient

public HighLevelSimpleClient getHLSimpleClient()

getNode

public Node getNode()

Get the node. Use this if you need access to low-level stuff, node config etc.

makeFilterCallback

public FilterCallback makeFilterCallback(java.lang.String path)

Create a GenericReadFilterCallback, which will filter URLs in exactly the same way as the node does when filtering a page.

Parameters:

path - The base URI for the page being filtered. Not necessarily a FreenetURI.

getPageMaker

public PageMaker getPageMaker()

Get the PageMaker.

addFormChild

public HTMLNode addFormChild(HTMLNode parentNode,
                             java.lang.String target,
                             java.lang.String name)

Add a valid form including the NodeClientCore.formPassword. See the JavaDoc there for an explanation of the purpose of this mechanism.

ATTENTION: It is critically important to validate the form password when processing requests which "change the server state". Other words for this would be requests which change your database or "write" requests. Requests which only read values from the server don't have to validate the form password.

To validate that the right password was received, use WebInterfaceToadlet.isFormPassword(HTTPRequest).

Parameters:

parentNode - The parent HTMLNode.

target - Where to post to.

name - The id/name of the form.

Returns:

The form's HTMLNode.

getPluginTalker

@Deprecated
public PluginTalker getPluginTalker(FredPluginTalker fpt,
                                                java.lang.String pluginname,
                                                java.lang.String identifier)
                                         throws PluginNotFoundException

Deprecated. Use connectToOtherPlugin(String, FredPluginFCPMessageHandler.ClientSideFCPMessageHandler) instead.

Get a PluginTalker so you can talk with other plugins.

Throws:

PluginNotFoundException

connectToOtherPlugin

public FCPPluginConnection connectToOtherPlugin(java.lang.String pluginName,
                                                FredPluginFCPMessageHandler.ClientSideFCPMessageHandler messageHandler)
                                         throws PluginNotFoundException

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 getPluginTalker(FredPluginTalker, String, String) API meanwhile.

Creates a FCP client connection with another plugin which is a FCP server (= which implements interface FredPluginFCPMessageHandler.ServerSideFCPMessageHandler).
Currently, the remote plugin must run in the same node, but the fact that FCP is used lays foundation for a future implementation to allow you to connect to other plugins by network, no matter where they are running.

Disconnecting properly

The formally correct mechanism of disconnecting the returned FCPPluginConnection is to null out the strong reference to it. The node internally keeps a ReferenceQueue which allows it to detect the strong reference being nulled, which in turn makes the node clean up its internal structures.
Thus, you are encouraged to keep the returned FCPPluginConnection in memory and use it for as long as you need it. Notice that keeping it in memory won't block unloading of the server plugin. If the server plugin is unloaded, the send-functions will fail. To get reconnected once the server plugin is loaded again, you must obtain a fresh client connection from this function: Once an existing client connection is indicated as closed by a single call to a send function throwing IOException, it must be considered as dead for ever, reconnecting is not possible.
While this does seem like you do not have to take care about disconnection at all, you must make sure to not keep an excessive amount of FCPPluginConnection objects strongly referenced to ensure that this mechanism works. Especially notice that a FCPPluginConnection is safe and intended to be used for multiple messages, you should not obtain a fresh one for every message you send.
Also, you should make sure to periodically try to send a message over the FCPPluginConnection and check whether you receive a reply to check whether the connection still is alive: There is no other mechanism of indicating a closed connection to you than not getting back any reply to messages you send. So if your plugin does send messages very infrequently, and thus might keep a reference to a dead FCPPluginConnection for a long time, it might be indicated to create a "keepalive-loop" which sends "ping" messages periodically and reconnects if no "pong" message is received within a sane timeout. Whether a server plugin supports a special "ping" message or requires you to use another type of message as ping is left up to the implementation of the server plugin.

Performance

While you are formally connecting via FCP, there is no actual network connection being created. The FCP messages are passed-through directly as Java objects. Therefore, this mechanism should be somewhat efficient.
Thus, plugins should communicate via FCP instead of passing objects of their own Java classes even if they are running within the same node because this encourages implementation of FCP servers, which in turn allows people to write alternative user interfaces for plugins.
Also, this will allow future changes to the node to make it able to run each plugin within its own node and only connect them via real networked FCP connections. This could be used for load balancing of plugins across multiple machines, CPU usage monitoring, sandboxing and other nice stuff.

Parameters:

pluginName - The name of the main class of the plugin - that is the class which implements FredPlugin. See PluginManager.getPluginInfoByClassName(String).

messageHandler - An object of your plugin which implements the FredPluginFCPMessageHandler.ClientSideFCPMessageHandler interface. Its purpose is to handle FCP messages which the remote plugin sends back to your plugin.

Returns:

A FCPPluginConnection representing the client connection.
Please do read the whole JavaDoc of this function to know how to use it properly.

Throws:

PluginNotFoundException

getPluginConnectionByID

public FCPPluginConnection getPluginConnectionByID(java.util.UUID connectionID)
                                            throws java.io.IOException

Allows FCP server plugins, that is plugins which implement FredPluginFCPMessageHandler.ServerSideFCPMessageHandler, to obtain an existing client FCPPluginConnection by its UUID - if the client is still connected.

May be used by servers which cannot store objects in memory, for example because they are using a database: An UUID can be serialized to disk, serialization would not be possible for a FCPPluginConnection.
Servers are however free to instead keep the FCPPluginConnection in memory, usage of this function is not mandatory.

Must not be used by client plugins: They shall instead keep a hard reference to the FCPPluginConnection in memory after they have received it from connectToOtherPlugin(String, FredPluginFCPMessageHandler.ClientSideFCPMessageHandler). If they did not keep a hard reference and only stored the ID, the FCPPluginConnection would be garbage collected and thus considered as disconnected.

Before you use this function, you should definitely also read the JavaDoc of FredPluginFCPMessageHandler.ServerSideFCPMessageHandler.handlePluginFCPMessage( FCPPluginConnection, FCPPluginMessage) for full instructions on how to handle the lifecycle of client connections and their disconnection.

Parameters:

connectionID - The connection's UUID as obtained by FCPPluginConnection.getID().

Returns:

The client connection if it is still connected.

Throws:

java.io.IOException - If there has been no client connection with the given ID or if the client has disconnected already.
If this happens, you should consider the connection UUID as invalid forever and discard it.

See Also:

The message handler at FredPluginFCPMessageHandler.ServerSideFCPMessageHandler provides an explanation of when to use this.

getToadletContainer

public ToadletContainer getToadletContainer()

Get the ToadletContainer, which manages HTTP. You can then register toadlets on it, which allow integrating your plugin into the main menus, and are a more versatile interface than FredPluginHTTP.

getStore

public PluginStore getStore()
                     throws PersistenceDisabledException

Get a PluginStore that can be used by the plugin to put data in a database. The database used is the node's database, so all the encrypt/decrypt part is already automatically handled according to the physical security level.

Parameters:

storeIdentifier - PluginStore identifier, Plugin's name or some other identifier.

Returns:

PluginStore

Throws:

DatabaseDisabledException

PersistenceDisabledException

putStore

public void putStore(PluginStore store)
              throws PersistenceDisabledException

This should be called by the plugin to store its PluginStore in the node's database.

Parameters:

store - Store to put.

storeIdentifier - Some string to identify the store, basically the plugin's name.

Throws:

DatabaseDisabledException

PersistenceDisabledException

getSessionManager

@Deprecated
public SessionManager getSessionManager(java.net.URI cookiePath)

Deprecated.

Get a new session manager for use with the specified path. See SessionManager for a detailed explanation of what cookie paths are. The usage of the global "/" path is not allowed. You must use getSessionManager(String cookieNamespace) if you want your cookie to be valid in the "/" path. This function is synchronized on the SessionManager-list and therefore concurrency-proof.

getSessionManager

public SessionManager getSessionManager(java.lang.String cookieNamespace)

Get a new session manager for use with the global "/" cookie path and the given cookie namespace. See SessionManager for a detailed explanation of what cookie namespaces are. This function is synchronized on the SessionManager-list and therefore concurrency-proof.

Parameters:

myCookieNamespace - The name of the client application which uses this cookie.

getSubConfig

public SubConfig getSubConfig()

Get the plugin's SubConfig. If the plugin does not implement FredPluginConfigurable, this will return null.

storeConfig

public void storeConfig()

Force a write of the plugin's config file. If the plugin does not implement FredPluginConfigurable, don't expect magic to happen.