This is an automated email from the ASF dual-hosted git repository. abudnikov pushed a commit to branch IGNITE-7595 in repository https://gitbox.apache.org/repos/asf/ignite.git
commit 9fe0aa23eecb877132da13506755f9952f8849b4 Author: abudnikov <[email protected]> AuthorDate: Tue Aug 25 18:10:00 2020 +0300 add draft of the plugins page --- docs/_data/toc.yaml | 2 + .../apache/ignite/snippets/plugin/MyPlugin.java | 62 ++++++++++++++++-- .../ignite/snippets/plugin/MyPluginProvider.java | 76 +++++++++++++--------- .../ignite/snippets/plugin/PluginExample.java | 38 +++++++++-- docs/_docs/code-snippets/xml/plugins.xml | 31 +++++++++ docs/_docs/plugins.adoc | 75 +++++++++++++++++++++ 6 files changed, 242 insertions(+), 42 deletions(-) diff --git a/docs/_data/toc.yaml b/docs/_data/toc.yaml index 81c3ee1..62c8aa0 100644 --- a/docs/_data/toc.yaml +++ b/docs/_data/toc.yaml @@ -249,6 +249,8 @@ url: /restapi - title: Control Script url: /control-script +- title: Plugins + url: /plugins - title: SQLLine url: /sqlline diff --git a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/plugin/MyPlugin.java b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/plugin/MyPlugin.java index c7e1b5c..e441837 100644 --- a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/plugin/MyPlugin.java +++ b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/plugin/MyPlugin.java @@ -1,14 +1,68 @@ package org.apache.ignite.snippets.plugin; +import java.util.concurrent.Executors; +import java.util.concurrent.ScheduledExecutorService; +import java.util.concurrent.TimeUnit; + +import org.apache.ignite.IgniteCache; import org.apache.ignite.plugin.IgnitePlugin; +import org.apache.ignite.plugin.PluginContext; + +/** + * The plugin prints cache size information to console + * @author + * + */ +public class MyPlugin implements IgnitePlugin, Runnable { + + private final ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(1); + + private PluginContext context; + + private long period; + + /** + * + * @param context + */ + public MyPlugin(long period, PluginContext context) { + this.period = period; + this.context = context; + } -public class MyPlugin implements IgnitePlugin { + private void print0() { + StringBuilder sb = new StringBuilder("\nCache Information: \n"); + //get the names of all caches + context.grid().cacheNames().forEach(cacheName -> { + //get the specific cache + IgniteCache cache = context.grid().cache(cacheName); + if (cache != null) { + sb.append(" cacheName=").append(cacheName).append(", size=").append(cache.size()) + .append("\n"); + } + }); - public MyPlugin() { - + System.out.print(sb.toString()); + } + + /** + * Prints the information about caches to console. + */ + public void printCacheInfo() { + print0(); + } + + @Override + public void run() { + print0(); } + void start() { + scheduler.scheduleAtFixedRate(this, period, period, TimeUnit.SECONDS); + } + void stop() { + scheduler.shutdownNow(); + } } - diff --git a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/plugin/MyPluginProvider.java b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/plugin/MyPluginProvider.java index 1f64683..5702299 100644 --- a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/plugin/MyPluginProvider.java +++ b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/plugin/MyPluginProvider.java @@ -5,19 +5,31 @@ import java.util.UUID; import org.apache.ignite.IgniteCheckedException; import org.apache.ignite.cluster.ClusterNode; -import org.apache.ignite.internal.GridPluginComponent; import org.apache.ignite.plugin.CachePluginContext; import org.apache.ignite.plugin.CachePluginProvider; import org.apache.ignite.plugin.ExtensionRegistry; -import org.apache.ignite.plugin.IgnitePlugin; import org.apache.ignite.plugin.PluginConfiguration; import org.apache.ignite.plugin.PluginContext; import org.apache.ignite.plugin.PluginProvider; import org.apache.ignite.plugin.PluginValidationException; import org.jetbrains.annotations.Nullable; -public class MyPluginProvider implements PluginProvider<PluginConfiguration>{ - +public class MyPluginProvider implements PluginProvider<PluginConfiguration> { + + private long period = 10; + + private MyPlugin plugin; + + public MyPluginProvider() { + } + + /** + * + * @param period period in seconds + */ + public MyPluginProvider(long period) { + this.period = period; + } @Override public String name() { @@ -26,74 +38,74 @@ public class MyPluginProvider implements PluginProvider<PluginConfiguration>{ @Override public String version() { - return null; + return "1.0"; } @Override public String copyright() { - return null; + return "MyCompany"; } @Override - public <T extends IgnitePlugin> T plugin() { - System.out.println("plugin"); - return (T) new MyPlugin(); + public MyPlugin plugin() { + return plugin; } @Override - public void initExtensions(PluginContext ctx, ExtensionRegistry registry) throws IgniteCheckedException { - + public void initExtensions(PluginContext ctx, ExtensionRegistry registry) + throws IgniteCheckedException { + plugin = new MyPlugin(period, ctx); } @Override - public <T> @Nullable T createComponent(PluginContext ctx, Class<T> cls) { - //return (T) new GridPluginComponent(this); - return null; + public void onIgniteStart() throws IgniteCheckedException { + plugin.start(); } @Override - public CachePluginProvider createCacheProvider(CachePluginContext ctx) { - return null; + public void onIgniteStop(boolean cancel) { + plugin.stop(); } + public long getPeriod() { + return period; + } + + public void setPeriod(long period) { + this.period = period; + } + + // other no-op methods of PluginProvider + //tag::no-op-methods[] @Override - public void start(PluginContext ctx) throws IgniteCheckedException { - + public <T> @Nullable T createComponent(PluginContext ctx, Class<T> cls) { + return null; } @Override - public void stop(boolean cancel) throws IgniteCheckedException { - + public CachePluginProvider createCacheProvider(CachePluginContext ctx) { + return null; } @Override - public void onIgniteStart() throws IgniteCheckedException { - - System.out.println("onIgnitestart"); - + public void start(PluginContext ctx) throws IgniteCheckedException { } @Override - public void onIgniteStop(boolean cancel) { - + public void stop(boolean cancel) throws IgniteCheckedException { } @Override public @Nullable Serializable provideDiscoveryData(UUID nodeId) { - // TODO Auto-generated method stub return null; } @Override public void receiveDiscoveryData(UUID nodeId, Serializable data) { - // TODO Auto-generated method stub - } @Override public void validateNewNode(ClusterNode node) throws PluginValidationException { - // TODO Auto-generated method stub - } - + //end::no-op-methods[] } diff --git a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/plugin/PluginExample.java b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/plugin/PluginExample.java index b09fe04..ffe8795 100644 --- a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/plugin/PluginExample.java +++ b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/plugin/PluginExample.java @@ -1,24 +1,50 @@ package org.apache.ignite.snippets.plugin; import org.apache.ignite.Ignite; +import org.apache.ignite.IgniteCache; import org.apache.ignite.Ignition; +import org.apache.ignite.configuration.CacheConfiguration; import org.apache.ignite.configuration.IgniteConfiguration; import org.junit.jupiter.api.Test; public class PluginExample { - public static void main(String[] args) { - new PluginExample().specifyPlugin(); - } - @Test - void specifyPlugin() { + void registerPlugin() { + //tag::example[] + //tag::register-plugin[] IgniteConfiguration cfg = new IgniteConfiguration(); - cfg.setPluginProviders(new MyPluginProvider()); + //register a plugin that prints the cache size information every 100 seconds + cfg.setPluginProviders(new MyPluginProvider(100)); + //start the node Ignite ignite = Ignition.start(cfg); + //end::register-plugin[] + //tag::access-plugin[] + //get an instance of the plugin MyPlugin p = ignite.plugin("MyPlugin"); + + //print the cache size information + p.printCacheInfo(); + //end::access-plugin[] + + IgniteCache cache = ignite.getOrCreateCache(new CacheConfiguration("test_cache").setBackups(1)); + + for (int i = 0; i < 10; i++) { + cache.put(i, "value " + i); + } + + //print the cache size information + p.printCacheInfo(); + //end::example[] + // ignite.close(); + } + + public static void main(String[] args) { + PluginExample pe = new PluginExample(); + pe.registerPlugin(); } } + diff --git a/docs/_docs/code-snippets/xml/plugins.xml b/docs/_docs/code-snippets/xml/plugins.xml new file mode 100644 index 0000000..03544cf --- /dev/null +++ b/docs/_docs/code-snippets/xml/plugins.xml @@ -0,0 +1,31 @@ +<?xml version="1.0" encoding="UTF-8"?> +<beans xmlns="http://www.springframework.org/schema/beans"; xmlns:util="http://www.springframework.org/schema/util"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd";> + <!-- tag::ignite-config[] --> + <bean class="org.apache.ignite.configuration.IgniteConfiguration"> + + <property name="pluginProviders"> + <bean class="org.apache.ignite.snippets.plugin.MyPluginProvider"> + <property name="period" value="100"/> + </bean> + </property> + + <!-- tag::discovery[] --> + <property name="discoverySpi"> + <bean class="org.apache.ignite.spi.discovery.tcp.TcpDiscoverySpi"> + <!-- prevent this client from reconnecting on connection loss --> + <property name="clientReconnectDisabled" value="true"/> + <property name="ipFinder"> + <bean class="org.apache.ignite.spi.discovery.tcp.ipfinder.vm.TcpDiscoveryVmIpFinder"> + <property name="addresses"> + <list> + <value>127.0.0.1:47500..47509</value> + </list> + </property> + </bean> + </property> + </bean> + </property> + <!-- end::discovery[] --> + </bean> + <!-- end::ignite-config[] --> +</beans> \ No newline at end of file diff --git a/docs/_docs/plugins.adoc b/docs/_docs/plugins.adoc new file mode 100644 index 0000000..9e59e8e --- /dev/null +++ b/docs/_docs/plugins.adoc @@ -0,0 +1,75 @@ += Plugins + +== Overview + +The Ignite plugin system allows you to extend the core functionality of Ignite. + +To add a custom plugin, implement the `PluginProvider` interface and register the implementation either via `IgniteConfiguration.setPluginProviders()` or service loader. + +. Implement the `IgnitePlugin` interface. If your plugin adds functionality that is meant to be triggered by a user, you should add public methods to this class that trigger specific actions. An instance of this class is available at runtime via `Ignite.plugin(String pluginName)`. + +. Implement the `PluginProvider` interface. The following methods must return non-null values. Other methods are optional. ++ +-- +* `name()` - returns the name of the plugin +* `plugin()` - return the object of your plugin class. + +Plugins have access to the Ignite API and node configuration via `PluginContext`. See the javadoc:org.apache.ignite.plugin.PluginContext[] javadoc for more information. + + +-- + +. Register the plugin via `IgniteConfiguration.setPluginProviders(...)`. + +. At runtime, call `MyPlugin plugin = Ignite.plugin(pluginName)` + + +== Plugin Example + +Let's create a simple Ignite plugin that prints information about the number of entries in every cache to the console periodically, on each node. +In addition, it exposes a public method that the users can call from their application to print the cache size information on demand. + +=== Implement IgnitePlugin +.MyPlugin.java +[source, java] +---- +include::{javaCodeDir}/plugin/MyPlugin.java[tags=, indent=0] +---- + +=== Implement PluginProvider + +.MyPluginProvider.java +[source, java] +---- +include::{javaCodeDir}/plugin/MyPluginProvider.java[tags=!no-op-methods, indent=0] +---- + +=== Register your Plugin + + +Programmatically: + +[source, java] +---- +include::{javaCodeDir}/plugin/PluginExample.java[tags=register-plugin, indent=0] +---- + + +Via XML Configuration: + +Compile your plugin source code and add the classes to the classpath on each node. +Then, you can register the plugin as follows: + +[source, xml] +---- +include::code-snippets/xml/plugins.xml[tags=ignite-config;!discovery, indent=0] +---- + +=== Access the Plugin at Runtime + +[source, java] +---- +include::{javaCodeDir}/plugin/PluginExample.java[tags=access-plugin, indent=0] + +---- +
