Skip to content

Latest commit

 

History

History
139 lines (94 loc) · 3.34 KB

plugins.rst

File metadata and controls

139 lines (94 loc) · 3.34 KB

Plugins

CrateDB implements a plugin loading infrastructure. To add functionalities, you can develop plugins for CrateDB.

A plugin must:

  • implement the io.crate.Plugin interface
  • register its implementation at META-INF/services/io.crate.Plugin so that CrateDB plugin load can find it

Refer to our CrateDB example plugin for more details.

Plugin CrateDB Dependency

In order to develop a plugin against a CrateDB release, a dependency to the CrateDB's server libraries must be set up.

Gradle

Define bintray (jCenter) repository:

repositories {
    jcenter()
}

Add CrateDB to compile dependencies:

dependencies {
    compile 'io.crate:crate:<VERSION>'
}

Maven

Add bintray (jCenter) as a repository to your maven settings.xml:

Add CrateDB as a dependency:

Plugin Loading

Loading of plugins is done by CrateDB by searching all class path element resources for a META-INF/services/io.crate.Plugin file.

Inside this file, one line is allowed to define the full qualified class name which implements the Plugin interface. This is similar to Java's ServiceLoader.

Constructor with Settings argument

CrateDB 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 its own custom setting entries.

The CrateDB example plugin makes use of that to implement a custom setting.

java

Plugin Interface

CrateDB uses the Guice module binding concept and so do plugins. As described in the io.crate.Plugin interface, a plugin can load several module types by implementing relevant methods:

  • lifecycle services
  • node level modules

This enables plugin developers to access a lot of functionality. But that comes at the price of API stability. Most of the components in CrateDB are considered internal and may change with any version, including hotfix versions.

The main purpose for the plugins right now is to add additional scalar functions or aggregation functions. An example of a plugin that does that is CrateDB example plugin.

Installing a Plugin

Installing a plugin is done by copying the plugin's JAR file(s) into the class path or to one of the following places:

  • <CRATE_HOME>/plugins/
  • <CRATE_HOME>/plugins/<SOME_PLUGIN_NAME>/
  • <CRATE_HOME>/plugins/<SOME_PLUGIN_NAME>/lib/