From 1fd1570cb65b24f827d4d533e83b1f675b28b38f Mon Sep 17 00:00:00 2001 From: adam-m Date: Sun, 22 Jul 2012 19:30:51 -0400 Subject: [PATCH] Better naming of module events, updated API docs --- .../DirectoryTreeTopComponent.java | 5 +- .../autopsy/ingest/IngestImageThread.java | 5 +- .../autopsy/ingest/IngestManager.java | 54 +++++++++++++++---- .../autopsy/ingest/ServiceDataEvent.java | 13 ++++- .../org/sleuthkit/autopsy/ingest/package.dox | 25 +++------ .../KeywordSearchEditListPanel.java | 7 +-- .../KeywordSearchListsViewerPanel.java | 33 ++++++------ 7 files changed, 88 insertions(+), 54 deletions(-) diff --git a/DirectoryTree/src/org/sleuthkit/autopsy/directorytree/DirectoryTreeTopComponent.java b/DirectoryTree/src/org/sleuthkit/autopsy/directorytree/DirectoryTreeTopComponent.java index ea59734b9b..2ea0302f4d 100644 --- a/DirectoryTree/src/org/sleuthkit/autopsy/directorytree/DirectoryTreeTopComponent.java +++ b/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() { diff --git a/Ingest/src/org/sleuthkit/autopsy/ingest/IngestImageThread.java b/Ingest/src/org/sleuthkit/autopsy/ingest/IngestImageThread.java index 761480840b..57d0237aaf 100644 --- a/Ingest/src/org/sleuthkit/autopsy/ingest/IngestImageThread.java +++ b/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 { 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 { 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()); } } diff --git a/Ingest/src/org/sleuthkit/autopsy/ingest/IngestManager.java b/Ingest/src/org/sleuthkit/autopsy/ingest/IngestManager.java index 8af100f255..fc2b6f59f0 100755 --- a/Ingest/src/org/sleuthkit/autopsy/ingest/IngestManager.java +++ b/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(); diff --git a/Ingest/src/org/sleuthkit/autopsy/ingest/ServiceDataEvent.java b/Ingest/src/org/sleuthkit/autopsy/ingest/ServiceDataEvent.java index 70df949e24..a044422b16 100644 --- a/Ingest/src/org/sleuthkit/autopsy/ingest/ServiceDataEvent.java +++ b/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. - * In its mos generic form, it only gives notice about a type of artifact and it + * of specific type to the blackboard. The name of property change fired is then IngestManager.IngestModuleEvent.DATA.toString() + * + * 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 { diff --git a/Ingest/src/org/sleuthkit/autopsy/ingest/package.dox b/Ingest/src/org/sleuthkit/autopsy/ingest/package.dox index db7ca8927d..450b890dfe 100644 --- a/Ingest/src/org/sleuthkit/autopsy/ingest/package.dox +++ b/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). +Use the IngestManager.addPropertyChangeListener() method to register a service event listener. +Events types received are defined in IngestManager.IngestModuleEvent enum. - -IngestManagerEvents.SERVICE_HAS_DATA event type, a special type of event object is passed in ServiceDataEvent. -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). - -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. - - -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. +At the end of the ingest, IngestManager itself will notify all listeners of IngestModuleEvent.COMPLETED event. +The event is an indication for listeners to perform the final data refresh by quering the blackboard. +Module developers are encouraged to generate periodic IngestModuleEvent.DATA +ServiceDataEvent events when they post data to the blackboard, +but the IngestManager will make a final event to handle scenarios where the module did not notify listeners while it was running. */ diff --git a/KeywordSearch/src/org/sleuthkit/autopsy/keywordsearch/KeywordSearchEditListPanel.java b/KeywordSearch/src/org/sleuthkit/autopsy/keywordsearch/KeywordSearchEditListPanel.java index fb14c035b3..30e1c8aa08 100644 --- a/KeywordSearch/src/org/sleuthkit/autopsy/keywordsearch/KeywordSearchEditListPanel.java +++ b/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); } diff --git a/KeywordSearch/src/org/sleuthkit/autopsy/keywordsearch/KeywordSearchListsViewerPanel.java b/KeywordSearch/src/org/sleuthkit/autopsy/keywordsearch/KeywordSearchListsViewerPanel.java index 9d3e4762a9..3445c1edab 100644 --- a/KeywordSearch/src/org/sleuthkit/autopsy/keywordsearch/KeywordSearchListsViewerPanel.java +++ b/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; /** - * - * @author dfickling + * Viewer panel widget for keyword lists */ 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) && - ((String) oldValue).equals(KeywordSearchIngestService.MODULE_NAME)) + if(changed.equals(IngestModuleEvent.COMPLETED.toString() ) && + ((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); + } } });