On this page:
Plugin
InterfaceThe plug-in facility defines a local Slice interface that all plug-ins must implement:
{zcode:slice} module Ice { local interface Plugin { void initialize(); void destroy(); }; }; {zcode} |
The lifecycle of an Ice plug-in is structured to accommodate dependencies between plug-ins, such as when a logger plug-in needs to use IceSSL for its logging activities. Consequently, a plug-in object's lifecycle consists of four phases:
initialize
on each plug-in. The order in which plug-ins are initialized is undefined by default but can be customized using a configuration property. If a plug-in has a dependency on another plug-in, you must configure the Ice run time so that initialization occurs in the proper order. In this phase it is safe for a plug-in to spawn new threads; it is also safe for a plug-in to interact with other plug-ins and use their services, as long as those plug-ins have already been initialized. If initialize
raises an exception, the Ice run time invokes destroy
on all plug-ins that were successfully initialized (in the reverse order of initialization) and raises the original exception to the application.destroy
on each plug-in in the reverse order of initialization.This lifecycle is repeated for each new communicator that an application creates and destroys.
In C++, the plug-in factory is an exported function with C linkage having the following signature:
{zcode:cpp} extern "C" { ICE_DECLSPEC_EXPORT Ice::Plugin* functionName(const Ice::CommunicatorPtr& communicator, const std::string& name, const Ice::StringSeq& args); } {zcode} |
You can define the function with any name you wish. We recommend that you use the ICE_DECLSPEC_EXPORT
macro to ensure that the function is exported correctly on all platforms. Since the function uses C linkage, it must return the plug-in object as a regular C++ pointer and not as an Ice smart pointer. Furthermore, the function must not raise C++ exceptions; if an error occurs, the function must return zero.
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.
In Java, a plug-in factory must implement the Ice.PluginFactory
interface:
{zcode:java} package Ice; public interface PluginFactory { Plugin create(Communicator communicator, String name, String[] args); } {zcode} |
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.
The create
method can return null
to indicate that a general error occurred, or it can raise PluginInitializationException
to provide more detailed information. If any other exception is raised, the Ice run time wraps it inside an instance of PluginInitializationException
.
In .NET, a plug-in factory must implement the Ice.PluginFactory
interface:
{zcode:cs} namespace Ice { public interface PluginFactory { Plugin create(Communicator communicator, string name, string[] args); } } {zcode} |
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.
The create
method can return null
to indicate that a general error occurred, or it can raise PluginInitializationException
to provide more detailed information. If any other exception is raised, the Ice run time wraps it inside an instance of PluginInitializationException
.