This document describes the C language interface for the NTCP Control Plugin described in the Control Plugin Description (DRAFT). The audience of this document are people who are interested in implementing native c-language control plugins for the NTCP server. This document describes the general requirements of a plugin, the functions which must be implemented by a plugin, and the API available for the plugin to interact with the NEES server.
Plugins will be implemented as a shared object or DLL which must be thread-safe, using the same threading model as the JVM. This software has been tested on the following platforms:
Plugins must export a function called initialize_plugin, of type nees_ntcp_plugin_init_t. This will be called by the NTCP server when a new plugin instance is requested. The plugin implementation must return pointers to functions which implement the rest of the plugin interface as well as an optional void * argument which will be passed to each of those, which may be used to point to plugin instance-specific data.
All plugin function types return an integer value: zero for success and non-zero for failure. When a non-zero value is returned, the plugin driver will call the plugin's nees_ntcp_plugin_error_string_t function to translate the error to a string which will be added to the exception which is thrown to the NTCP server. A more detailed description of the plugin function types is available in the plugin functions page.
This interface also defines a number of abstract data types which correspond to the Java classes used by the NTCP server implementation to pass values from the client to the plugin implementation. These are described in the data types page.
The NTCP server is configured via a WSDD file in its installation directory. This file contains (among other things) a sequence of service defintions. In the definition of the nees/ntcp/NTCPServer service, the ntcpBackendFactory and the org.nees.ntcp.plugins.gateway.module parameters must be defined to use the NTCP C Gateway Plugin and the native C plugin code.
The shared object name should either contain the absolute path of the object or DLL, or just the base name of an object or DLL in the runtime-linker's search path. For linux, this object must be in a directory contained in the LD_LIBRARY_PATH environment variable. For windows the DLL must be in a directory contained in the PATH environment variable. If the shared object cannot be found, an error will be generated on linux, but on windows, the NTCP server will fail in native code.
The following is an example WSDD fragment which will configure an NTCP server to use the native plugin located in the shared library "neesgrid_c_plugin.so", with the changes from the default NTCP Server WSDD highlighted.
<service name="nees/ntcp/NTCPServer" provider="Handler" style="wrapped">
<parameter name="name" value="NTCP Server"/>
<parameter name="schemaPath"
value="schema/nees/ntcp/ntcp_server_service.wsdl"/>
<parameter name="className"
value="org.nees.ntcp.ntcpServer.NtcpServer"/>
<parameter name="baseClassName"
value="org.nees.ntcp.server.impl.NtcpServerImpl"/>
<parameter name="operationProviders"
value="org.globus.ogsa.impl.ogsi.NotificationSourceProvider"/>
<parameter name="handlerClass"
value="org.globus.ogsa.handlers.RPCURIProvider"/>
<parameter name="persistent" value="true"/>
<parameter name="allowedMethods" value="*"/>
<parameter name="isSecure" value="true"/>
<parameter name="isProfiling" value="false"/>
<parameter name="localPolicyPlugin"
value="org.nees.ntcp.server.backend.test.DummyLocalPolicyPlugin"/>
<parameter name="ntcpBackendFactory"
value="org.nees.ntcp.plugins.gateway.GatewayPluginFactory"/>
<parameter name="org.nees.ntcp.plugins.gateway.module"
value="neesgrid_c_plugin.so"/>
</service>
By default, the Java gateway plugin will load the C gateway plugin code from libnees_ntcp_control_plugin_gcc32dbgpthr.so on linux and nees_ntcp_control_plugin_win32dbgthr.dll on windows. The shared object must be found in one of the directories in LD_LIBRARY_PATH or PATH environment variables in linux and windows respectively. If the plugin is installed with a different name or Globus flavor, then the Java System properties org.nees.ntcp.plugins.gateway.lib and org.nees.ntcp.plugins.gateway.flavor can be used to let the Java Gateway Plugin know what shared object or DLL to load.
For example, to use the gateway plugin library "libnees_ntcp_control_plugin_vendorcc32pthr.so" instead of "libnees_ntcp_control_plugin_gcc32dbgpthr.so" on linux, the property org.nees.ntcp.plugins.gateway.flavor should be set to "vendorcc32pthr" and the org.nees.ntcp.plugins.gateway.flavor property can be omitted. System properties are typically set by passing -Dproperty-name=property-value on the Java command line, so this example would be to add -Dorg.nees.ntcp.plugins.gateway.flavor=vendorcc32pthr to the Java command line.
about globus |
grid research |
globus toolkit |
software development
Comments? webmaster@globus.org