com.sun.javatest.report
Class CustomReport

java.lang.Object
  extended by com.sun.javatest.report.CustomReport

public abstract class CustomReport
extends java.lang.Object

API to specify a customized report type for the Test Manager.


Nested Class Summary
static class CustomReport.ReportConfigPanel
          Configuration panel for a report.
static class CustomReport.ReportEnviroment
          Specified environment and settings for report generation.
 class CustomReport.ReportException
          The class ReportException indicates an error during report creation.
 
Constructor Summary
CustomReport()
           
 
Method Summary
abstract  java.io.File createReport(java.io.File rootDir)
          Create a report within the context of a GUI.
abstract  java.io.File createReport(java.lang.String args, java.io.File rootDir, InterviewParameters ip, TestFilter filter)
          Write a report without the context of a GUI.
 void dispose()
          Dispose of any data or components which this class may be holding references to.
abstract  java.lang.String getDescription()
          Get a longer description about the purpose of this report type.
abstract  java.lang.String getName()
          Get a short name for this report type.
 CustomReport.ReportConfigPanel[] getOptionPanes()
          Get report options panes.
 CustomReport.ReportEnviroment getReportEnviroment()
           
abstract  java.lang.String getReportId()
          Get a short internal name for this report type.
 java.io.InputStream getXmlReport()
          Request the content of the standard XML report from the harness.
 boolean needsXmlReport()
          Will this report need the standard XML data report if it is run.
 void setEnviroment(CustomReport.ReportEnviroment envir)
           
abstract  java.lang.String validateOptions()
          Validate the options currently in the option panes.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CustomReport

public CustomReport()
Method Detail

needsXmlReport

public boolean needsXmlReport()
Will this report need the standard XML data report if it is run. The default implementation returns false. Returning false does not mean that the report cannot ask for the XML, but by correctly answering, the harness may be able to apply some optimization based on which other reports are being generated.

Returns:
True if the XML report will be requested, false otherwise.
See Also:
getXmlReport()

getXmlReport

public final java.io.InputStream getXmlReport()
                                       throws java.io.IOException,
                                              org.xml.sax.SAXException
Request the content of the standard XML report from the harness. This method will always succeed, unless insufficient information exists to generate a report. Should only be called subsequent to a call from the harness to one of the createReport methods.

Throws:
java.io.IOException
org.xml.sax.SAXException
See Also:
needsXmlReport()

createReport

public abstract java.io.File createReport(java.io.File rootDir)
                                   throws CustomReport.ReportException
Create a report within the context of a GUI. The Interview parameter gives access to the WorkDirectory and other data structures required to generate a useful report. This is the primary method which needs to be overriden to create your report. Be sure to call the superclass method when overriding.

Parameters:
rootDir - The directory to write the report to.
Returns:
The filename of a file that should be displayed if possible. Currently, only HTML (with simple CSS), plain text and RTF can be rendered.
Throws:
CustomReport.ReportException - - if the report creation was unsuccessful. Harness can show Exception's text

createReport

public abstract java.io.File createReport(java.lang.String args,
                                          java.io.File rootDir,
                                          InterviewParameters ip,
                                          TestFilter filter)
                                   throws CustomReport.ReportException
Write a report without the context of a GUI. All information needed to generate the report should come from the given parameters and the Preferences subsystem if needed. Code in this method should be careful not to provoke any GUI initialization because the AWT and Swing toolkits may be unable to run in the current environment. Be sure to call the superclass method when overriding.

Parameters:
args - Arguments given to this report format. It is encoded into a single string, the format of which is defined by the report implementation. In general though, the arg string must be absent of spaces, and should not require any characters which require escaping on common platforms (semicolon, ampersand, exclamation, any quotation marks).
rootDir - The directory to write the report to.
ip - The interview which should be report on.
filter - The test filter that should be applied when iterating over the results to place in the report. If the report relies on the XML report, this parameter can usually be ignored since the XML report itself will have been filtered already.
Returns:
The filename of a file that should be displayed if possible. Currently, only HTML (with simple CSS), plain text and RTF can be rendered.
Throws:
CustomReport.ReportException - - if the report creation was unsuccessful. Harness can show Exception's text
See Also:
Preferences

getReportId

public abstract java.lang.String getReportId()
Get a short internal name for this report type. Should be unique within a test suite's set of report types. The value should be a valid Java identifier. This value could be used by the user to identify the report type on the command line, but otherwise will not generally be visible to the user. This value is also used to generate a unique directory name within the report directory when writing the report. So, it will be used when constructing the rootDir parameter of the createReport methods.

See Also:
getName(), Character.isJavaIdentifierStart(char), Character.isJavaIdentifierPart(char)

getName

public abstract java.lang.String getName()
Get a short name for this report type. The implementation should internationalize this value. This is the name that the user will generally see. There are not restrictions on the characters in the name, it may contain spaces, etc. It should be kept short, since it is likely to be presented in GUI lists and tabs. Example value: JT Harness Extended XML

Returns:
Internationalized name of this report. Should never be null or zero-length string.

getDescription

public abstract java.lang.String getDescription()
Get a longer description about the purpose of this report type. The implementation should internationalize this value. This may be presented to the user as inline help in the GUI, a "Info" popup, etc... The text should be descriptive about who would use the report, why, how it is different than other reports, the format of the report data (XML, binary, etc...). The length of the description could be up to a full paragraph in length. Do not include any special formatting in the string (newlines, HTML, etc...).

Returns:
Internationalized description of this report. Should never be null or zero-length string.

getReportEnviroment

public CustomReport.ReportEnviroment getReportEnviroment()

getOptionPanes

public CustomReport.ReportConfigPanel[] getOptionPanes()
Get report options panes. These panes can be used by the user to configure the report. These panes should be unique to this instance of the custom report, and should not be shared across many instances.


validateOptions

public abstract java.lang.String validateOptions()
Validate the options currently in the option panes. This method would only be called after getOptionPanes. It can be assumed that this method is called just before createReport to ensure that the user's settings are valid (in GUI mode). It is not called in non-GUI mode.

Returns:
Null if the current options are valid. If something is invalid, the return value is a short message indicating what setting the user should correct. The message should not be longer than a sentence or two.
See Also:
getOptionPanes(), CustomReport.ReportConfigPanel

dispose

public void dispose()
Dispose of any data or components which this class may be holding references to. Implementations should set references to data structures to null. The assumption is that this object is no longer usable after this method is called. Be sure to call the superclass implementation if you override this method.


setEnviroment

public void setEnviroment(CustomReport.ReportEnviroment envir)


Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved.