A plugin does not necessaryily need to implement the PluginMBean interface directly. Instead a new interface that extends the PluginMBean interface could be defined and implemented by the concrete plugin implementation. However, the new plugin interface is still required to inherit the PluginMBean interface.

For example:

publicinterface XYZPluginMBean extends PluginMBean {}

Here the XYZPluginMBean extends the PluginMBean. This interface can then further define any required methods or attributes that are to be exposed via MBean operations.

The concrete implementation would then be:

publicclassXYZPluginextends AbstractPlugin implements XYZPluginMBean {}

Similar to Extending the PluginMBean Interface section, a developer can rely on the numerous abstract classes detailed in Solution Elements, or any abstract class the developer defines to initialize plugin MBean values to defaults. As previously stated, the abstract classes wrap much of the complexity of plugin creation. In addition to relying on the abstract classes for plugin initialization a developer can also rely on the abstract implementations of the collect(…) methods.

AbstractPlugin.java API: public AbstractPlugin(final Class mbeanInterface) throws NotCompliantMBeanException

AbstractPlugin.java API: public AbstractPlugin(final Class mbeanInterface, final String displayName, final String mBeanName,

final String description, final String pluginVersion) throws NotCompliantMBeanException {

AbstractPlugin.java API: publicabstract Map<String, Object> collect(long callNumber, long maxAgeInDays, long minAgeInDays, String pathTimeStamp);

A developer is required to implement this method as it is Abstract. It is called by UI layers as an entry point to do the plugin work..

A developer can usually pass this methods parameters to the collectData(…) methods of AbstractPlugin.java. As previously discussed, the collectData(…) method handles the complexity of calling the collection framework.

A developer can implement the collect methods in a way that does not rely on collectData(…) or any of the Abstract classes parent collectXYZ(…) method implementations. In general, this is an exception however. Only advanced plugins that require specialized work, such as running a Java process that does some work to build a file to be collected, will probably avoid simply calling the parent collect(…) method implementations. Even in this situation, after the Java process has completed and generated its data, parent classes could still be relied on to do the actual collection. MBeanDumpPlugin.java and WDSPlugin.java are two plugins PTC provides that do additional work other than simply call the parent collection methods, these can be examined in greater detail for those wishing to build highly complex plugins.

Care must be taken when providing the return type of the collect(…) method. The collectData(…) method of AbstractPlugin.java wraps all the complexity of creating a valid return type that the plugin framework will correctly interpret. This is also why it is recommended to use the collectData(…) method in the collect(…) method implementation. Not doing so increases the complexity of the implementation of the collect(…) method greatly.

The Outer Map: Map <String, Object>

The String key must be the server process ID and hostname of the name the plugin executed on. For example, 5524@DSTUSYNSKI03D. While any String is valid, the plugin framework will report this to the user which will appear as meaningless data if it isn’t properly built.

The Object is actually an inner Map of type <String, String>.

The Inner Map: Map <String, String>

The inner Map should have four key entries, one for each String, “success”, “path”, “message”, “location”.

Each of these keys values must be another String that corresponds to the appropriate value for the key. The “success” keys value should be true or false and is the value that states whether the collection framework was successful in collecting the plugin data or not. The “path” keys value is generated by the collection framework and it denotes the last directory in the canonical path for which the plugin data is collected to for the particular server the plugin executed on. The “message” keys value is a String message that might accompany the plugin generated by the collection framework. This is likely a status message of why a plugin failed. The value null should be used if no message is to be reported. The “location” keys value is a String representing a partial path to where the collection framework collects the plugin data.

When not relying on the collectData(…) method of AbstractPlugin.java or other parent Abstract classes care must be taken to ensure the collect(…) methods return type adheres to this form such that it can be correctly processed by the plugin framework. If implementing a plugin and building the return Map<String, Object> directly examine the MBeanDump.java and WDSPlugin.java implementations for greater detail. Both of these classes do not rely on the Abstract classes or the collection framework directly and therefore build the correct return type in their collect(…) method implementations.

For the advanced plugin that requires the return Map to be built a developer can rely on the PluginUtilites.getReturnMap(…) method which is discussed further in this section.

AbstractPlugin.java API: publicabstract Map<String, Object> collect(String topicIdentifier, long maxAgeInDays, long minAgeInDays, String pathTimeStamp);

A developer is required to implement this method as it is Abstract. It is called by UI layers as an entry point to do the plugin work.

See the previous collect(…) method for detail on this methods usage.

AbstractPlugin.java API: public Map<String, Object> collectData(String srcPath, finallong callNumber,

finallong maxAgeInDays, finallong minAgeInDays, String pathTimeStamp) {

This is the method wraps the complexity of using the collection framework directly for collecting plugin data. Although not strictly required, it is recommended, that it be called by the collect(…) method implementations for a plugin. Often, calling this method in the collect(…) method and returning its value is all that is required of a collect(…) method implementation.

The return value of this method is the same return value as the collect(…) methods described above.

AbstractPlugin.java API: public Map<String, Object> collectData(String srcPath, final String topicIdentifier,

finallong maxAgeInDays, finallong minAgeInDays, String pathTimeStamp) {

See the previous collect(…) method for detail on this methods usage.

PluginUtilities.java API: publicstatic Map<String, Object>

getReturnMap(finalboolean success, final String path, final String message,

final String location) {

This method will build up a return value for use with the collect(…) method implementations provided correct values are passed into this method via it’s parameters. This method is a utility method that makes the creation of the collect(…) methods return value easier. Essentially, it wraps the creation of the return value freeing the implementor of the collect(…) method the need to create the outer and inner Maps. As each parameters description details, the parameters are used to generate the inner Map and the method implementation will handle generating the outer Map<String, Object>. The resulting return value is a Map<String, Object> where the Object is of type Map<String, String> that can then be used as the return type of a collect(…) method.

While each of these parameters aren’t strictly required, they should be considered as such, otherwise the methods return value Map<String, Object> will simply be incomplete. The inner Map will not contain the correct data required by the plugin framework for reporting on the plugin execution status.

Note that this method will only be useful as a utility for use when a developer does not rely on the collectData(…) implementation of AbstractPlugin.java or other Abstract collectXYZ(…) method implementations.