com.ibm.are.plugin
Class BasePlugin

java.lang.Object
  extended by com.ibm.are.plugin.BasePlugin
All Implemented Interfaces:
com.ibm.are.core.Element, Plugin, PluginReporting, Reporting, StatusReporting, java.lang.Runnable

public abstract class BasePlugin
extends java.lang.Object
implements java.lang.Runnable, Plugin, PluginReporting

The BasePlugin class is an abstract base class that implements much of the behavior required for a Plugin in the Application Runtime Expert. This class provides the following set of implemented features available for use by any sub-class:

Although this class implements the PluginReporting interface, the actual implementation is nothing more than delegating each reporting event to registered reporters. By default there are three registered reporters: PlainTextReporter, XmlReporter, and SummaryReporter. Methods are provided to replace the default reporters or add additional reporters.

Version:
1.0
Author:
IBM

Nested Class Summary
 class BasePlugin.ReporterCollection
           
 
Field Summary
static java.lang.String COPYRIGHT
          Copyright for class bytecode
protected  java.util.logging.Logger log
          The logger associated with the plugin
protected  java.io.PrintWriter out
          The output writer for the plugin
protected  PluginData pluginData
          Data associated with the plugin.
protected  Version pluginVersion
          The plugin's version
protected  BasePlugin.ReporterCollection reporter
          Collection of reporters used to format and generate reports for the plugin
protected  ResultInfo result
          The result value of running the plugin
 
Fields inherited from interface com.ibm.are.report.Reporting
FORMAT_BINARY, FORMAT_HTML, FORMAT_PLAIN_TEXT, FORMAT_SERIALIZED, FORMAT_USER_DEFINED, FORMAT_XML, LEVEL_ERROR, LEVEL_INFO, LEVEL_NONE, LEVEL_WARNING, MAX_REPORT_DEPTH, MIN_REPORT_DEPTH
 
Constructor Summary
protected BasePlugin()
          Constructs and initializes fields for a new plugin.
 
Method Summary
 void addReporter(ReporterReporting reporter)
          Add a reporter to this group
 com.ibm.are.core.ElementData getElementData()
          
protected  java.lang.String getInput(java.lang.String prompt)
          Retrieves an input value from standard input.
 java.util.logging.Logger getLogger()
          Retrieves the logger associated with the plugin
 PluginData getPluginData()
          Retrieves the plugin data associated with this plugin.
 PluginReporting getReporter()
          Retrieves the reporter for the plugin
 java.io.PrintWriter getStandardOut()
          Retrieves the standard output writer for the plugin.
 java.io.InputStream getTemplateResource(java.lang.String resName)
          Answers a stream on a resource found by looking up 'resName' in the template.
 Version getVersion()
          
 void init(java.util.List initArgs)
          Any initialization that the plugin needs to do prior to running can be done in this method.
protected  boolean initOutput(java.lang.String outputFileName)
          Initializes the plugin's out stream to the given file name.
protected abstract  Version initPluginVersion()
          Used to initialize the plugin's pluginVersion field
 void removeAllReporters()
          Removes all reporters
 void removeReporter(java.lang.String className)
          Removes all reporters whose class name matches the given class name
 void report(java.lang.String msg, int depth)
          Report a message at the given level in the reporting hierarchy.
 ProblemContext report(java.lang.String msg, java.lang.String errorLevel)
          Report a message at the given error level during the runtime processing.
 ProblemContext report(java.lang.String msg, java.lang.String errorLevel, com.ibm.are.autofix.FixAction fixAction)
          Report a message at the given error level during the runtime processing, with info about how to fix the problem.
 ProblemContext reportError(java.lang.String msg)
          Report an error message during the runtime processing.
 ProblemContext reportError(java.lang.String msg, com.ibm.are.autofix.FixAction fixAction)
          Report an error message during the runtime processing, with info about how to fix the problem.
 void reportFinish(com.ibm.are.core.Element elem, ResultInfo result)
          Reports the result of the runtime processing for a plugin.
 ProblemContext reportInfo(java.lang.String msg)
          Report an informational message during the runtime processing.
 ProblemContext reportInfo(java.lang.String msg, com.ibm.are.autofix.FixAction fixAction)
          Report an informational message during the runtime processing, with info about how to fix the problem.
 void reportStart(com.ibm.are.core.Element elem)
          Reports the start of a plugin
 void reportStatistic(java.lang.String description, java.lang.Object value, int depth)
          Reports an interesting or very important statistic.
 void reportStep(java.lang.String msg)
          Reports a new step in the runtime processing.
 void reportStepDetail(java.lang.String msg)
          Reports a new step detail in the runtime processing.
 void reportSubStep(java.lang.String msg)
          Reports a new sub step in the runtime processing.
 void reportSubStepDetail(java.lang.String msg)
          Reports a new sub step detail in the runtime processing.
 ProblemContext reportWarning(java.lang.String msg)
          Report a warning message during the runtime processing.
 ProblemContext reportWarning(java.lang.String msg, com.ibm.are.autofix.FixAction fixAction)
          Report a warning message during the runtime processing, with info about how to fix the problem.
 ResultInfo result()
          Retrieves the result of the plugin being run.
 void run()
          This method is used to bookend the real implementation of the plugin, the runImpl() method.
protected abstract  ResultInfo runImpl()
          The implementation of the plugin.
 void setElementData(com.ibm.are.core.ElementData newData)
          
 void setLogger(java.util.logging.Logger appLogger)
          Sets the logger to be used for logging events
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.ibm.are.core.Element
getCommonName, getDescription
 

Field Detail

COPYRIGHT

public static final java.lang.String COPYRIGHT
Copyright for class bytecode

See Also:
Constant Field Values

out

protected java.io.PrintWriter out
The output writer for the plugin


log

protected java.util.logging.Logger log
The logger associated with the plugin


pluginVersion

protected Version pluginVersion
The plugin's version


pluginData

protected PluginData pluginData
Data associated with the plugin. This data is typically initialized by Application Runtime Expert and available for use as soon as the plugin's init() method is invoked.


result

protected ResultInfo result
The result value of running the plugin


reporter

protected BasePlugin.ReporterCollection reporter
Collection of reporters used to format and generate reports for the plugin

Constructor Detail

BasePlugin

protected BasePlugin()
Constructs and initializes fields for a new plugin. The plugin's pluginVersion is set in the constructor.

Method Detail

init

public void init(java.util.List initArgs)
Any initialization that the plugin needs to do prior to running can be done in this method. The base class does implement this method, so it should be invoked even if overridden by a subclass.

Specified by:
init in interface Plugin
Parameters:
initArgs - Initialization arguments. Currently the core does not pass any arguments upon initialization, so this list will always be empty.

result

public ResultInfo result()
Retrieves the result of the plugin being run. The type of result returned by a plugin is implementation dependent.

Specified by:
result in interface Plugin
Returns:
The default implementation is to return a Boolean object whose value is true.

getElementData

public com.ibm.are.core.ElementData getElementData()

Specified by:
getElementData in interface com.ibm.are.core.Element

setElementData

public void setElementData(com.ibm.are.core.ElementData newData)

Specified by:
setElementData in interface com.ibm.are.core.Element

getReporter

public final PluginReporting getReporter()
Retrieves the reporter for the plugin

Specified by:
getReporter in interface Plugin
Returns:
The reporter
See Also:
PluginReporting

getVersion

public Version getVersion()

Specified by:
getVersion in interface com.ibm.are.core.Element

getPluginData

public PluginData getPluginData()
Retrieves the plugin data associated with this plugin.

Returns:
The plugin data
See Also:
PluginData

setLogger

public void setLogger(java.util.logging.Logger appLogger)
Sets the logger to be used for logging events

Parameters:
appLogger - The logger to be used

getLogger

public java.util.logging.Logger getLogger()
Retrieves the logger associated with the plugin

Specified by:
getLogger in interface Plugin
Returns:
The logger

getStandardOut

public java.io.PrintWriter getStandardOut()
Retrieves the standard output writer for the plugin. This writer is typically mapped to standard output, aka the System.out output stream. But this is not always the case. Thus, plugin authors should always write to the standard output writer provided by this method rather than writing directly to System.out.

Specified by:
getStandardOut in interface Plugin
Returns:
The standard output writer

reportInfo

public final ProblemContext reportInfo(java.lang.String msg)
Report an informational message during the runtime processing.

Specified by:
reportInfo in interface PluginReporting
Parameters:
msg - The message to print
Returns:
A context for the problem being reported. This context can be used to report additional details about the problem.

reportInfo

public final ProblemContext reportInfo(java.lang.String msg,
                                       com.ibm.are.autofix.FixAction fixAction)
Report an informational message during the runtime processing, with info about how to fix the problem.

Specified by:
reportInfo in interface PluginReporting
Parameters:
msg - The message to print
fixAction - The info about how to fix the problem.
Returns:
A context for the problem being reported. This context can be used to report additional details about the problem.

reportWarning

public final ProblemContext reportWarning(java.lang.String msg)
Report a warning message during the runtime processing.

Specified by:
reportWarning in interface PluginReporting
Parameters:
msg - The message to print
Returns:
A context for the problem being reported. This context can be used to report additional details about the problem.

reportWarning

public final ProblemContext reportWarning(java.lang.String msg,
                                          com.ibm.are.autofix.FixAction fixAction)
Report a warning message during the runtime processing, with info about how to fix the problem.

Specified by:
reportWarning in interface PluginReporting
Parameters:
msg - The message to print
fixAction - The info about how to fix the problem.
Returns:
A context for the problem being reported. This context can be used to report additional details about the problem.

reportError

public final ProblemContext reportError(java.lang.String msg)
Report an error message during the runtime processing.

Specified by:
reportError in interface PluginReporting
Parameters:
msg - The message to print
Returns:
A context for the problem being reported. This context can be used to report additional details about the problem.

reportError

public final ProblemContext reportError(java.lang.String msg,
                                        com.ibm.are.autofix.FixAction fixAction)
Report an error message during the runtime processing, with info about how to fix the problem.

Specified by:
reportError in interface PluginReporting
Parameters:
msg - The message to print
fixAction - The info about how to fix the problem.
Returns:
A context for the problem being reported. This context can be used to report additional details about the problem.

report

public final ProblemContext report(java.lang.String msg,
                                   java.lang.String errorLevel,
                                   com.ibm.are.autofix.FixAction fixAction)
Report a message at the given error level during the runtime processing, with info about how to fix the problem.

Specified by:
report in interface PluginReporting
Parameters:
msg - The message to print
errorLevel - The error level to use when reporting
fixAction - The info about how to fix the problem.
Returns:
A context for the problem being reported. This context can be used to report additional details about the problem.

reportStatistic

public final void reportStatistic(java.lang.String description,
                                  java.lang.Object value,
                                  int depth)
Reports an interesting or very important statistic.

Specified by:
reportStatistic in interface StatusReporting
Parameters:
description - A description of the statistic being reported
value - The (statistic) value to report
depth - The depth in the status reporting hierarchy where the statistic will be reported

reportStep

public final void reportStep(java.lang.String msg)
Reports a new step in the runtime processing. A step is the topmost node in the status reporting hierarchy.

Specified by:
reportStep in interface StatusReporting
Parameters:
msg - The message to report

reportStepDetail

public final void reportStepDetail(java.lang.String msg)
Reports a new step detail in the runtime processing. A 'step detail' is the direct child of a 'step' in the reporting status hierarchy.

Specified by:
reportStepDetail in interface StatusReporting
Parameters:
msg - The message to report

reportSubStep

public final void reportSubStep(java.lang.String msg)
Reports a new sub step in the runtime processing. A 'sub step' is the direct child of a 'step detail' in the reporting status hierarchy.

Specified by:
reportSubStep in interface StatusReporting
Parameters:
msg - The message to report

reportSubStepDetail

public final void reportSubStepDetail(java.lang.String msg)
Reports a new sub step detail in the runtime processing. A 'sub step detail' is the direct child of a 'sub step' in the reporting status hierarchy.

Specified by:
reportSubStepDetail in interface StatusReporting
Parameters:
msg - The message to report

addReporter

public void addReporter(ReporterReporting reporter)
Add a reporter to this group

Parameters:
reporter - The reporter to be added

removeReporter

public void removeReporter(java.lang.String className)
Removes all reporters whose class name matches the given class name

Parameters:
className - The package and class name of the reporter to remove

removeAllReporters

public void removeAllReporters()
Removes all reporters


report

public final ProblemContext report(java.lang.String msg,
                                   java.lang.String errorLevel)
Report a message at the given error level during the runtime processing.

Specified by:
report in interface PluginReporting
Parameters:
msg - The message to print
errorLevel - The error level to use when reporting
Returns:
A context for the problem being reported. This context can be used to report additional details about the problem.

report

public final void report(java.lang.String msg,
                         int depth)
Report a message at the given level in the reporting hierarchy.

Specified by:
report in interface StatusReporting
Parameters:
msg - The message to print
depth - The level within the reporting hierarchy. If this parameter were set to 1 it would be equivalent to invoking the StatusReporting.reportStep(String) method. The valid value ranges from MIN_REPORT_DEPTH (include) to MAN_REPORT_DEPTH (include).

reportStart

public final void reportStart(com.ibm.are.core.Element elem)
Reports the start of a plugin

Specified by:
reportStart in interface StatusReporting
Parameters:
elem - The plugin that is starting

reportFinish

public final void reportFinish(com.ibm.are.core.Element elem,
                               ResultInfo result)
Reports the result of the runtime processing for a plugin.

Specified by:
reportFinish in interface StatusReporting
result - The result

run

public final void run()
This method is used to bookend the real implementation of the plugin, the runImpl() method. By bookending the actual implementation of the plugin, this method provides the base class a way to perform standard "pre" and "post" run operations for every plugin, thus freeing plugin developers from having to perform a set of standardized tasks at the beginning and end of their plugins.

Specified by:
run in interface Plugin
Specified by:
run in interface java.lang.Runnable

initPluginVersion

protected abstract Version initPluginVersion()
Used to initialize the plugin's pluginVersion field

Returns:
The current version of the plugin

runImpl

protected abstract ResultInfo runImpl()
The implementation of the plugin. This method is invoked by the run() method. Subclasses put their implementation of the plugin in this method.

Returns:
The result of the plugin's runtime processing. Typically the result is nothing more than a boolean indicating success or failure, but the result is not restricted to just a boolean.

getInput

protected java.lang.String getInput(java.lang.String prompt)
Retrieves an input value from standard input. This is a convenience method that is typically only used by plugins that need to get input from the user via the console.

Parameters:
prompt - The message to display when prompting for input
Returns:
The input value

initOutput

protected boolean initOutput(java.lang.String outputFileName)
Initializes the plugin's out stream to the given file name.

Parameters:
outputFileName - The name of the output file. If the input file name is null or equal to "stdout" the output stream is initialized to standard out.
Returns:
true if the output stream needs to be closed once it is no longer needed, false if it should not be closed.

getTemplateResource

public java.io.InputStream getTemplateResource(java.lang.String resName)
Answers a stream on a resource found by looking up 'resName' in the template. If the resource cannot be found, null is returned.

Note that this method is based on the class loader of this (BasePlugin) class. Normally it's the default class loader and resource out side of the template jar can also be found if a resource with the same name exists in any jar listed in the classpath. However this method is provided as a helper method intended for easy retrieval of resource within the same template which contains the caller plugin.

Example:

InputStream is = myPlugin.getTemplateResource("xml/myConfig.xml");

Parameters:
resName - String the name of the resource to find.
Returns:
InputStream a stream on the resource or null if the resource cannot be found
See Also:
Class.getResourceAsStream(String resName)