PluginMBean

Java Class - Interface

As noted earlier, each plugin is an MBean and must implement the PluginMBean interface. This interface specifies the contract required to implement a plugin while ensuring its use as an MBean. This class can be extended into new interface hierarchies to provide additional functionality.

Implementing this class allows a plugin to expose attributes and operations that can be executed from a JMX console.

This class contains the primary APIs to implement MBean attributes and operations.

AbstractPlugin

Java Class - Abstract

An abstract class that wraps much of the complexity of implementing the PluginMBean interface for a plugin. This class provides concrete implementations of methods that can be used via inheritance from classes which extend it.

This is the base parent class for all plugins and any custom plugin should extend this class either directly or hierarchically.

SelfAwareMBean

Java Class - Abstract

Each plugin is a SelfAwareMBean, that is, each plugin is a standard MBean (as previously described) that knows its own MBean ObjectName allowing it to maintain a single register of itself in the MBean registry.

All custom plugins should implement a call to super() in the plugin constructor (Sample Codee) to ensure that each plugin is registered as a SelfAwareMBean. The AbstractPlugin base class implements a method call to register the plugin as a SelfAwareMBean.

Anecdotally, all plugins should be SelfAwareMBeans as each plugin should eventually inherit from the base class AbstractPlugin which extends SelfAwareMBean.

com.ptc.customersupport.plugins

Java Package

This Java package contains all the PTC provide plugin implementations. This package contains abstract source files for making the implementation of numerous plugins easier by providing default functionality for many required methods.

Notably, the package includes the following abstract Java classes:

AbstractMultipleFilePlugin

AbstractQMLPlugin

AbstractReportingPlugin

AbstractSQLPlugin

AbstactWinDUPlugin

AbstractXconfPlugin

GatherFilePlugin

GatherFolderPlugin

GatherLogsPlugin

GatherEveryLogPlugin

The functionality of these plugins can be used directly through Java inheritance to provide easier plugin implementations for common plugin functionality types.

AbstractMultipleFilePlugin

Java Class - Abstract

This class wraps common functionality needed for a plugin to gather a list of files.

AbstractQMLPlugin

Java Class - Abstract

This class wraps common functionality needed for a plugin to execute a QML (Query Markup Language) files/scripts. These scripts usually contain a .qml file extension.

AbstractReportingPlugin

Java Class - Abstract

This class wraps common functionality needed for a plugin to execute plugins against Windchill Business Reporting.

AbstractSQLPlugin

Java Class - Abstract

This class wraps common functionality needed for a plugin to execute a SQL (Structured Query Language) files/scripts.

AbstractWinDUPlugin

Java Class – Abstract

This class wraps common functionality needed for a plugin to execute a WinDU (Windchill Diagnostic Utilitiy) task.

AbstractXconfPlugin

Java Class – Abstract

This class wraps common functionality needed for a plugin to recursively identify referenced xconf files from a parent xconf file.

GatherFilePlugin

Java Class - Abstract

This class wraps common functionality needed for a plugin to gather a single file.

GatherFolderPlugin

Java Class – Abstract

This class wraps common functionality needed for a plugin to gather a parent and all child directories.

GatherLogsPlugin

Java Class - Abstract

This class wraps common functionality needed for a plugin to gather a directory of log files. This class differs slightly from the similar GatherFolderPlugin in that it operates over a specified date range for a file, in particular, the file modification time.

GatherEveryLogPlugin

Java Class - Abstract

This class wraps common functionality needed for a plugin to gather a directory of log files. This class differs slightly from the similar GatherLogsPlugin in that it ignores date range for a file, in particular, the file modification time. As such, it operates over every log file.

CollectorMBean

Java Class - Interface

A Java MBean interface that specifies the contract for how a plugin collects its targeted data. This MBean does not need to be implemented directly by a plugin as AbstractPlugin takes care of the implementation details.

Collector

Java Class

The concrete implementation class for the CollectorMBean interface. This is the class that all plugins essentially rely on to do their file collection.

collect(…)

Java Method

The two collect(…) methods are part of the PluginMBean interface and must be implemented by all plugins (as all plugins must implement the PluginMBean interface).

These methods specify the API’s necessary to interact with the Collector class and ultimately carry out the work of the plugin.

In general cases, the AbstractPlugin and other Abstract classes (see above) in the plugin hierarchy provide default implementations that can be relied upon for the collect(…) methods. Specifically, the collectData(…) method of AbstractPlugin.java can often simply be called by the collect(…) methods. However, more advanced plugins that handle very specific needs may require these methods to be overridden and implemented directly. Generally, these cases are rare and only occur when a plugin isn’t simply collecting files but rather needs to run some Java process or invoke some separate operation that does processing which results in a file that then needs to be collected.

There are plugins in the com.ptc.customer

support.plugin.* packages that do this which can be examined for examples, specifically, see MBeanDumpPlugin.java, WDSPlugin.java and AbstractWinduPlugin.java.

Note that there are two collect(…) methods that must be implemented as there are essentially two ways the PluginMBean interfaces specifies a user can collect data. One API requires a callNumber parameter and the other requires a topicIdentifier. Each of these parameters is used to distinguish locations that information is collected to.

This method requires a specific Map return value. For greater detail regarding the return value and this method see Abstracting the Plugin in Customization Points

collectData(…)

Java Method

The collectData(…) method of AbstractPlugin.java wraps much of the complexity of implementing the collect(…) methods of the PluginMBean interface. This method sets up the broadcast message to marshaled to each server as determined by the plugin. It also correctly builds up the return Map that is expected. Since this method hides the complexity of using the collection framework directly, it can often be relied upon by the collect(…) methods. One can simply call this method with the appropriate parameter values in most plugin cases.

This method requires a specific Map return value. For greater detail regarding the return value and this method see Abstracting the Plugin in Customization Points

PluginType

Java Class

This is a Java enumerated type class. Each plugin must specify one of the enumerated types of PluginType when initializing itself so that the Collector class knows what do with and where to place the collected information on the file system.

PluginUtilities

Java Class

This is a Java class that provides utility methods that may be useful for creating more advanced plugins that do not rely on default behavior of the collect(…) methods. Of specific interest is the getReturnMap(boolean, String, String) method that will build up the Map return value that is expected by the collect(…) methods. This will assist in simplifying the implementation of advanced plugins which implement collect(…) methods with specific behavior.

PluginPropertyUtils

Java Class

This is a Java class that provides utility methods for property information that may be useful for creating more advanced plugins. This class provides methods that allow a user to obtain xconf managed property value information as well as a means to resolve tokenized xconf paths into fully qualified canonical paths.

*Resource

Java Classes

Each plugins strings should be localized so that they can be viewed in various locales. The com.ptc.customersupport.mbeans.plugin* packages contain resource classes. These resource Java classes maintain strings that can be localized and used in Java source code.

A plugin can make use of these or new resource files to provide localized strings.

<file_name>.jar

Java Jar File

This is a standard Java .jar file and can be named anything. The .jar file is the standard way to deploy a custom plugin in the System Configuration Collector for use.

The .jar should contain the compiled .class files for the plugin and any helper Java classes along with the PluginMBean services file (see below). The .jar file must maintain the directory structure of the package for the .class files and the service file.

For more information on Java Jar files specification see Additional Resources.

com.ptc.customersupport.mbeans.PluginMBean

Java Jar Service File

This is a services file contained in a Java .jar file that allows the System Configuration Collectors Java class loader to know if a new plugin has been deployed. The file structure is rigid and must be maintained, otherwise, Java class loader issues will result and the plugin will not load nor be available for use. The .jar file must contain the file com.ptc.customersupport.mbeans.PluginMBean at location META-INF\services. The file contents must be of type:

<java source package>.<plugin class name> (without the brackets).

For more information on Java Service Provider Interface see Additional Resources