Edit

Extending Ignite.NET With Custom Plugins

Overview

The Ignite.NET plugin system allows you to extend the core Ignite.NET functionality with custom plugins. The best way to explain how Ignite plugins work is by looking at the life cycle of plugins.

IgniteConfiguration.PluginConfigurations

First, an Apache Ignite plugin has to be registered via the IgniteConfiguration.PluginConfigurations property which is a collection of the IPluginConfiguration implementations. From a user’s perspective, this is a manual process - a plugin’s assembly has to be referenced and configured explicitly.

The IPluginConfiguration interface has two members that interact with the Java part of Apache Ignite.NET. This is described in the next section. Besides those two members, IPluginConfiguration implementation should contain all the other plugin-specific configuration properties.

Another part of an IPluginConfiguration implementation is the mandatory [PluginProviderType] attribute that tethers a plugin configuration with a plugin implementation. For example:

[PluginProviderType(typeof(MyPluginProvider))]
    public class MyPluginConfiguration : IPluginConfiguration
    {
        public string MyProperty { get; set; }  // Plugin-specific property

        public int? PluginConfigurationClosureFactoryId
        {
            get { return null; }  // No Java part
        }

        public void WriteBinary(IBinaryRawWriter writer)
        {
            // No-op.
        }
    }

To recap, this is how plugins are added and initialized:

You add the IPluginConfiguration implementation instance to IgniteConfiguration.
You start an Ignite node with the prepared configuration.
Before the Ignite node initialization is finished, the Ignite plugin engine examines the IPluginConfiguration implementation for the [PluginProviderType] attribute and instantiates the specified class.

IPluginProvider

The IPluginProvider implementation is the work-horse of the newly added plugin. It deals with the Ignite node life cycle by processing the calls to the OnIgniteStart and OnIgniteStop methods. In addition, it can provide an optional API to be used by an end user via the GetPlugin<T>() method.

The first method to be invoked on the IPluginProvider implementation by the Ignite.NET engine is Start(IPluginContext<TestIgnitePluginConfiguration> context). IPluginContext provides an access to an initial plugin configuration and all means to interact with Ignite.

When Ignite is being stopped, the Stop and OnIgniteStop methods are executed sequentially so that the plugin implementation can accomplish all cleanup and shutdown-related tasks.

IIgnite.GetPlugin

Plugins can expose user-facing API which is accessed via the IIgnite.GetPlugin(string name) method. The Ignite engine will search for IPluginProvider with the passed name and call GetPlugin on it.

Interacting With Java

The Ignite.NET plugin can interact with an Ignite Java plugin via the PlatformTarget & IPlatformTarget interface pair.

Java-Specific Logic

Implement the PlatformTarget interface, which is a communication point with .NET:

class MyPluginTarget implements PlatformTarget {
  @Override public long processInLongOutLong(int type, long val) throws IgniteCheckedException {
    if (type == 1)
        return val + 1;
    else
      return val - 1;
  }
  ...  // Other methods here.
}

Implement the PlatformPluginExtension interface:

public class MyPluginExtension implements PlatformPluginExtension {
  @Override public int id() {
    return 42;  // Unique id to be used from .NET side.
  }

  @Override public PlatformTarget createTarget() {
    return new MyPluginTarget();  // Return target from previous step.
  }
}

Implement the PluginProvider.initExtensions method and register the PlatformPluginExtension class:

@Override public void initExtensions(PluginContext ctx, ExtensionRegistry registry) {
  registry.registerExtension(PlatformPluginExtension.class, new MyPluginExtension());
}

.NET-specific Logic

Call IPluginContext.GetExtension with a corresponding id. This will invoke the createTarget call on the Java side:

IPlatformTarget extension = pluginContext.GetExtension(42);

long result = extension.InLongOutLong(1, 2);  // processInLongOutLong is called in Java

Other IPlatformTarget methods provide an efficient way to exchange any kind of data between Java and .NET code.

Callbacks from Java

NET -> Java call mechanism is described above; you can also do Java -> .NET calls:

Register callback handler with some ID on the .NET side via the IPluginContext.RegisterCallback method.
Call PlatformCallbackGateway.pluginCallback with that ID on the Java side.

Note	Complete Example A detailed walk-through plugin example can be found in this blog post.

© 2024 The Apache Software Foundation.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.