The Introscope platform has two mechanisms for extension - plug-in jar files and Eclipse plug-ins. The plug-in jar file mechanism is a proprietary extension mechanism available on all three tiers (agent, Enterprise Manager, Workstation) of the product. This extension mechanism has been deprecated on the EM and Workstation tiers in favor of the new Eclipse extension points that leverage the Eclipse extension point mechanism.
Products built on the Introscope platform that extend multiple tiers have special requirements related to class serialization. If two extensions on different tiers wish to serialize a class which is defined in the extensions they must register their classloader with Isengard. The way the classloader is registered differs based on the extension mechanism used.
Before the Introscope platform was moved to the Eclipse runtime the product implemented its own propriety extension mechanism very similar to Eclipse plug-ins. An extension was a jar file containing java classes with special entries in the MANIFEST file that defined the extension entry points. Here an example MANIFEST file:
com-wily-Extension-Classloader-Key: SDK-Examples com-wily-Extension-Name: Example Plugins - EM com-wily-Extension-Type: Introscope-EnterpriseManager com-wily-Extension-Version: 1 com-wily-Extension-Localized-Resource-List: com-wily-Extension-Plugins-List: agentsoverview com-wily-Extension-Plugin-agentsoverview-Name: Agents Overview API com-wily-Extension-Plugin-agentsoverview-Type: EMService com-wily-Extension-Plugin-agentsoverview-Version: 1 com-wily-Extension-Plugin-agentsoverview-Entry-Point-Class: com.wily.introscope.ext.server.agentsoverview.AgentsOverviewEMPlugin
This sample defines one Enterprise Manager plug-in named "agentsoverview" with an entry class "com.wily.introscope.ext.server.agentsoverview.AgentsOverviewEMPlugin". The classloader for this plug-in is registered with Isengard under the key "SDK-Examples". Here's the MANIFEST file for the Workstation extension that goes along with this EM extension:
com-wily-Extension-Classloader-Key: SDK-Examples com-wily-Extension-Name: Example Plugins - Workstation com-wily-Extension-Type: Introscope-Console com-wily-Extension-Version: 1 com-wily-Extension-depends-on: JGraph Library com-wily-Extension-Localized-Resource-List: com-wily-Extension-Plugins-List: agentsoverviewviewer com-wily-Extension-Plugin-agentsoverviewviewer-Name: Agents Overview Viewer com-wily-Extension-Plugin-agentsoverviewviewer-Type: ConsoleService com-wily-Extension-Plugin-agentsoverviewviewer-Version: 1 com-wily-Extension-Plugin-agentsoverviewviewer-Entry-Point-Class: com.wily.introscope.ext.workstation.typeviews.agentsoverview.AgentsOverviewViewerPlugin
This extension uses the same classloader key, "SDK-Examples", as its EM extension counterpart. When the EM extension serializes a class defined in the extension to the Workstation, Isengard writes the classloader key name along with the class information. When the Workstation deserializes this class, it will find the extension classloader that matches the given key name.
This is the primary extension mechanism of the Introscope Agent. This extension mechanism is still available in the Enterprise Manager and the Workstation, but it has been deprecated in favor of the new Eclipse extension point mechanism.
The new Introscope extension mechanism uses Eclipse plug-in extension points. Extensions are defined in a plug-in's plugin.xml file. Here's a sample snippet that defines a new type viewer:
<extension
point="com.wily.introscope.workstation.typeViewer">
<typeViewer class="example.helloworldtypeviewer.HelloWorldTypeViewer"/>
</extension>
There is a UI to define extensions (the plug-in xml does not need to be edited by hand).
Classes shared between two plug-ins should be broken into a separate "common" plug-in. The Workstation and EM plug-ins should both depend on this common plug-in and the common plug-in should be deployed on both tiers. That's it! The platform will automatically register the common bundle's classloader for Isengard serialization.
public interface IApplicationService extends IMessageService
{
Application[] getApplications(String domain) throws ConnectionException;
}
Since this interface will be used by both the EM and Workstation plug-ins it will be packaged in a common plug-in named com.wily.example.applications.common. This plug-in will also include the Application class. The com.wily.example.applications.em plug-in will depend on the common plug-in and implement the IApplicationService interface. The com.wily.example.applications.workstation plug-in will depend on the common plug-in and implement a new type viewer extension.
Whenever a class from the common plug-in is serialized by Isengard, the bundle symbolic id (com.wily.example.applications.common) will be passed along as the classloader key.
For example, after a call is made to getApplications and an array of Applications is about to be serialized, Isengard tries to find the classloader for this class. It will find the bundle classloader under the common plug-in's id, com.wily.example.applications.common. When the array is deserialized on the Workstation, Isengard looks for the classloader stored under the com.wily.example.applications.common key and uses it when deserializing the Applications.
Some extension writers may need to override the default classloader key name (the bundle symbolic name) in order to support older agent plug-ins. The com-wily-Extension-Classloader-Key manifest header is still supported, and if present it will be chosen as the classloader key name instead of the bundle name.
Many plug-ins are written for the EM and the Workstation tiers alone, and these should use the new Eclipse extension point mechanism. The agent tier, however, still relies on the old plug-in mechanism. When extending Introscope across the agent and EM tiers a similar approach as described above should be used. Create a common plug-in for the code that must be shared between the tiers. Create the EM extension as an Eclipse plug-in. Create the agent extension using the old plug-in mechanism and specify the common plug-in as a dependency in the agent plug-in's MANIFEST:
com-wily-Extension-depends-on: com.wily.example.agentexample.common
Both the agent plug-in and the common plug-in should be deployed in the agent's ext directory. The agent will read the MANIFEST of the common plug-in and treat it as a plug-in library.
Remember that the code in the common project typically must be Java 1.3 compliant. If that is not the case, the JVM requirement for the plug-in should be explicitly stated in the extension's documentation.