---
title: "Plug-in API"
url: https://docs.zeroc.com/ice/3.8/plugins/plug-in-facility/plug-in-api
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# Plug-in API

This page is written for C++, C#, and Java.

Parts of this page are for some programming languages only, and name them. For one language's text alone, see [C++](https://docs.zeroc.com/ice/3.8/plugins/plug-in-facility/plug-in-api/cpp.md), [C#](https://docs.zeroc.com/ice/3.8/plugins/plug-in-facility/plug-in-api/csharp.md), and [Java](https://docs.zeroc.com/ice/3.8/plugins/plug-in-facility/plug-in-api/java.md).

> **C++**
>
> ## The `Plugin` Base Class
>
> A C++ plug-in is an instance of a class that implements the `Ice::Plugin` abstract base class:
>
> ```cpp
> namespace Ice
> {
>     class Plugin
>     {
>     public:
>         virtual ~Plugin();
>         virtual void initialize() = 0;
>         virtual void destroy() = 0;
>     };
> }
> ```
>
> A plug-in object's lifecycle consists of four phases:
>
> - **Construction** Ice calls the plug-in factory during communicator initialization. Acquire resources here, but defer starting threads and using other plug-ins until `initialize`.
> - **Initialization** After constructing all plug-ins, Ice calls `initialize` in construction order. Factories in `InitializationData.pluginFactories` run in list order, followed by plug-ins loaded through configuration. Use [Ice.PluginLoadOrder](https://docs.zeroc.com/ice/3.8/property-reference/ice-properties/cpp.md#ice.pluginloadorder) to order the latter. A plug-in can use another plug-in after that plug-in has initialized.
> - **Active use** The plug-in provides its services until the communicator is destroyed. Its implementation must handle concurrent calls when multiple threads use these services.
> - **Destruction** When the communicator is destroyed, Ice calls `destroy` in reverse initialization order.
>
> If the `initialize` method of a plug-in throws an exception, communicator initialization fails with `PluginInitializationException`. Ice does not call `destroy` on this plug-in: `initialize` must release the resources it acquired before throwing.
>
> ## Plug-in Factory Function
>
> In C++, a plug-in factory is a function with the following signature:
>
> ```cpp
> using PluginFactoryFunc = Ice::Plugin* (*)(const Ice::CommunicatorPtr& communicator,
>                                           const std::string& name,
>                                           const Ice::StringSeq& args);
> ```
>
> You can choose any name for the factory function of your plug-in. If you want to load this plug-in at runtime, you will need to export this function from the library and provide its name in configuration. Use C linkage to avoid name-mangling. For example:
>
> ```cpp
> extern "C" ICE_DECLSPEC_EXPORT Ice::Plugin* createPlugin(
>     const Ice::CommunicatorPtr& communicator,
>     const std::string& name,
>     const Ice::StringSeq& args);
> ```
>
> The arguments to the function consist of the communicator that is in the process of being initialized, the name assigned to the plug-in, and any arguments that were specified in the [plug-in's configuration](https://docs.zeroc.com/ice/3.8/property-reference/ice-plugin-properties/cpp.md).
>
> Allocate the plug-in with `new`. Ice takes ownership of the pointer returned by the factory function.
>
> ## Loading a Plug-in Using InitializationData
>
> When your application depends on a plug-in, you should load this plug-in into your communicator by adding a factory for this plug-in to the `pluginFactories` field of your communicator’s `InitializationData`.
>
> For example:
>
> ```cpp
> #include <Ice/Ice.h>
> #include <IceDiscovery/IceDiscovery.h>
>
> Ice::InitializationData initData;
> initData.properties = Ice::createProperties(argc, argv);
> initData.pluginFactories = {IceDiscovery::discoveryPluginFactory()};
>
> Ice::CommunicatorPtr communicator = Ice::initialize(initData);
> ```
>
> `pluginFactories` is a vector of:
>
> ```cpp
> struct PluginFactory
> {
>     /// The name of the plug-ins created by this factory.
>     std::string pluginName;
>
>     /// The factory function.
>     Ice::PluginFactoryFunc factoryFunc;
> };
> ```
>
> Ice creates the plug-ins in list order, each with the name given by its factory, before the plug-ins loaded through configuration. To pass arguments to one of these plug-ins, set the `Ice.Plugin.Name` property, where `Name` is the plug-in's name. Ice ignores the first token of the value, which holds the entry point of a plug-in loaded through configuration, and passes the remaining tokens to the factory. By convention, this first token is `1`. For example:
>
> ```config
> Ice.Plugin.MyPlugin=1 arg1 arg2
> ```
>
> ## Managing Plug-ins
>
> The plug-in manager of a communicator gives access to its plug-ins: call `getPluginManager` on the communicator, then `getPlugin` with the name of the plug-in. See [PluginManager](https://code.zeroc.com/ice/3.8/api/cpp/classIce_1_1PluginManager.html) in the API reference.
>
> To configure a plug-in through its own API before Ice initializes it, set [Ice.InitPlugins](https://docs.zeroc.com/ice/3.8/property-reference/ice-properties/cpp.md#ice.initplugins) to `0`. Create the communicator, obtain the plug-in with `getPlugin`, configure it, and then call `initializePlugins` on the plug-in manager.
>
> ## Transport Factories and Static Linking
>
> The Ice C++ shared library registers the TCP, SSL, UDP, and WebSocket transports automatically. The static Ice library registers only TCP and SSL: when you link with this library, add `Ice::udpPluginFactory()` or `Ice::wsPluginFactory()` to `pluginFactories` for the UDP or WebSocket transport you need. The IceDiscovery and IceLocatorDiscovery plug-ins need UDP.
>
> ## See Also
>
> - [Plug-in Configuration](https://docs.zeroc.com/ice/3.8/plugins/plug-in-facility/installing-a-plug-in-using-configuration/cpp.md)
> - [Ice.Plugin.\*](https://docs.zeroc.com/ice/3.8/property-reference/ice-plugin-properties/cpp.md)

> **C#**
>
> ## The `Plugin` Interface
>
> A C# plug-in is an instance of a class that implements the `Ice.Plugin` interface:
>
> ```csharp
> namespace Ice;
>
> public interface Plugin
> {
>     void initialize();
>     void destroy();
> }
> ```
>
> A plug-in object's lifecycle consists of four phases:
>
> - **Construction** Ice calls the plug-in factory during communicator initialization. Acquire resources here, but defer starting threads and using other plug-ins until `initialize`.
> - **Initialization** After constructing all plug-ins, Ice calls `initialize` in construction order. Factories in `InitializationData.pluginFactories` run in list order, followed by plug-ins loaded through configuration. Use [Ice.PluginLoadOrder](https://docs.zeroc.com/ice/3.8/property-reference/ice-properties/csharp.md#ice.pluginloadorder) to order the latter. A plug-in can use another plug-in after that plug-in has initialized.
> - **Active use** The plug-in provides its services until the communicator is destroyed. Its implementation must handle concurrent calls when multiple threads use these services.
> - **Destruction** When the communicator is destroyed, Ice calls `destroy` in reverse initialization order.
>
> If the `initialize` method of a plug-in throws an exception, communicator initialization fails with `PluginInitializationException`. Ice does not call `destroy` on this plug-in: `initialize` must release the resources it acquired before throwing.
>
> ## Plug-in Factory
>
> In C#, a plug-in factory is a class that implements the `PluginFactory` interface:
>
> ```csharp
> namespace Ice;
>
> public interface PluginFactory
> {
>     string pluginName { get; }
>
>     Plugin create(Communicator communicator, string name, string[] args);
> }
> ```
>
> The arguments to the create method consist of the communicator that is in the process of being initialized, the name assigned to the plug-in, and any arguments that were specified in the [plug-in's configuration](https://docs.zeroc.com/ice/3.8/property-reference/ice-plugin-properties/csharp.md).
>
> Ice uses `pluginName` as the name of the plug-in when it creates a plug-in configured using `InitializationData.pluginFactories` (see below).
>
> ## Loading a Plug-in Using InitializationData
>
> When your application depends on a plug-in, you should load this plug-in into your communicator by adding a factory for this plug-in to the `pluginFactories` field of your communicator’s `InitializationData`.
>
> For example:
>
> ```csharp
> var initData = new Ice.InitializationData
> {
>     properties = new Ice.Properties(ref args),
>     pluginFactories = [new IceDiscovery.PluginFactory()]
> };
>
> await using Ice.Communicator communicator = Ice.Util.initialize(initData);
> ```
>
> `pluginFactories` is a list of `PluginFactory`.
>
> Ice creates the plug-ins in list order, each with the name given by its factory, before the plug-ins loaded through configuration. To pass arguments to one of these plug-ins, set the `Ice.Plugin.Name` property, where `Name` is the plug-in's name. Ice ignores the first token of the value, which holds the entry point of a plug-in loaded through configuration, and passes the remaining tokens to the factory. By convention, this first token is `1`. For example:
>
> ```config
> Ice.Plugin.MyPlugin=1 arg1 arg2
> ```
>
> ## Managing Plug-ins
>
> The plug-in manager of a communicator gives access to its plug-ins: call `getPluginManager` on the communicator, then `getPlugin` with the name of the plug-in. See [PluginManager](https://code.zeroc.com/ice/3.8/api/csharp/api/Ice.PluginManager.html) in the API reference.
>
> To configure a plug-in through its own API before Ice initializes it, set [Ice.InitPlugins](https://docs.zeroc.com/ice/3.8/property-reference/ice-properties/csharp.md#ice.initplugins) to `0`. Create the communicator, obtain the plug-in with `getPlugin`, configure it, and then call `initializePlugins` on the plug-in manager.
>
> ## See Also
>
> - [Plug-in Configuration](https://docs.zeroc.com/ice/3.8/plugins/plug-in-facility/installing-a-plug-in-using-configuration/csharp.md)
> - [Ice.Plugin.\*](https://docs.zeroc.com/ice/3.8/property-reference/ice-plugin-properties/csharp.md)

> **Java**
>
> ## The `Plugin` Interface
>
> A Java plug-in is an instance of a class that implements the `com.zeroc.Ice.Plugin` interface:
>
> ```java
> package com.zeroc.Ice;
>
> public interface Plugin {
>     void initialize();
>     void destroy();
> }
> ```
>
> A plug-in object's lifecycle consists of four phases:
>
> - **Construction** Ice calls the plug-in factory during communicator initialization. Acquire resources here, but defer starting threads and using other plug-ins until `initialize`.
> - **Initialization** After constructing all plug-ins, Ice calls `initialize` in construction order. Factories in `InitializationData.pluginFactories` run in list order, followed by plug-ins loaded through configuration. Use [Ice.PluginLoadOrder](https://docs.zeroc.com/ice/3.8/property-reference/ice-properties/java.md#ice.pluginloadorder) to order the latter. A plug-in can use another plug-in after that plug-in has initialized.
> - **Active use** The plug-in provides its services until the communicator is destroyed. Its implementation must handle concurrent calls when multiple threads use these services.
> - **Destruction** When the communicator is destroyed, Ice calls `destroy` in reverse initialization order.
>
> If the `initialize` method of a plug-in throws an exception, communicator initialization fails with `PluginInitializationException`. Ice does not call `destroy` on this plug-in: `initialize` must release the resources it acquired before throwing.
>
> ## Plug-in Factory
>
> In Java, a plug-in factory is a class that implements the `PluginFactory` interface:
>
> ```java
> package com.zeroc.Ice;
>
> public interface PluginFactory {
>     String getPluginName();
>     Plugin create(Communicator communicator, String name, String[] args);
> }
> ```
>
> The arguments to the create method consist of the communicator that is in the process of being initialized, the name assigned to the plug-in, and any arguments that were specified in the [plug-in's configuration](https://docs.zeroc.com/ice/3.8/property-reference/ice-plugin-properties/java.md).
>
> Ice uses the value returned by `getPluginName()` as the name of the plug-in when it creates a plug-in configured using `InitializationData.pluginFactories` (see below).
>
> ## Loading a Plug-in Using InitializationData
>
> When your application depends on a plug-in, you should load this plug-in into your communicator by adding a factory for this plug-in to the `pluginFactories` field of your communicator’s `InitializationData`.
>
> For example:
>
> ```java
> InitializationData initData = new InitializationData();
> initData.properties = new com.zeroc.Ice.Properties(args);
> initData.pluginFactories =
>     java.util.List.of(new com.zeroc.IceDiscovery.PluginFactory());
>
> try (Communicator communicator = new Communicator(initData)) {
>     // Use the communicator.
> }
> ```
>
> `pluginFactories` is a list of `com.zeroc.Ice.PluginFactory`.
>
> Ice creates the plug-ins in list order, each with the name given by its factory, before the plug-ins loaded through configuration. To pass arguments to one of these plug-ins, set the `Ice.Plugin.Name` property, where `Name` is the plug-in's name. Ice ignores the first token of the value, which holds the entry point of a plug-in loaded through configuration, and passes the remaining tokens to the factory. By convention, this first token is `1`. For example:
>
> ```config
> Ice.Plugin.MyPlugin=1 arg1 arg2
> ```
>
> ## Managing Plug-ins
>
> The plug-in manager of a communicator gives access to its plug-ins: call `getPluginManager` on the communicator, then `getPlugin` with the name of the plug-in. See [PluginManager](https://code.zeroc.com/ice/3.8/api/java/com.zeroc.ice/com/zeroc/Ice/PluginManager.html) in the API reference.
>
> To configure a plug-in through its own API before Ice initializes it, set [Ice.InitPlugins](https://docs.zeroc.com/ice/3.8/property-reference/ice-properties/java.md#ice.initplugins) to `0`. Create the communicator, obtain the plug-in with `getPlugin`, configure it, and then call `initializePlugins` on the plug-in manager.
>
> ## See Also
>
> - [Plug-in Configuration](https://docs.zeroc.com/ice/3.8/plugins/plug-in-facility/installing-a-plug-in-using-configuration/java.md)
> - [Ice.Plugin.\*](https://docs.zeroc.com/ice/3.8/property-reference/ice-plugin-properties/java.md)
