-
Notifications
You must be signed in to change notification settings - Fork 549
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
2 changed files
with
112 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -22,6 +22,7 @@ Contents | |
hello | ||
sql/index | ||
blob | ||
plugins | ||
udc | ||
storage_consistency | ||
best_practice/index | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |