Class Report

java.lang.Object
ca.spatial.reportwriter.Report
All Implemented Interfaces:
Selectable<Report>, Comparable<Report>
Direct Known Subclasses:
BlockAvailReport, BlockReport, CategoryReport, ChartReport, ColumnSummaryReport, CompareChartWriter, CompareReport, CopyFileReport, CrosstabReport, DecodeReport, ExcelReport, ExclusiveAssignmentReport, ExclusiveLockReport, GeneralReport, IndexReport, MapLayoutReport, MapReport, NetworkCostReport, ObjectiveProgressReport, PatchDetailReport, PatchReport, PeriodValueReport, PivotTableReport, RangeIndicatorChartReport, RangePeriodReport, RangeReport, RasterRemapReport, RouteCostReport, RouteReport, ScenarioEventReport, ShortageReport, StandEventReport, TableQueryReport, TargetReport, TargetStatusReport, TargetSummaryReport, TextReport, TreatmentReport, TreeReport

public abstract class Report extends Object implements Comparable<Report>, Selectable<Report>
This abstract class defines the template for reports used in the ReportWriter system.

The reports themselves are usually templates, that are parameterized with arguments that are passed in through the constructor. The arguments often specify column headings, reselection criteria, and grouping criteria. The layout of the data within the report is usually an intrinsic property of the hard-coded report template.

Reports are retrieved from the report writer by a URL that identifies the report by a path name. The path name is provided in the report constructor, and registers the report to a location in the report writer. For example, a report describing area harvested might be retrieved from "http://localhost:8081/areaHarvested.html".

Report templates often provide their content in several formats, usually HTML (formatted table), PNG (histogram) and CSV (raw data). Each format is rendered by requested the report with the appropriate file extention (".html", ".png", or ".csv").

Parameters:
Reports sometimes support parameters that can be passed in the URL as a query string (for example:
"http://localhost:8081/areaHarvested.html?scenario=Test1".

Query strings follow the usual URL syntax:

  • A query string is separated from the location part of the URL by a '?' character
  • Each element in a query string is label/value pair, separated by an '=' symbol (e.g. "label=value")
  • Multiple query string elements are separated by the '&' symbol (e.g. "label1=value1&label2=value2")
  • Arrays of values are represented by multiple elements having the same label (e.g. "period=1&period=2&period=3")

Most reports allow the following query string elements:

Report parameters
ElementDescription
selectedIndicates if the report should only tally records that have been selected in the base table. This element does not require a value; the mere presence of the element indicates that only selected values should be used.
scenarioThe value of this element contains a phrase that is appended to the report title. The scenario name is written to the HTML file to help document the conditions in place when the report was created.
chart.typeThis parameter will control the display of the charts in some of the report types. Not all charts can be controlled with this parameter. The values that can be specified are 'line', 'area', 'bar', and 'stackedbar'.
chart.widthThis parameter will control the width of the chart. The value is the number of pixels.
chart.heightThis parameter will control the height of the chart. The value is the number of pixels.
chart.seriescolor_0This controls the colour used for the first series. Series numbers start at zero, so the colour value for the second series would be specified by seriescolor_1. The color value is specified as a hexidecimal RGB triplet, such as "#ff0000" for red.
chart.texture_0This controls the stipple pattern used for the first series. Series numbers start at zero, so the stipple value for the second series would be specified by texture_1. The stipple value is specified as a name from the SPSTexturePaint class, such as "stipple1".
chart.linewidth_0This controls the line width used for the first series. Series numbers start at zero, so the width value for the second series would be specified by series.1.linewidth. The linewidth value is specified in points.
chart.xaxis.categoryControls if the x-axis should be rendered as categories (true). If the values in the xaxis are numbers in ascending order the default will be to display the axis using a numeric range. This parameter can override that behaviour and display a category axis. (e.g. "true")
chart.referenceAdds a horizontal reference line to the chart. The parameter contains the y-value for the location of the line. Three optional parameters may be provide, separated by semicolons. The first is an optional color specified as a hexdecimal RGB triplet. The seond is the line width specified as a number, and the third is a dash distance for creating dashed lines (e.g. "125000;#0000ff;2;10"). Multiple reference lines may be specified, each grouping of parameters separated by a | character (e.g. 305000;#00ff00;2;10|328000;#dddd00;2;10).
chart.boundsRangeAxisSpecifies the bounds on the range axis as a pair of number separated with a semicolon (e.g. "-50;50")
chart.logRangeAxisSpecifies the range axis should use a logarithmic scale using a true/false value (e.g. "true")
chart.spliDomainAxisSpeficies to use a hierarchical type of domain axis that is useful for category data. Specify using a true/false value (e.g. "true")

See the specific report documentation for details about additional query string elements.

See the setDefaultParams(java.lang.String[][]) and ReportWriter.setDefaultParams(java.lang.String[][]) methods for a means to set default query string parameters.

Author:
Tom Moore
See Also:
ReportWriter
  • Field Details

    • STACKED_BARS

      public static final int STACKED_BARS
      A flag indicating the stacked bar type of chart, used in the makePng(java.lang.String, java.lang.String, java.lang.String, java.lang.String[], java.lang.String[], double[][], int, java.io.PrintStream, java.util.Map<java.lang.String, java.lang.Object>) method.
      See Also:
      Constant Field Values
    • SIDE_BY_SIDE_BARS

      public static final int SIDE_BY_SIDE_BARS
      A flag indicating the side-by-side bar type of chart, used in the makePng(java.lang.String, java.lang.String, java.lang.String, java.lang.String[], java.lang.String[], double[][], int, java.io.PrintStream, java.util.Map<java.lang.String, java.lang.Object>) method.
      See Also:
      Constant Field Values
    • LINE

      public static final int LINE
      A flag indicating the line chart type, used in the makePng(java.lang.String, java.lang.String, java.lang.String, java.lang.String[], java.lang.String[], double[][], int, java.io.PrintStream, java.util.Map<java.lang.String, java.lang.Object>) method.
      See Also:
      Constant Field Values
    • AREA

      public static final int AREA
      A flag indicating the area chart type, used in the makePng(java.lang.String, java.lang.String, java.lang.String, java.lang.String[], java.lang.String[], double[][], int, java.io.PrintStream, java.util.Map<java.lang.String, java.lang.Object>) method.
      See Also:
      Constant Field Values
    • PIE

      public static final int PIE
      A flag indicating the pie chart type, used in the makePng(java.lang.String, java.lang.String, java.lang.String, java.lang.String[], java.lang.String[], double[][], int, java.io.PrintStream, java.util.Map<java.lang.String, java.lang.Object>) method.
      See Also:
      Constant Field Values
  • Constructor Details

    • Report

      public Report(String filename, String title)
      The standard constructor for all reports. Most reports will invoke this superclass constructor.
      Parameters:
      filename - The basename of the report (not including the filename extenstion).
      title - The report title (also used in the index).
  • Method Details

    • doReport

      public abstract ca.spatial.reportwriter.Report.DataCache doReport(String reportName, PrintStream out, Map<String,​Object> param, ca.spatial.reportwriter.Report.DataCache cache)
      The method used by the report writer to format the requested report. This method is implemented in every custom report. Application programs generally do not need to call this method, but instead use the report writer methods to obtain reports.
      Parameters:
      reportName - The full name of the report to be printed, including the extension of the sub-report (if any).
      out - The output stream to print output on to.
      param - A HashMap containing parameters that modify the report (for example the scenario name).
    • getTitle

      public String getTitle()
      An accessor function to retrieve the report title
    • setTitle

      public Report setTitle(String title)
      A function to set the report title
    • setDisplayFormat

      public Report setDisplayFormat(String pattern)
    • getDisplayFormat

      public String getDisplayFormat()
    • toString

      public String toString()
      Returns the report title
      Overrides:
      toString in class Object
    • getLength

      public long getLength(String filename, Map<String,​Object> param)
      Return the length of this report, in bytes. In most cases the length of the report is unknown because it is generated on the fly. By default we will return a -1 to indicate an unknown length. Specialized classes can over ride this.
    • getAttributeStore

      public AttributeStore getAttributeStore()
      Get the AttributeStore that provides the data for this report.
    • setAttributeStore

      public void setAttributeStore(AttributeStore store)
      Set the AttributeStore that provides the data for this report.
    • getFilename

      public String getFilename()
      An accessor function to retrieve the report name
    • getDefaultFilename

      public String getDefaultFilename()
      Return the preferred or default filename, if this report produces multiple file types.
    • getBasepart

      public static String getBasepart(String filename)
      An accessor function to retrieve the final part of the report name
    • getBasepart

      public String getBasepart()
      An accessor function to retrieve the final part of the report name
    • getNamepart

      public static String getNamepart(String filename)
      An accessor function to retrieve the final part of the report name
    • getNamepart

      public String getNamepart()
      An accessor function to retrieve the final part of the report name
    • getFolderpart

      public static String getFolderpart(String filename)
      An accessor function to retrieve the folder part of the report name
    • getFolderpart

      public String getFolderpart()
      An accessor function to retrieve the folder part of the report name
    • getExtension

      public static String getExtension(String filename)
      An accessor function to retrieve the filename extension
    • getExtension

      public String getExtension()
      An accessor function to retrieve the filename extension
    • getTypes

      public abstract String[] getTypes()
      An accessor function to retrieve the list of report types supported by this report. See the documentation for the TYPES variable for the list of sub-types.
    • getAdditionalFiles

      public String[] getAdditionalFiles()
      Return a list of additional file names provided by this report.
    • getReportFor

      public String getReportFor(String ext)
    • doesGIF

      public boolean doesGIF()
      Test if the report supports the GIF type
    • doesPNG

      public boolean doesPNG()
      Test if the report supports the PNG type
    • doesHTML

      public boolean doesHTML()
      Test if the report supports the HTML type
    • doesCSV

      public boolean doesCSV()
      Test if the report supports the CSV type
    • doesAnyTypes

      public boolean doesAnyTypes(String[] types)
      A test for one of several file types
    • doesType

      public boolean doesType(String type)
      A test for a specific file type
    • isDhandler

      public boolean isDhandler()
      Indicate if this report is a dynamic handler. This report type will be deprecated and is not documented.
    • isSelected

      public boolean isSelected()
      Indicate if the report is 'selected'. When selected the report will be marked in the ReportSelector tree widget, and will be output when the scenario is saved.
      Specified by:
      isSelected in interface Selectable<Report>
    • setSelected

      public Report setSelected(boolean selected)
      Set a flag to indicate if the report is selected or not.
      Specified by:
      setSelected in interface Selectable<Report>
    • isIndexed

      public boolean isIndexed()
      Indicate if the report is to be listed in the index.
    • setIndexed

      public Report setIndexed(boolean indexed)
      Set a flag to indicate that the report is indexed or not.
    • setDefaultParams

      public Report setDefaultParams(String[][] defaults)
      Set a list of parameters that will be used with this report. The parameters might influence the display of the report or of the chart.

      The parameters influence the display of the report or of the chart. The default parameters are merged with parameters that are provided on the query string with the report URL. The parameters on the URL will over ride the default parameters.

      Very few reports support parameters, but this mechanism will be used in future to support some form of report customization. See the Report class description for documenation of commonly used parameters. See the Parameter notes in the class description of each individual report for report-specific parameters.

      Parameters:
      defaults - The list of name/value pairs of default parameters.
    • addDefaultParam

      public Report addDefaultParam(String key, Object value)
      Add a parameter to the list of defaults.
      Parameters:
      key - The parameter key
      value - The parameter value
    • interpolateParams

      public String interpolateParams(String text, Map<String,​Object> hm)
      Interpolate parameter values into a string. Where parameter keys are found in the string they are replaced with the parameter values. Parameter keys in the input text must be quoted with {% and %} tokens.
      Parameters:
      text - The string to be interpolated.
      hm - The set of key/value parameters used for substitution.
    • encodeURL

      public static String encodeURL(String url)
      This helper method will convert a URL in string format to encoded format. The encoding will convert special characters that are not permitted in URL strings (such as a space character) to their encoded equivalents.
      Parameters:
      url - The URL to encode.
      Returns:
      The encoded value.
    • encodeFileURL

      public static String encodeFileURL(String url)
      This helper method will convert the filename part of an URL in string format to encoded format. The encoding will convert special characters that are not permitted in URL filename strings (such as a space character) to their encoded equivalents, but it will leave filename legal parts (e.g. '/') intact.
      Parameters:
      url - The URL to encode.
      Returns:
      The encoded value.
    • header

      public String header(String title, ReportWriter rw)
      Write a standard HTML page header. This includes the doctype, html head with javascript and css references, the opening body tag and the title.

      To complete the page write the closing body and html tags or call the footer() method which will close these tags automatically.

    • getPathToRoot

      public String getPathToRoot()
    • endMainContent

      public String endMainContent()
      Get the end of the main content div
    • footer

      public static String footer()
      Write a standard HTML page footer
    • htmlText

      public String htmlText(String text, Map<String,​Object> param)
    • chartImg

      public String chartImg(String name, Map<String,​Object> param)
    • csvLink

      public String csvLink(Map<String,​Object> param)
    • indexLink

      public String indexLink()
    • parentIndex

      public String parentIndex()
    • patternToRegex

      public static String patternToRegex(String spec, boolean wildSuffix)
      Convert a pattern spec to a regular expression pattern. Two types of patterns specs are handled. If the input spec starts with a '~' character, then discard this and treat the rest of the string as a regular expression (no translation). Otherwise, treat the specification as a glob pattern that has a trailing wildcard. When globbing this routine will escape special characters, and transform '*' and '?' to wildcard strings and characters.

      For more information about regular expressions see the Pattern class.

      Parameters:
      spec - A string containing the pattern to convert.
      wildSuffix - A flag to indicate if a wildcard suffix should added to the pattern. This will only be added if the spec string is not a regex (not prefixed with '~').
      Returns:
      A string with a regular expression pattern.
      See Also:
      Pattern
    • escapeRegexChars

      public static String escapeRegexChars(String pattern)
    • uniqueLabels

      public static String[] uniqueLabels(String[] labels)
    • compareTo

      public int compareTo(Report r2)
      Specified by:
      compareTo in interface Comparable<Report>
    • formatColumnHeadings

      public String formatColumnHeadings(DefaultMutableTreeNode node, String[] initialCols, String[] finalCols)
      Print hierarchically nested column headings.
    • formatColumnHeadings

      public String formatColumnHeadings(DefaultMutableTreeNode node, int initialCols, String[] finalCols)
      Print hierarchically nested column headings.