Friendlyskies AoI Forum

Hey Kintel!

Welcome to the forum, and welcome to the world of AOI plugins! :-)

One question: Are the external plugins you are calling existing plugins (such as STLTranslator) or are they effectively sub-plugins of your plugin (ie, they implement some interface specific to your code)?
This post assumes the former and answers accordingly. If the latter, then AOI supports this, but with different features. If you have this need, post back and ask.


Assuming you are calling existing AOI plugins (eg Translators):

You are correct, but not completely correct. AOI supports "tight" coupling between plugins - where it will load an external plugin into the classloader of your plugin; and AOI also supports "loose" coupling where you can ask AOI to call a method in an external plugin without loading it into your plugin's classloader.

The choice is based primarily on the following:

* tight coupling requires less code for each call, but it is assumed that the external plugin is always available when yours is (you can wrap a try{} block around your code if you're paranoid, but it not normally required).
- Tight coupling is most appropriate when you expect the external plugin to always be available whenever yours is.

* loose coupling needs to have been enabled for the method(s) you wish to call, is slightly more verbose, but is more naturally robust in the face of missing plugins.
- Loose coupling is most appropriate when the the presence of the external plugin is optional, or not guaranteed.

Tight and loose coupling can be combined in the one calling plugin.

1. Tight coupling is accomplished through the "extensions.xml" file.
1.1 add an "import" line for each plugin you wish to have imported into your plugin's classloader:
<import name="name-of-plugin" />
eg: <import name="STLTranslator" />

1.2 import the external plugin's class(es) in your Java code and call the method(s) directly;

1.3 You will need to ensure the plugin jar or source is visible on the classpath or sourcepath when compiling your plugin, so you'll have to adjust your build (eg Ant) file.

2. Loose coupling is accomplished in the Java code, with optional behaviour enabled in the extensions.xml file.
2.1 in your Java code, use a call to PluginRegistry.invokeExportedMethod() to call into the external plugin method.
*Note that only methods "exported" from a plugin are candidates to be called this way - see the external plugin's extensions.xml file to get a list, or call PluginRegistry.getExportedMethods() to get the list programatically.

2.1a You can also call PluginRegistry to export a method on an external plugin that the plugin author did not originally export. Just call PluginRegistry.getPlugins() or PluginRegistry.getPluginObject() to get the plugin object you need to register the method.

*Note that invokeExportedMethod() throws an exception if the call fails for any reason, including the plugin not being installed.

2.2 add an "external" line to your plugin's extensions.xml file for each external plugin that you want SPManager to automatically install if it is missing when your plugin is installed. SPManager performs transitive dependency resolution over "required" external plugins.

eg: <external type="plugin" name="STLTranslator" association="required" />

With this line in your extensions.xml file, SPManager will ensure STLTranslator is installed whenever it installs your plugin.

*Note that the <import /> element causes an implicit required dependency to be registered within SPManager, meaning that
<import name="STLTranslator" /> will also cause SPManager to ensure STLTranslator is installed whenever it installs your plugin.

Have fun with all this, and post back if you have more questions.

For example code, see AdvancedRendering which uses both tight and loose coupling in the one plugin - even allowing for one plugin to be optional.
RenderParams.java uses loose coupling to access the MetaDataPlugin, RenderManager.java uses loose coupling to detect and optionally use the PreviewPlugin, and the extensions.xml file imports the Renderers plugin, and defines MetadataPlugin as a required dependency.

See the extensions.xml file in STLTranslator plugin or the HelpPlugin for examples of exporting methods.

Hope this helps (and is not too verbose) :-)

Cheers!
Nik