Merge pull request #5763 from APriestman/6211_updateReportDoc

6211 Updated documentation on writing report modules

docs/doxygen/modReport.dox

@@ -3,63 +3,18 @@
 \section report_summary Overview
 Report modules allow Autopsy users to create different report types.  Autopsy comes with modules to generate HTML and Excel artifact reports, a tab delimited File report, a Keyhole Markup Language (KML) report for Google Earth data, and a body file for timeline creation.  You can make additional modules to create custom output formats. 
 
-There are three types of reporting modules that differ in how the data is organized. 
-- Table report modules organize the data into tables.  If your output is in table format, this type of module will be easier to make because Autopsy does a lot of the organizing work for you. 
-- File report modules are also table-based, but they specifically deal with reporting on the Files in the case, not artifacts.
-- General report modules are free form and you are allowed to organize the output however you want.  
-
-Table report modules require their subclasses to override methods to start and end tables, and add rows to those tables. These methods are provided data, generated from a default configuration panel, for the module to report on. Because of this, when creating a table report module one only needs to focus on how to display the data, not how to find it.
-
-File report modules are similar to table report modules, but only require their sub-classes to start and end a single table, and add rows to that table. The methods are given an AbstractFile and a list of FileReportDataTypes, which specify what information about the file should be added to the report. The data can be extracted from the file by calling the FileReportDataTypes getValue method with the file as it's argument.
-
-On the other hand, general report modules have a single method to generate the report. This method gives the module freedom to find and process any data it so chooses. General modules also have the ability to provide a configuration panel, allowing the user to choose from various displayed settings. The report module may then use the user's selection to generate a more specific report.
+All custom report modules will be general report modules. General report modules have a single method to generate the report. This method gives the module freedom to find and process any data it so chooses. General modules also have the ability to provide a configuration panel, allowing the user to choose from various displayed settings. The report module may then use the user's selection to generate a more specific report.
 
 General modules are also given the responsibility of updating their report's progress bar and processing label in the UI. A progress panel is given to every general report module. It contains basic API to start, stop, and add to the progress bar, as well as update the processing label. The module is also expected to check the progress bar's status occasionally to see if the user has manually canceled the report.
 
 \section report_create_module Creating a Report Module
-To create a report module, start off by creating a new Java or Python (Jython) class and implementing (Java) or inheriting (Jython) the appropriate interface:
-- org.sleuthkit.autopsy.report.TableReportModule 
-- org.sleuthkit.autopsy.report.FileReportModule 
-- org.sleuthkit.autopsy.report.GeneralReportModule 
-
-All three of these interfaces extend the org.sleuthkit.autopsy.report.ReportModule interface that defines the following methods:
+To create a report module, start off by creating a new Java or Python (Jython) class and implementing (Java) or inheriting (Jython) from org.sleuthkit.autopsy.report.GeneralReportModule. You'll need to override multiple methods including the following:
 - org.sleuthkit.autopsy.report.ReportModule.getName()
 - org.sleuthkit.autopsy.report.ReportModule.getDescription()
 - org.sleuthkit.autopsy.report.ReportModule.getRelativeFilePath()
-
-These methods will be called by Autopsy when it is presenting the reporting UI to a user.
-
-\subsection report_create_module_table Creating A Table Report Module
-If you implement TableReportModule, you should override the methods:
-- org.sleuthkit.autopsy.report.TableReportModule.startReport(String path)
-- org.sleuthkit.autopsy.report.TableReportModule.endReport()
-- org.sleuthkit.autopsy.report.TableReportModule.startDataType(String title)
-- org.sleuthkit.autopsy.report.TableReportModule.endDataType()
-- org.sleuthkit.autopsy.report.TableReportModule.startSet(String setName)
-- org.sleuthkit.autopsy.report.TableReportModule.endSet()
-- org.sleuthkit.autopsy.report.TableReportModule.addSetIndex(List<String> sets)
-- org.sleuthkit.autopsy.report.TableReportModule.addSetElement(String elementName)
-- org.sleuthkit.autopsy.report.TableReportModule.startTable(List<String> titles)
-- org.sleuthkit.autopsy.report.TableReportModule.endTable()
-- org.sleuthkit.autopsy.report.TableReportModule.addRow(List<String> row)
-- org.sleuthkit.autopsy.report.TableReportModule.dateToString(long date)
-
-When generating table module reports, Autopsy will iterate through a list of user selected data, and call methods such as addRow(List<String> row) for every "row" of data it finds, or startTable(List<String> titles) for every new category it finds. Developers are guaranteed that every start of a data type, set, or table will be followed by an appropriate end. The focus for a table report module should be to take the given information and display it in a user friendly format. See org.sleuthkit.autopsy.report.ReportExcel for an example.
-
-\subsection report_create_module_file Creating a File Report Module
-If you implement FileReportModule, the overriden methods will be:
-- org.sleuthkit.autopsy.report.FileReportModule.startReport(String path)
-- org.sleuthkit.autopsy.report.FileReportModule.endReport()
-- org.sleuthkit.autopsy.report.FileReportModule.startTable(List<FileReportDataTypes> headers)
-- org.sleuthkit.autopsy.report.FileReportModule.endTable()
-- org.sleuthkit.autopsy.report.FileReportModule.addRow(AbstractFile toAdd, List<FileReportDataTypes> columns)
-
-As when generating table module reports, Autopsy will iterate through a list of user selected data (which are represented by FileReportDataTypes), and call addRow(AbstractFile toAdd, List<FileReportDataTypes> columns) for every abstract file in the case. Developers are guaranteed that the order of method calls will be startReport(), startTable(List<FileReportDataTypes> headers), addRow(AbstractFile toAdd, List<FileReportDataTypes> columns), AbstractFile toAdd, List<FileReportDataTypes> columns),..., endTable(), endReport().
-
-\subsection report_create_module_general Creating a General Report Module
-
-If you implement GeneralReportModule, the overridden methods will be:
 - org.sleuthkit.autopsy.report.GeneralReportModule.generateReport(String reportPath, ReportProgressPanel progressPanel)
+
+If your report module requires configuration, you'll need to override:
 - org.sleuthkit.autopsy.report.GeneralReportModule.getConfigurationPanel()
 
 For general report modules, Autopsy will simply call the generateReport(String reportPath, ReportProgressPanel progressPanel) method and leave it up to the module to aquire and report data in its desired format.  The only requirements are that the module saves to the given report path and updates the org.sleuthkit.autopsy.report.ReportProgressPanel as the report progresses.
@@ -90,22 +45,14 @@ if (null == searchService) {
 
 \subsection report_create_module_layer Installing your Report Module
 
-Report modules developed using Java must be registered in a layer.xml file. This file allows Autopsy to find the report module.
+Adding a service provider annotation allows Autopsy to find your report module.
 
-An example entry in a layer.xml is shown below:
 \code
-<folder name="Services">
-    <file name="org-sleuthkit-autopsy-report-ReportHTML.instance">
-        <attr name="instanceOf" stringvalue="org.sleuthkit.autopsy.report.TableReportModule"/>
-        <attr name="instanceCreate" methodvalue="org.sleuthkit.autopsy.report.ReportHTML.getDefault"/>
-        <attr name="position" intvalue="910"/>
-    </file>
-</folder>
+@ServiceProvider(service = GeneralReportModule.class)
+public class SampleReportModule implements GeneralReportModule {
 \endcode
 
-In the above example, "org-sleuthkit-autopsy-report-ReportHTML" should be replaced with the package path to your report module.
-
-It is also important to remember to include a getDefault() method in your report module. As shown in the code above, the instance to each report module is accessed via it's getDefault() method.
+It is also important to remember to include a getDefault() method in your report module. As shown in the code above, the instance to each report module is accessed via its getDefault() method.
 For example:
 
 \code