From 64bee77d44adbe0c5f071f9e4fdfa0a3e02b7d2e Mon Sep 17 00:00:00 2001
From: Sebastian Utz <su@rtme.net>
Date: Tue, 28 Apr 2015 22:17:43 +0200
Subject: [PATCH] add plugin documentation

---
 docs/index_html.rst |   1 +
 docs/plugins.txt    | 111 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 112 insertions(+)
 create mode 100644 docs/plugins.txt

diff --git a/docs/index_html.rst b/docs/index_html.rst
index 9aa4b9b127bc..391afa88de66 100644
--- a/docs/index_html.rst
+++ b/docs/index_html.rst
@@ -22,6 +22,7 @@ Contents
    hello
    sql/index
    blob
+   plugins
    udc
    storage_consistency
    best_practice/index
diff --git a/docs/plugins.txt b/docs/plugins.txt
new file mode 100644
index 000000000000..2a8fbb1310d3
--- /dev/null
+++ b/docs/plugins.txt
@@ -0,0 +1,111 @@
+.. _plugins:
+
+=========
+ Plugins
+=========
+
+Crate implements a plugin loading infrastructure making it possible to
+develop plugins for crate.
+
+A plugin must at least:
+
+ - implement the ``io.crate.Plugin`` interface
+ - register its implementation at
+   ``META-INF/services/io.crate.Plugin``
+   | so crate plugin load can find it.
+
+See our `example crate plugin`_ for details about that.
+
+.. _plugins_loading:
+
+Plugin Loading
+==============
+
+Loading of plugins is done by crate for searching all class path
+element resources for a ``META-INF/services`` file named like the
+`Plugin interface`_: **io.crate.Plugin**
+
+Inside this file just one line is allowed defining the FQN class name
+which is implementing the `Plugin interface`_. This is almost the same
+like you may know from Java's ServiceLoader.
+
+Constructor with ``Settings`` argument
+--------------------------------------
+Crate passes a ``Settings`` instance to the plugin implementation
+constructor if such a constructor exists. Otherwise an empty
+constructor is used. By using the ``Settings`` instance, a plugin can
+process existing settings and/or implement it's own custom setting entries.
+
+The `example crate plugin`_ makes use of that for implementing a
+custom setting.
+
+.. _plugins_interface:
+
+Plugin Interface
+================
+
+As described at the ``io.crate.Plugin`` interface, a plugin can hook
+in lot of serveral modules by implementing relevant methods:
+
+  - node level modules (singleton per node)
+  - index level modules (singletons per index on a node)
+  - shard level modules (singletons per shard of an index on a node)
+
+Besides of this more generic hooks, a plugin can also listen to
+concrete module bindings, e.g. as our `example crate plugin`_ does, to
+the binding of the ``ScalarFunctionModule`` in order to register
+scalar functions. This can be achieved by implementing a related
+``onModule(AnyModule module)`` method, e.g.::
+
+  ....
+  public void onModule(ScalarFunctionModule module) {
+      MyAwesomeScalaFunction.register(module)
+  }
+  ...
+
+Again, checkout `example crate plugin`_ to see this in action.
+
+.. _plugins_abstract_plugin:
+
+AbstractPlugin Class
+====================
+
+A good start for developing an own plugin is to extend the implementation
+from ``io.crate.plugin.AbstractPlugin``, which already implements all
+by interface required methods. So one must just overwride the relevant
+one. E.g.::
+
+  public class MyAwesomePlugin extends AbstractPlugin {
+
+      @Override
+      public String name() {
+          return "myawesome-plugin";
+      }
+
+      @Override
+      public String description() {
+          return "A really awesome crate plugin";
+      }
+
+      @Override
+      public Settings additionalSettings() {
+      ImmutableSettings.Builder builder = ImmutableSettings.builder();
+      // This plugin enables ``stats`` by default
+      builder.put("stats.enabled", true);
+      return builder.build();
+      }
+  }
+
+Methods ``name`` and ``description`` must be always implemented,
+anything else is already implemented by the abstract plugin class.
+
+Installing a Plugin
+===================
+
+Installing a plugin is simply done by copying the plugin jar (and
+maybe it's dependencies) to crate's class path, usually at
+``<CRATE_HOME>/lib``. Afterwards a node/cluster restart should load
+the plugin.
+
+
+.. _`example crate plugin`: https://github.com/crate/crate-example-plugin