Writing Cross Tier Extensions

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.

Introscope plug-in jars

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.

Eclipse plug-ins

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.

Example

We want to add a new type viewer to the Investigator which displays the names of all of the customer's applications when a domain is selected. We will extend the EM with a new Isengard service that lists the applications for a domain. The new Workstation type viewer will call this service to get the list of applications. The service interface might look like this:
		
	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.

Overridding the classloader key

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.

Mixed Plugin Mechanisms

NOTE This section is subject to change pending the approval of the Agent OSGi extension.

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.