From 0df6a09f4357c9d2c2a92f34c5bdebd9b352aa61 Mon Sep 17 00:00:00 2001 From: Brian Carrier Date: Mon, 18 May 2015 10:49:27 -0400 Subject: [PATCH 1/2] Added comments to DataSourceProcessor interfaces --- .../DataSourceProcessor.java | 47 ++++++------- .../DataSourceProcessorCallback.java | 69 +++++++++++-------- .../DataSourceProcessorProgressMonitor.java | 4 +- 3 files changed, 65 insertions(+), 55 deletions(-) diff --git a/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessor.java b/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessor.java index e150e871ac..20a004c516 100644 --- a/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessor.java +++ b/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessor.java @@ -21,28 +21,25 @@ package org.sleuthkit.autopsy.corecomponentinterfaces; import javax.swing.JPanel; -/* - * Defines an interface used by the Add DataSource wizard to discover different - * Data SourceProcessors. +/** + * Interface used by the Add DataSource wizard to allow different + * types of data sources to be added to a case. Examples of data + * sources include disk images, local files, etc. * - * Each data source may have its unique attributes and may need to be processed - * differently. - * - * The DataSourceProcessor interface defines a uniform mechanism for the Autopsy UI + * The interface provides a uniform mechanism for the Autopsy UI * to: - * - collect details for the data source to be processed. - * - Process the data source in the background - * - Be notified when the processing is complete + * - Collect details from the user about the data source to be processed. + * - Process the data source in the background and add data to the database + * - Provides progress feedback to the user / UI. */ public interface DataSourceProcessor { - /* + /** * The DSP Panel may fire Property change events * The caller must enure to add itself as a listener and * then react appropriately to the events */ enum DSP_PANEL_EVENT { - UPDATE_UI, // the content of JPanel has changed that MAY warrant updates to the caller UI FOCUS_NEXT // the caller UI may move focus the the next UI element, following the panel. }; @@ -51,39 +48,43 @@ public interface DataSourceProcessor { /** * Returns the type of Data Source it handles. * This name gets displayed in the drop-down listbox - **/ + */ String getDataSourceType(); /** * Returns the picker panel to be displayed along with any other - * runtime options supported by the data source handler. - **/ + * runtime options supported by the data source handler. The + * DSP is responsible for storing the settings so that a later + * call to run() will have the user-specified settings. + * + * Should be less than 544 pixels wide and 173 pixels high. + */ JPanel getPanel(); /** * Called to validate the input data in the panel. * Returns true if no errors, or * Returns false if there is an error. - **/ + */ boolean isPanelValid(); /** - * Called to invoke the handling of Data source in the background. - * Returns after starting the background thread - * @param settings wizard settings to read/store properties - * @param progressPanel progress panel to be updated while processing + * Called to invoke the handling of data source in the background. + * Returns after starting the background thread. * - **/ + * @param progressPanel progress panel to be updated while processing + * @param dspCallback Contains the callback method DataSourceProcessorCallback.done() that the DSP must call when the background thread finishes with errors and status. + */ void run(DataSourceProcessorProgressMonitor progressPanel, DataSourceProcessorCallback dspCallback); /** * Called to cancel the background processing. - **/ + */ void cancel(); /** * Called to reset/reinitialize the DSP. - **/ + */ void reset(); } diff --git a/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessorCallback.java b/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessorCallback.java index 1b69c03c17..6fca9d08a6 100644 --- a/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessorCallback.java +++ b/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessorCallback.java @@ -16,7 +16,6 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - package org.sleuthkit.autopsy.corecomponentinterfaces; import java.awt.EventQueue; @@ -25,42 +24,52 @@ import org.sleuthkit.datamodel.Content; /** * Abstract class for a callback for a DataSourceProcessor. - * - * Ensures that DSP invokes the caller overridden method, doneEDT(), - * in the EDT thread. - * + * + * Ensures that DSP invokes the caller overridden method, doneEDT(), in the EDT + * thread. + * */ public abstract class DataSourceProcessorCallback { - - public enum DataSourceProcessorResult - { - NO_ERRORS, - CRITICAL_ERRORS, - NONCRITICAL_ERRORS, + + public enum DataSourceProcessorResult { + NO_ERRORS, + CRITICAL_ERRORS, + NONCRITICAL_ERRORS, }; + - /* - * Invoke the caller supplied callback function on the EDT thread + /** + * Called by a DSP implementation when it is done adding a data source + * to the database. Users of the DSP can override this method if they do + * not want to be notified on the EDT. Otherwise, this method will call + * doneEDT() with the same arguments. + * @param result Code for status + * @param errList List of error strings + * @param newContents List of root Content objects that were added to database. Typically only one is given. */ - public void done(DataSourceProcessorResult result, List errList, List newContents) - { - + public void done(DataSourceProcessorResult result, List errList, List newContents) { + final DataSourceProcessorResult resultf = result; final List errListf = errList; final List newContentsf = newContents; - - // Invoke doneEDT() that runs on the EDT . - EventQueue.invokeLater(new Runnable() { - @Override - public void run() { - doneEDT(resultf, errListf, newContentsf ); - - } - }); + + // Invoke doneEDT() that runs on the EDT . + EventQueue.invokeLater(new Runnable() { + @Override + public void run() { + doneEDT(resultf, errListf, newContentsf); + } + }); } - - /* - * calling code overrides to provide its own calllback - */ - public abstract void doneEDT(DataSourceProcessorResult result, List errList, List newContents); + + /** + * Called by done() if the default implementation is used. Users of DSPs + * that have UI updates to do after the DSP is finished adding the DS can + * implement this method to receive the updates on the EDT. + * + * @param result Code for status + * @param errList List of error strings + * @param newContents List of root Content objects that were added to database. Typically only one is given. + */ + public abstract void doneEDT(DataSourceProcessorResult result, List errList, List newContents); }; diff --git a/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessorProgressMonitor.java b/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessorProgressMonitor.java index 7495979d71..28001a9d62 100644 --- a/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessorProgressMonitor.java +++ b/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessorProgressMonitor.java @@ -18,10 +18,10 @@ */ package org.sleuthkit.autopsy.corecomponentinterfaces; -/* +/** * An GUI agnostic DataSourceProcessorProgressMonitor interface for DataSourceProcesssors to * indicate progress. - * It models after a JProgressbar though it could use any underlying implementation + * It models after a JProgressbar though it could use any underlying implementation (or NoOps) */ public interface DataSourceProcessorProgressMonitor { From 5e997614a5d94592aec4bd7685a0f9a4c8cf823c Mon Sep 17 00:00:00 2001 From: Brian Carrier Date: Mon, 18 May 2015 10:55:31 -0400 Subject: [PATCH 2/2] Added comments to DataSourceProcessor interfaces --- .../corecomponentinterfaces/DataSourceProcessor.java | 4 ++-- .../DataSourceProcessorCallback.java | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessor.java b/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessor.java index 20a004c516..f76f6b29a1 100644 --- a/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessor.java +++ b/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessor.java @@ -40,8 +40,8 @@ public interface DataSourceProcessor { * then react appropriately to the events */ enum DSP_PANEL_EVENT { - UPDATE_UI, // the content of JPanel has changed that MAY warrant updates to the caller UI - FOCUS_NEXT // the caller UI may move focus the the next UI element, following the panel. + UPDATE_UI, ///< the content of JPanel has changed that MAY warrant updates to the caller UI + FOCUS_NEXT ///< the caller UI may move focus the the next UI element, following the panel. }; diff --git a/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessorCallback.java b/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessorCallback.java index 6fca9d08a6..76acfd2efc 100644 --- a/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessorCallback.java +++ b/Core/src/org/sleuthkit/autopsy/corecomponentinterfaces/DataSourceProcessorCallback.java @@ -32,9 +32,9 @@ import org.sleuthkit.datamodel.Content; public abstract class DataSourceProcessorCallback { public enum DataSourceProcessorResult { - NO_ERRORS, - CRITICAL_ERRORS, - NONCRITICAL_ERRORS, + NO_ERRORS, ///< No errors were encountered while ading the data source + CRITICAL_ERRORS, ///< No data was added to the database. There were fundamental errors processing the data (such as no data or system failure). + NONCRITICAL_ERRORS, ///< There was data added to the database, but there were errors from data corruption or a small number of minor issues. };