Better naming of module events, updated API docs

DirectoryTree/src/org/sleuthkit/autopsy/directorytree/DirectoryTreeTopComponent.java

@@ -63,6 +63,7 @@ import org.sleuthkit.autopsy.datamodel.RootContentChildren;
 import org.sleuthkit.autopsy.datamodel.Views;
 import org.sleuthkit.autopsy.datamodel.ViewsNode;
 import org.sleuthkit.autopsy.ingest.IngestManager;
+import org.sleuthkit.autopsy.ingest.IngestManager.IngestModuleEvent;
 import org.sleuthkit.autopsy.ingest.ServiceDataEvent;
 import org.sleuthkit.datamodel.BlackboardArtifact;
 import org.sleuthkit.datamodel.BlackboardAttribute;
@@ -683,7 +684,7 @@ public final class DirectoryTreeTopComponent extends TopComponent implements Dat
             }
         }
 
-        if (changed.equals(IngestManager.SERVICE_HAS_DATA_EVT)) {
+        if (changed.equals(IngestModuleEvent.DATA.toString())) {
             final ServiceDataEvent event = (ServiceDataEvent) oldValue;
             SwingUtilities.invokeLater(new Runnable() {
                 @Override
@@ -693,7 +694,7 @@ public final class DirectoryTreeTopComponent extends TopComponent implements Dat
             });
         }
         
-        if (changed.equals(IngestManager.SERVICE_COMPLETED_EVT)) {
+        if (changed.equals(IngestModuleEvent.COMPLETED.toString())) {
             SwingUtilities.invokeLater(new Runnable() {
                 @Override
                 public void run() {

Ingest/src/org/sleuthkit/autopsy/ingest/IngestImageThread.java

@@ -26,6 +26,7 @@ import javax.swing.SwingWorker;
 import org.netbeans.api.progress.ProgressHandle;
 import org.netbeans.api.progress.ProgressHandleFactory;
 import org.openide.util.Cancellable;
+import org.sleuthkit.autopsy.ingest.IngestManager.IngestModuleEvent;
 import org.sleuthkit.datamodel.Image;
 
 /**
@@ -107,7 +108,7 @@ public class IngestImageThread extends SwingWorker<Object, Void> {
                 catch (Exception e) {
                     logger.log(Level.INFO, "Error completing the service " + service.getName(), e);
                 }
-                IngestManager.fireServiceEvent(IngestManager.SERVICE_COMPLETED_EVT, service.getName());
+                IngestManager.fireServiceEvent(IngestModuleEvent.COMPLETED.toString(), service.getName());
             } else {
                 logger.log(Level.INFO, "Service " + service.getName() + " stopped");
                 try {
@@ -116,7 +117,7 @@ public class IngestImageThread extends SwingWorker<Object, Void> {
                 catch (Exception e) {
                     logger.log(Level.INFO, "Error stopping the service" + service.getName(), e);
                 }
-                IngestManager.fireServiceEvent(IngestManager.SERVICE_STOPPED_EVT, service.getName());
+                IngestManager.fireServiceEvent(IngestModuleEvent.STOPPED.toString(), service.getName());
             }
 
         }

Ingest/src/org/sleuthkit/autopsy/ingest/IngestManager.java

@@ -98,13 +98,45 @@ public class IngestManager {
     //monitor
     private final IngestMonitor ingestMonitor = new IngestMonitor();
 
-    private enum IngestManagerEvents {
+    /**
-        SERVICE_STARTED, SERVICE_COMPLETED, SERVICE_STOPPED, SERVICE_HAS_DATA
+     * Possible events about ingest modules
+     * Event listeners can get the event name 
+     * by using String returned by toString() method on the specific event.
+     */
+    public enum IngestModuleEvent {
+        /**
+         * Event sent when the ingest module has been started processing.
+         * Second argument of the property change fired contains module name String
+         * and third argument is null.
+         */
+        STARTED,
+     
+        /**
+         * Event sent when the ingest module has completed processing.
+         * Second argument of the property change fired contains module name String
+         * and third argument is null.
+         * 
+         * This event is generally used by listeners to perform a final data view refresh (listeners need to query all data from the blackboard).
+         * 
+         */
+        COMPLETED,
+        
+        /**
+         * Event sent when the ingest module has stopped processing, and likely not all data has been processed.
+         * Second argument of the property change fired contains module name String
+         * and third argument is null.
+         */
+        STOPPED, 
+        
+        /**
+         * Event sent when ingest module has new data.
+         * Second argument of the property change fired contains ServiceDataEvent object and third argument is null.
+         * The object can contain encapsulated new data created by the service.
+         * Listener can also query new data as needed.
+         * 
+         */
+        DATA
     };
-    public final static String SERVICE_STARTED_EVT = IngestManagerEvents.SERVICE_STARTED.name();
-    public final static String SERVICE_COMPLETED_EVT = IngestManagerEvents.SERVICE_COMPLETED.name();
-    public final static String SERVICE_STOPPED_EVT = IngestManagerEvents.SERVICE_STOPPED.name();
-    public final static String SERVICE_HAS_DATA_EVT = IngestManagerEvents.SERVICE_HAS_DATA.name();
     
     //ui
     private IngestUI ui = null;
@@ -144,7 +176,7 @@ public class IngestManager {
     }
 
     static synchronized void fireServiceDataEvent(ServiceDataEvent serviceDataEvent) {
-        pcs.firePropertyChange(SERVICE_HAS_DATA_EVT, serviceDataEvent, null);
+        pcs.firePropertyChange(IngestModuleEvent.DATA.toString(), serviceDataEvent, null);
     }
 
     /**
@@ -248,7 +280,7 @@ public class IngestManager {
                     //image services are now initialized per instance
                     quService.init(managerProxy);
                     newImageWorker.execute();
-                    IngestManager.fireServiceEvent(SERVICE_STARTED_EVT, quService.getName());
+                    IngestManager.fireServiceEvent(IngestModuleEvent.STARTED.toString(), quService.getName());
                 }
             }
         }
@@ -980,7 +1012,7 @@ public class IngestManager {
 
             //notify main thread services started
             for (IngestServiceAbstractFile s : abstractFileServices) {
-                IngestManager.fireServiceEvent(SERVICE_STARTED_EVT, s.getName());
+                IngestManager.fireServiceEvent(IngestModuleEvent.STARTED.toString(), s.getName());
             }
 
             final String displayName = "File Ingest";
@@ -1062,7 +1094,7 @@ public class IngestManager {
                 if (!this.isCancelled()) {
                     for (IngestServiceAbstractFile s : abstractFileServices) {
                         s.complete();
-                        IngestManager.fireServiceEvent(SERVICE_COMPLETED_EVT, s.getName());
+                        IngestManager.fireServiceEvent(IngestModuleEvent.COMPLETED.toString(), s.getName());
                     }
                 }
 
@@ -1102,7 +1134,7 @@ public class IngestManager {
                         logger.log(Level.WARNING, "Exception while stopping service: " + s.getName(), e);
                     }
                 }
-                IngestManager.fireServiceEvent(SERVICE_STOPPED_EVT, s.getName());
+                IngestManager.fireServiceEvent(IngestModuleEvent.STOPPED.toString(), s.getName());
             }
             //empty queues
             emptyAbstractFiles();

Ingest/src/org/sleuthkit/autopsy/ingest/ServiceDataEvent.java

@@ -24,9 +24,18 @@ import org.sleuthkit.datamodel.BlackboardArtifact.ARTIFACT_TYPE;
 
 /**
  * Event data that are fired off by ingest modules when they have posted new data
- * of specific type to the blackboard. 
+ * of specific type to the blackboard. The name of property change fired is then IngestManager.IngestModuleEvent.DATA.toString()
- * In its mos generic form, it only gives notice about a type of artifact and it 
+ * 
+ * In its most generic form, it only gives notice about a type of artifact and it 
  * can also give notice about specific IDs that can be retrieved.
+ * 
+ * The object wraps a collection of blackboard artifacts and their associated attributes that are to be reported as the new data to listeners.
+ * Passing the data as part of the event reduces memory footprint and decreases number of garbage collections of the blackboard artifacts and attributes objects (the objects are expected to be reused by the data event listeners).
+ * 
+ * If a service does not pass the data as part of ServiceDataEvent (ServiceDataEvent.getArtifacts() returns null) - it is an indication that the service 
+ * has new data but it does not implement new data tracking.  The listener can then perform a blackboard query to get the latest data of interest (e.g. by artifact type).
+ * 
+ * By design, only a single type of artifacts can be contained in a single data event. 
  */
 public class ServiceDataEvent {
 

Ingest/src/org/sleuthkit/autopsy/ingest/package.dox

@@ -152,23 +152,14 @@ methods should be used for general configuration.
 Other modules and core Autopsy classes may want to get the status of the ingest manager.  The IngestManager provides access to this data with the sleuthkit.autopsy.ingest.IngestManager.isIngestRunning() method.
 
 
-External modules can also register themselves as ingest service event listeners and receive event notifications (when a module is started, stopped, completed or has new data).  Use the IngestManager.addPropertyChangeListener() method to register a service event listener.  Events types received are defined in IngestManager.IngestManagerEvents enum.   
+External modules can also register themselves as ingest service event listeners and receive event notifications (when a module is started, stopped, completed or has new data).  
-<!-- @@@ This is a private enumÉ -->
+Use the IngestManager.addPropertyChangeListener() method to register a service event listener.  
+Events types received are defined in IngestManager.IngestModuleEvent enum.   
 
-<!-- @@@ This should be moved to the class documentation -- we should document what each event means -->
+At the end of the ingest, IngestManager itself will notify all listeners of IngestModuleEvent.COMPLETED event.
-IngestManagerEvents.SERVICE_HAS_DATA event type, a special type of event object is passed in ServiceDataEvent.
+The event is an indication for listeners to perform the final data refresh by quering the blackboard.
-The object wraps a collection of blackboard artifacts and their associated attributes that are to be reported as the new data to listeners.
+Module developers are encouraged to generate periodic IngestModuleEvent.DATA 
-Passing the data as part of the event reduces memory footprint and decreases number of garbage collections 
+ServiceDataEvent events when they post data to the blackboard, 
-of the blackboard artifacts and attributes objects (the objects are expected to be reused by the data event listeners).
+but the IngestManager will make a final event to handle scenarios where the module did not notify listeners while it was running. 
-
-If a service does not pass the data as part of ServiceDataEvent (ServiceDataEvent.getArtifacts() returns null) - it is an indication that the service 
-has new data but it does not implement new data tracking.  The listener can then perform a blackboard query to get the latest data of interest (e.g. by artifact type).
-
-Service name and artifact type for the collection of artifacts is also passed in as as part of the service data event.
-By design, only a single type of artifacts can be contained in a single data event. 
-
-<!-- @@@ We should mention with what type of event they will be notified with. -->
-At the end of the ingest, IngestManager itself will notify all listeners of new data being available in the blackboard.
-Module developers are encouraged to generate events when they post data to the blackboard, but the IngestManger will make a final event to handle scenarios where the module did not notify listeners while it was running. 
 
 */

KeywordSearch/src/org/sleuthkit/autopsy/keywordsearch/KeywordSearchEditListPanel.java

@@ -47,6 +47,7 @@ import javax.swing.table.AbstractTableModel;
 import javax.swing.table.TableCellRenderer;
 import javax.swing.table.TableColumn;
 import org.sleuthkit.autopsy.ingest.IngestManager;
+import org.sleuthkit.autopsy.ingest.IngestManager.IngestModuleEvent;
 import org.sleuthkit.datamodel.BlackboardAttribute;
 
 /**
@@ -189,13 +190,13 @@ class KeywordSearchEditListPanel extends javax.swing.JPanel implements ListSelec
             public void propertyChange(PropertyChangeEvent evt) {
                 String changed = evt.getPropertyName();
                 Object oldValue = evt.getOldValue();
-                if (changed.equals(IngestManager.SERVICE_COMPLETED_EVT)
+                if (changed.equals(IngestModuleEvent.COMPLETED.toString() )
                         && ((String) oldValue).equals(KeywordSearchIngestService.MODULE_NAME)) {
                     initIngest(1);
-                } else if (changed.equals(IngestManager.SERVICE_STARTED_EVT)
+                } else if (changed.equals(IngestModuleEvent.STARTED.toString() )
                         && ((String) oldValue).equals(KeywordSearchIngestService.MODULE_NAME)) {
                     initIngest(0);
-                } else if (changed.equals(IngestManager.SERVICE_STOPPED_EVT)
+                } else if (changed.equals(IngestModuleEvent.STOPPED.toString() )
                         && ((String) oldValue).equals(KeywordSearchIngestService.MODULE_NAME)) {
                     initIngest(1);
                 }

KeywordSearch/src/org/sleuthkit/autopsy/keywordsearch/KeywordSearchListsViewerPanel.java

@@ -17,11 +17,7 @@
  * limitations under the License.
  */
 
-/*
+
- * KeywordSearchListsViewerPanel.java
- *
- * Created on Feb 17, 2012, 1:45:38 PM
- */
 package org.sleuthkit.autopsy.keywordsearch;
 
 import java.awt.Component;
@@ -37,8 +33,6 @@ import java.util.logging.Logger;
 import javax.swing.JCheckBox;
 import javax.swing.JTable;
 import javax.swing.ListSelectionModel;
-import javax.swing.border.Border;
-import javax.swing.border.EmptyBorder;
 import javax.swing.event.ListSelectionEvent;
 import javax.swing.event.ListSelectionListener;
 import javax.swing.table.AbstractTableModel;
@@ -46,10 +40,10 @@ import javax.swing.table.TableCellRenderer;
 import javax.swing.table.TableColumn;
 import org.openide.util.actions.SystemAction;
 import org.sleuthkit.autopsy.ingest.IngestManager;
+import org.sleuthkit.autopsy.ingest.IngestManager.IngestModuleEvent;
 
 /**
- *
+ * Viewer panel widget for keyword lists
- * @author dfickling
  */
 class KeywordSearchListsViewerPanel extends AbstractKeywordSearchPerformer {
     
@@ -165,10 +159,12 @@ class KeywordSearchListsViewerPanel extends AbstractKeywordSearchPerformer {
             }
         };
         
-        if(IngestManager.getDefault().isServiceRunning(KeywordSearchIngestService.getDefault()))
+        if(IngestManager.getDefault().isServiceRunning(KeywordSearchIngestService.getDefault())) {
             initIngest(true);
-        else
+        }
+        else {
             initIngest(false);
+        }
         
         IngestManager.addPropertyChangeListener(new PropertyChangeListener() {
 
@@ -176,15 +172,18 @@ class KeywordSearchListsViewerPanel extends AbstractKeywordSearchPerformer {
             public void propertyChange(PropertyChangeEvent evt) {
                 String changed = evt.getPropertyName();
                 Object oldValue = evt.getOldValue();
-                if(changed.equals(IngestManager.SERVICE_COMPLETED_EVT) &&
+                if(changed.equals(IngestModuleEvent.COMPLETED.toString() ) &&
-                        ((String) oldValue).equals(KeywordSearchIngestService.MODULE_NAME))
+                        ((String) oldValue).equals(KeywordSearchIngestService.MODULE_NAME)) {
                     initIngest(false);
-                else if(changed.equals(IngestManager.SERVICE_STARTED_EVT) &&
+                }
-                        ((String) oldValue).equals(KeywordSearchIngestService.MODULE_NAME))
+                else if(changed.equals(IngestModuleEvent.STARTED.toString() ) &&
+                        ((String) oldValue).equals(KeywordSearchIngestService.MODULE_NAME)) {
                     initIngest(true);
-                else if(changed.equals(IngestManager.SERVICE_STOPPED_EVT) &&
+                }
-                        ((String) oldValue).equals(KeywordSearchIngestService.MODULE_NAME))
+                else if(changed.equals(IngestModuleEvent.STOPPED.toString() ) &&
+                        ((String) oldValue).equals(KeywordSearchIngestService.MODULE_NAME)) {
                     initIngest(false);
+                }
             }
             
         });