Important: This user guide is assumed to be used with TPTP 4.2
The Managed Agent Explorer is available as a Tech Preview in TPTP 4.2. It allows users to introspect and interact
with managed agents that represent resources instrumented for open standards management like WSDM or JMX
resources. It is possible to add new managed agents that represents managed resources that may be instrumented by
other means. This document provides the details on how the Managed Agent Explorer interacts with the Managed Agents and
how it can be extended to work with new types of Managed Agents.
1.1 Providing a Managed Resource Agent implementation
1.2 Providing a launch configuration for the new Managed Resource
1.3 Providing configuration pages for the launch configuration
1.4 More details on Managed Resource Agent implementation
The managed agent explorer provides a view to introspect and interact with manageable resources instrumented for WSDM and JMX. It is possible to provide plugins that will enable the managed agent explorer to work with other protocols as well as long as the custom command contract and the returned data structures are compliant with what the resource explorer expects. Following are the multiple steps involved in providing new plugins that contribute new management mechanisms to the managed agent abstraction.
- Provides the default implementations for some methods that all agents must support and hence establishes common behavior for all managed resource agents.
- Defines a number of abstract methods hence establishing the API contract for all managed agents. However these methods are protected and called only from the code that interprets custom commands. The actual interaction between the Managed Agent Explorer (workbench) and a managed agent takes place over custom commands.
- Provides serialization and deserialization of custom command payload.
- Defines the set of command strings that can be sent in a custom command.
To contribute a new type of managed resource agent , simply extend this class and provide implementations for the abstract methods.
You must also provide a contribution through the org.eclipse.tptp.monitoring.managedagent.managedResourceType extension point. An example follows:
<extension point="org.eclipse.tptp.monitoring.managedagent.managedResourceType">
<MRType
class="org.eclipse.tptp.monitoring.managedagent.wsdm.internal.agents.WSDMAgent"
type="WSDM"/>
</extension>
The resource type you are contributing is identified by the type attribute of the MRType element. As seen below this managed resource type definition will be matched with the agentType attribute provided within the launch configuration.
Please see further below for more details on the actual implementation of the resource agent.
In addition to the above extension, your new managed resource plugin must also define a data collector mechanism and associate it with a launch configuration./ An example follows:
<extension point="org.eclipse.hyades.trace.ui.dataCollectionMechanism">
<collector
id = "org.eclipse.tptp.monitoring.managedagent.datacollector.WSDMIntrospector"
name = "WSDM resource"
description = "A data collector to introspect managed agents like WSDM agents and JMX agents"
icon = "icons/mr.gif">
</collector>
</extension>
<extension point="org.eclipse.hyades.trace.ui.launchConfigMechanismAssociator">
<association launchConfigID = "org.eclipse.tptp.monitoring.managedagent.launch.common">
<mechanism mechanismID = "org.eclipse.tptp.monitoring.managedagent.datacollector.WSDMIntrospector">
<configuration
launchDelegate = "org.eclipse.tptp.monitoring.managedagent.ui.launch.internal.common.ManagedAgentDelegate"
configurationId = "org.eclipse.tptp.managedagent.datacollector.ManagedAgentConfiguration">
</configuration>
</mechanism>
</association>
</extension>
The important part of the first contribution definition is the id attribute of the collector. It is used to correlate this managed resource agent contribution with a launch configuration.
The second contribution definition above specifies the launch configuration to be used for this managed agent. The id attribute of the collectorelement in the first contribution is specified as the mechanismID attribute of the mechanism element in the second contribution. Also note that your new managed agent type will reuse the provided ManagedAgentDelegate .i.e. all contributed managed agent types can use the same launch delegate for the abstract managed agent. Hence the other fields in the second contribution can be reused as is.
Even though you will be reusing the managed agent delegate and launch configuration provided by the abstract managed agent, you will need to provide the configuration pages because you will probably have configuration that is specific to your managed agent type. The following example plugin.xml fragment shows how this can be done:
<extension point = "org.eclipse.hyades.trace.ui.configuration">
<configuration
id = "org.eclipse.tptp.managedagent.datacollector.ManagedAgentConfiguration"
class = "org.eclipse.tptp.monitoring.managedagent.datacollector.internal.wsdm.ManagedAgentConf"
dialogTitle = "WSDM Managed Agent Configuration">
</configuration>
</extension>
The class you specify in the above contribution must implement org.eclipse.tptp.trace.ui.provisional.launcher.IConfiguration which is the standard mechanism through which any TPTP agent provides configuration pages. Ultimately you must populate a provided ILaunchConfigurationWorkingCopy with the attributes and values specified through these configuration pages.
In addition, you must add an attribute with name specified by the ManagedAgentFactory.MANAGED_AGENT_TYPE static variable and provide the same string that you provided for the type attribute in the MRType element in the contribution of your Managed resource agent type. The standard Managed Agent launch delegate will use this to instantiate your contributed managed agent.
All communication and data exchange between the explorer and the agent happens over custom commands. To abstract the usage of custom commands and to take care of fundamental issues like serialization and command synchronization, helper classes are provided. Primary among them are the ManagedAgentCommandHelper, CommandSerializer and CommandWrapper classes. The explorer uses the ManagedAgentCommandHelper, an instance of which is created for every agent instance, to interact with the agent. The contract between the managed resource agent and the explorer is defined by the custom commands to be implemented and the data structures returned. The following section explains the two in detail.
The following are the custom commands to be implemented by any managed resource agent. Note that the ManagedResourceAgent class provides a basic implementation for deserializing and serializing custom commands and interaction with the agent framework – all you need to do is extend this class and provide method implementations for the abstract methods many of which represent the actual custom commands being invoked. It is not necessary for you to be proficient in the custom command framework or actual serialization operations. Each custom command has a corresponding abstract method in the ManagedResourceAgent class that you must implement to provide the function described below.
|
Custom Command |
Abstract method to be implemented |
|
INIT_COMMAND |
boolean init() |
|
LOAD_META_DATA_COMMAND |
void loadMetaData() |
|
GET_PROPS_META_DATA_COMMAND |
Hashtable getPropertiesMetaData() |
|
GET_OPS_META_DATA_COMMAND |
Hashtable getOperationsMetaData() |
|
GET_COMMAND |
Object[] getResourceProperty(String propertyName) |
|
GET_MULTIPLE_COMMAND |
Hashtable getMultipleResourceProperty(String[] propNames) |
|
SET_COMMAND |
void setResourceProperty(String propName, Object[] values) |
|
INVOKE_OPERATION_COMMAND |
Object invokeOperation(String methodName, Object[] params) |
|
GET_MEMBERS_COMMAND |
Hashtable getMembers() |
- At this time, you can only provide simple data types or Hashtables with simple data types for keys and values or Hashtables containing other Hashtables with simple data types for key and values as parameters and return types. This is because the CommandSerializer only supports these types and hence only such types can be serialized to be sent across custom commands. As such this is not an issue because ultimately the Managed Agent Explorer converts everything to strings for display so your ManagedResourceAgent subclass can do the conversion to string and return strings or Hashtables with strings in them. However in the next revision, we expect the explorer to do validation based on type and metadata.
- All methods to be implemented throw exceptions. Method dispatching is done by the execute method in ManagedResourceAgent in response to receiving a custom command. When an exception is thrown by your implementation of any method, that is propogated across the custom command framework and an exception is raised on the ManagedAgentCommandHelper which is what the explorer uses to communicate with your managed resource.
The standard agent commands are implemented by the Managed Resource Agent and it is typically not necessary to override the default implementations. However the getName() method is usually overridden. The Managed Agent Explorer calls this method (through the helper) only after it has passed the configuration. Typically managed agent providers will use this configuration to return an unique name for the agent. Note that only unique managed agents will be displayed in the Profiling Monitors view so it is important to derive unique names from the passed in configuration.
Also setConfiguration and getConfiguration are often called on managed agents. The default implementations in ManagedResourceAgent will usually suffice and they also save a local copy. However you may wish to override these implementations and process the configuration.
INIT_COMMAND is the first custom command to be issued to the Managed agent implementation. You can perform any initialization action here. The return is a boolean value that indicates whether the agent is successfully initialized. If the agent is not initialized successfully you must invoke the provided setActive() method with a false parameter to ensure that no more commands are issued to the agent.
The LOAD_META_DATA command is issued by the explorer to signal the managed resource agent that it should collect the metadata. The actual metadata is not returned in this operation. Typically metadata includes names and types of properties, names of operations, names and types of the parameters to the operations and names and types of the returned values from the operations. Note that the managed agent explorer is very generic and requires such metadata to display the properties and operations of the managed resource and allow an user to manipulate the resource. You can choose to discover metadata by multiple means including object reflection in some cases and metadata exchange mechanisms in others. You can hold the metadata in any data structure; however they must be returned in the form described in the following 2 methods. Note that every time one of the following 2 calls is issued, a LOAD_META_DATA command will be issued before them.
The GET_PROPS_META_DATA command is issued only after the LOAD_META_DATA command has been issued. The explorer uses this custom command to get details about the properties exposed by this resource to populate its internal models. The returned data structure is described below,
- A Hashtable containing two entries with keys specified by the strings corresponding to the static variables PROPERTY_NAMES and PROPERTY_TYPES in the ManagedResourceAgent class; each of these entries is a Hashtable
- The first hashtable entry containing an arraylist of strings corresponding to the names of the properties exposed by the resource
- The second hashtable entry containing an arraylist of strings corresponding to the types of properties exposed by the resource and in the same order as the previous arraylist.
The GET_OPS_META_DATA command is also issued only after a LOAD_META_DATA command has been issued. This method also returns a hashtable as the previous one however the data structure is slightly different.
- A hashtable containing 4 entries with keys specified by strings corresponding to the static variables PARAM_NAMES, PARAM_TYPES, RETURN_NAMES, RETURN_TYPES in the ManagedResourceAgent class
- The first entry must be a Hashtable that has an entry for each operation keyed by a string with the operation name. Each entry’s value is an arraylist of strings with the names of the parameters for that particular operation in the same order as the operation’s signature.
- The second entry must be a Hashtable that has an entry for each operation keyed by a string with the operation name. Each entry’s value is an arraylist of strings with the types of the parameters for that particular operation in the same order as the operation’s signature.
- The third entry is a Hashtable that has an entry for each operation keyed by a string with the operation name. Each entry’s value is a string that has a symbolic name for the return type of that particular operation.
- The last entry is a Hashtable that has an entry for each operation keyed by a string with the operation name. Each entry’s value is a string that has the return type of that particular operation.
The GET_COMMAND is used for retrieving property values. The String parameter specifies the property name. The method must return an Object array with all the returned values. If you have only one value to return, you can return a single object array.
The GET_MULTIPLE_COMMAND is used for retrieving multiple property values. You can delegate the actual individual property value retrieval to the getResourceProperty method. The returned hashtable must contain strings that hold the passed in property names as keys and an object array as the value for each key. The object array will hold the property values. If you have only value for each property you can use a single entry object array.
SET_COMMAND is used for setting the value of a property. The first parameter is a identifies the property name and the second parameter is an object array of values. Note that the actual implementation of the set operation may differ according to the behavior of your managed resource. Some managed resources will insert new values while others will replace existing ones. Another option is to replace values of properties already present and insert values if the property is currently not present on the resource (effectively changing the member variables of the resource and hence its “schema”).
INVOKE_OPERATION_COMMAND is used for invoking operations on the resource type which are specific to only that resource type and hence have not been abstracted out into separate custom commands. The first parameter is the name of the operation to invoke on the resource and the second parameter is an object array of arguments to be passed to the operation being invoked. The return is an object that represents the value returned by the invoked operation.
GET_MEMBERS is a special command that applies only to managed resources that can be organized hierarchically. Each member of such a managed resource is a managed resource of the same type as well. The corresponding method implementation must return a Hashtable with an entry for each contained or referenced managed resource instance. The key for each entry is a unique connection string and typically you can use the same value that you return for getName() as explained above. The value against each key is Hashtable that contains the properties needed for launching an agent to talk to the particular child member represented by that entry. This Hashtable must contain:
- An entry whose key is the string ManagedAgentType and whose value is the type of managed resource agent that must be used to talk to this member. This is typically the same as the type of agent that was used to talk to this group in the first place. For example if you providing an implementation for a JMX resource type then this value will be JMX.
- Other entries providing the same information that would be entered by an user in the launch configuration tabs if he were to manually connect to this child resource. For example in the case of WSDM agents, the typical launch configuration results in one configuration parameter epr which is a string. So, each child member will have such a Hashtable with that one entry.
- A entry with key displayString that determines what will be displayed in the Managed Agent Explorer. Note that this could be different from what will be shown in the Profiling Monitors view when an agent is launched for this child (that depends on what getName() will return when that agent is launched) but typically one would keep these the same.
Note that explorer will typically provide a context menu action to automatically launch an agent to introspect and interact with such a contained managed resource. This means that whatever connection information is returned must be useful enough for the delegate to instanstiate a managed agent of the same type. Note that contained managed resources must be of the same type as the containing managed resource .i.e. the same type of agent will be used to introspect and interact with the contained managed resources.
Authors: Balan Subramanian, Mark Weitzel