From ba60762d44a27bded84f1bb6fdedf1519bf71a01 Mon Sep 17 00:00:00 2001
From: Greg DiCristofaro <gregd@basistech.com>
Date: Fri, 6 Mar 2020 15:42:23 -0500
Subject: [PATCH] updated comments

---
 .../contentviewers/TranslatablePanel.java     | 97 +++++++++++++++----
 .../texttranslation/ui/TranslateTextTask.java | 67 +++++++++----
 2 files changed, 126 insertions(+), 38 deletions(-)

diff --git a/Core/src/org/sleuthkit/autopsy/contentviewers/TranslatablePanel.java b/Core/src/org/sleuthkit/autopsy/contentviewers/TranslatablePanel.java
index d1aa1e57af..e20b7e063e 100644
--- a/Core/src/org/sleuthkit/autopsy/contentviewers/TranslatablePanel.java
+++ b/Core/src/org/sleuthkit/autopsy/contentviewers/TranslatablePanel.java
@@ -39,7 +39,13 @@ import org.sleuthkit.autopsy.texttranslation.ui.TranslateTextTask;
  */
 class TranslatablePanel extends JPanel {
     
+    /**
+     * an exception that can occur during the normal operation of the translatable panel
+     * for instance, this exception can be thrown if it is not possible to set the child
+     * content to the provided content string
+     */
     class TranslatablePanelException extends Exception {
+        public static final long serialVersionUID = 1L;
 
         TranslatablePanelException(String message) {
             super(message);
@@ -168,9 +174,6 @@ class TranslatablePanel extends JPanel {
     private final ImageIcon warningIcon = new ImageIcon(TranslatablePanel.class.getResource("/org/sleuthkit/autopsy/images/warning16.png"));
 
     private final ContentComponent contentComponent;
-    private final Component rootComponent;
-    private final String origOptionText;
-    private final String translatedOptionText;
     private final TextTranslationService translationService;
     private final ThreadFactory translationThreadFactory = new ThreadFactoryBuilder().setNameFormat("translatable-panel-%d").build();
     private final ExecutorService executorService = Executors.newSingleThreadExecutor(translationThreadFactory);
@@ -180,6 +183,7 @@ class TranslatablePanel extends JPanel {
 
     private String content;
     private String contentDescriptor;
+    private boolean prevTranslateSelection;
 
     private volatile TranslatedText cachedTranslated;
     private volatile OnTranslation backgroundTask = null;
@@ -201,31 +205,37 @@ class TranslatablePanel extends JPanel {
     TranslatablePanel(ContentComponent contentComponent, String origOptionText, String translatedOptionText, String origContent,
             TextTranslationService translationService) {
         this.contentComponent = contentComponent;
-        this.rootComponent = contentComponent.getRootComponent();
-        this.origOptionText = origOptionText;
-        this.translatedOptionText = translatedOptionText;
         this.translationService = translationService;
 
         initComponents();
-        additionalInit();
+        additionalInit(contentComponent.getRootComponent(), origOptionText, translatedOptionText);
         setTranslationBarVisible();
         reset();
     }
     
 
 
+    /**
+     * @return  the cached translated text or returns null
+     */
     private TranslatedText getCachedTranslated() {
         synchronized (cachedTranslatedLock) {
             return cachedTranslated;
         }
     }
 
+    /**
+     * @param translated    the translated text to be cached
+     */
     private void setCachedTranslated(TranslatedText translated) {
         synchronized (cachedTranslatedLock) {
             this.cachedTranslated = translated;
         }
     }
 
+    /**
+     * if a translation worker is running, this is called to cancel the worker
+     */
     private void cancelPendingTranslation() {
         synchronized (backgroundTaskLock) {
             if (backgroundTask != null && !backgroundTask.isDone()) {
@@ -235,6 +245,9 @@ class TranslatablePanel extends JPanel {
         }
     }
 
+    /**
+     * runs a translation worker to translate the text
+     */
     private void runTranslationTask() {
         synchronized (backgroundTaskLock) {
             cancelPendingTranslation();
@@ -246,14 +259,24 @@ class TranslatablePanel extends JPanel {
         }
     }
 
+    /**
+     * resets the component to an empty state and sets the translation bar visibility
+     * based on whether there is a provider
+     */
     final void reset() {
         setTranslationBarVisible();
         setContent(null, null);
     }
 
+    /**
+     * sets the content for the component; this also clears the status
+     * @param content               the content for the panel
+     * @param contentDescriptor     the content descriptor to be used in error messages
+     */
     void setContent(String content, String contentDescriptor) {
         cancelPendingTranslation();
         this.translateComboBox.setSelectedIndex(0);
+        this.prevTranslateSelection = false;
         this.content = content;
         this.contentDescriptor = contentDescriptor;
         clearStatus();
@@ -274,23 +297,43 @@ class TranslatablePanel extends JPanel {
         return translationService.translate(input);
     }
 
+    /**
+     * clears the status bar
+     */
     private void clearStatus() {
         setStatus(null, false);
     }
 
+    /**
+     * sets the status bar message
+     * @param msg               the status bar message to show
+     * @param showWarningIcon   whether that status is a warning
+     */
     private synchronized void setStatus(String msg, boolean showWarningIcon) {
         statusLabel.setText(msg);
         statusLabel.setIcon(showWarningIcon ? warningIcon : null);
     }
 
+    /**
+     * sets the translation bar visibility based on whether or not there is a provided
+     */
     private void setTranslationBarVisible() {
         translationBar.setVisible(this.translationService.hasProvider());
     }
 
+    /**
+     * the child component provided in the constructor will have its content set to the string provided
+     * @param content   the content to display in the child component
+     */
     private void setChildComponentContent(String content) {
         setChildComponentContent(content, DEFAULT_ORIENTATION);
     }
 
+    /**
+     * the child component provided in the constructor will have its content set to the string provided
+     * @param content   the content to display in the child component
+     * @param orientation the orientation for the text
+     */
     @Messages({"# {0} - exception message", "TranslatablePanel.onSetContentError.text=There was an error displaying the text: {0}"})
     private synchronized void setChildComponentContent(String content, ComponentOrientation orientation) {
         SwingUtilities.invokeLater(() -> {
@@ -302,26 +345,38 @@ class TranslatablePanel extends JPanel {
         });
     }
 
-    private void additionalInit() {
-        add(this.rootComponent, java.awt.BorderLayout.CENTER);
+    /**
+     * items that are programmatically initialized
+     */
+    private void additionalInit(Component rootComponent, String origOptionText, String translatedOptionText) {
+        add(rootComponent, java.awt.BorderLayout.CENTER);
         translateComboBox.removeAllItems();
-        translateComboBox.addItem(new TranslateOption(this.origOptionText, false));
-        translateComboBox.addItem(new TranslateOption(this.translatedOptionText, true));
+        translateComboBox.addItem(new TranslateOption(origOptionText, false));
+        translateComboBox.addItem(new TranslateOption(translatedOptionText, true));
     }
 
+    /**
+     * when the combo box choice is selected, this method is fired
+     * @param translateOption   the current translate option
+     */
     private void handleComboBoxChange(TranslateOption translateOption) {
-        cancelPendingTranslation();
-        clearStatus();
+        boolean curTranslateSelection = translateOption.shouldTranslate();
+        if (curTranslateSelection != this.prevTranslateSelection) {
+            this.prevTranslateSelection = curTranslateSelection;
+            
+            cancelPendingTranslation();
+            clearStatus();
 
-        if (translateOption.shouldTranslate()) {
-            TranslatedText translated = getCachedTranslated();
-            if (translated != null) {
-                setChildComponentContent(translated.getText(), translated.getOrientation());
+            if (curTranslateSelection) {
+                TranslatedText translated = getCachedTranslated();
+                if (translated != null) {
+                    setChildComponentContent(translated.getText(), translated.getOrientation());
+                } else {
+                    runTranslationTask();
+                }
             } else {
-                runTranslationTask();
-            }
-        } else {
-            setChildComponentContent(content);
+                setChildComponentContent(content);
+            }    
         }
     }
 
diff --git a/Core/src/org/sleuthkit/autopsy/texttranslation/ui/TranslateTextTask.java b/Core/src/org/sleuthkit/autopsy/texttranslation/ui/TranslateTextTask.java
index 70fe09f4cf..2932cf5d19 100644
--- a/Core/src/org/sleuthkit/autopsy/texttranslation/ui/TranslateTextTask.java
+++ b/Core/src/org/sleuthkit/autopsy/texttranslation/ui/TranslateTextTask.java
@@ -36,7 +36,7 @@ import org.sleuthkit.autopsy.texttranslation.TranslationException;
 /**
  * abstract class for translating text and displaying to the user
  */
-public abstract class TranslateTextTask extends SwingWorker<TranslateTextTask.Result, Void> {
+public abstract class TranslateTextTask extends SwingWorker<TranslateTextTask.TranslateResult, Void> {
 
     private static final Logger logger = Logger.getLogger(TranslatedTextViewer.class.getName());
 
@@ -46,21 +46,21 @@ public abstract class TranslateTextTask extends SwingWorker<TranslateTextTask.Re
     /**
      * as a result of running and processing the translation
      */
-    public static class Result {
+    public static class TranslateResult {
 
         private final String errorMessage;
         private final String result;
         private final boolean successful;
 
-        public static Result error(String message) {
-            return new Result(null, message, false);
+        public static TranslateResult error(String message) {
+            return new TranslateResult(null, message, false);
         }
 
-        public static Result success(String content) {
-            return new Result(content, null, true);
+        public static TranslateResult success(String content) {
+            return new TranslateResult(content, null, true);
         }
 
-        private Result(String result, String errorMessage, boolean successful) {
+        private TranslateResult(String result, String errorMessage, boolean successful) {
             this.successful = successful;
             this.errorMessage = errorMessage;
             this.result = result;
@@ -91,15 +91,42 @@ public abstract class TranslateTextTask extends SwingWorker<TranslateTextTask.Re
         this.contentDescriptor = fileDescriptor;
     }
 
+    /**
+     * retrieves the original text content to be translated
+     * @return      the original text content
+     * @throws IOException
+     * @throws InterruptedException
+     * @throws IllegalStateException 
+     */
     protected abstract String retrieveText() throws IOException, InterruptedException, IllegalStateException;
 
+    /**
+     * method to be overridden when a translated text result is received
+     * @param text          the text to display
+     * @param orientation   the orientation of the text
+     * @param font          the font style (returns plain)
+     */
     protected abstract void onTextDisplay(String text, ComponentOrientation orientation, int font);
 
+    /**
+     * when a progress result is received, this method is called
+     * this method can be overridden depending on the scenario but defaults to just displaying using onTextDisplay
+     * @param text          the text of the status update
+     * @param orientation   the orientation for the status
+     * @param font          the font style of the status
+     */
     protected void onProgressDisplay(String text, ComponentOrientation orientation, int font) {
         // default to normal display unless overridden
         onTextDisplay(text, orientation, font);
     }
 
+    /**
+     * when an error result is received, this method is called
+     * this method can be overridden depending on the scenario but defaults to just displaying using onTextDisplay
+     * @param text          the text of the error
+     * @param orientation   the orientation for the error
+     * @param font          the font style of the error
+     */
     protected void onErrorDisplay(String text, ComponentOrientation orientation, int font) {
         // default to normal display unless overridden
         onTextDisplay(text, orientation, font);
@@ -112,7 +139,7 @@ public abstract class TranslateTextTask extends SwingWorker<TranslateTextTask.Re
         "# {0} - exception message", "TranslatedContentViewer.translationException=An error occurred while translating the text ({0})."
     })
     @Override
-    public Result doInBackground() throws InterruptedException {
+    public TranslateResult doInBackground() throws InterruptedException {
         if (this.isCancelled()) {
             throw new InterruptedException();
         }
@@ -121,7 +148,7 @@ public abstract class TranslateTextTask extends SwingWorker<TranslateTextTask.Re
         try {
             fileText = retrieveText();
         } catch (IOException | IllegalStateException ex) {
-            return Result.error(ex.getMessage());
+            return TranslateResult.error(ex.getMessage());
         }
 
         if (this.isCancelled()) {
@@ -129,17 +156,23 @@ public abstract class TranslateTextTask extends SwingWorker<TranslateTextTask.Re
         }
 
         if (fileText == null || fileText.isEmpty()) {
-            return Result.error(Bundle.TranslatedContentViewer_fileHasNoText());
+            return TranslateResult.error(Bundle.TranslatedContentViewer_fileHasNoText());
         }
 
         if (!this.translateText) {
-            return Result.success(fileText);
+            return TranslateResult.success(fileText);
         }
 
         return translateRetrievedText(fileText);
     }
 
-    private Result translateRetrievedText(String fileText) throws InterruptedException {
+    /**
+     * final step in translation swing worker prior to being done(); translates the text if needed
+     * @param fileText          the text to translate
+     * @return                  the translated text
+     * @throws InterruptedException     if operation is canclled, an interrupted exception is thrown
+     */
+    private TranslateResult translateRetrievedText(String fileText) throws InterruptedException {
         SwingUtilities.invokeLater(() -> {
             onProgressDisplay(Bundle.TranslatedContentViewer_translatingText(), ComponentOrientation.LEFT_TO_RIGHT, Font.ITALIC);
         });
@@ -151,17 +184,17 @@ public abstract class TranslateTextTask extends SwingWorker<TranslateTextTask.Re
             }
 
             if (translation == null || translation.isEmpty()) {
-                return Result.error(Bundle.TranslatedContentViewer_emptyTranslation());
+                return TranslateResult.error(Bundle.TranslatedContentViewer_emptyTranslation());
             } else {
-                return Result.success(translation);
+                return TranslateResult.success(translation);
             }
 
         } catch (NoServiceProviderException ex) {
             logger.log(Level.WARNING, "Error translating text for file " + this.contentDescriptor, ex);
-            return Result.error(Bundle.TranslatedContentViewer_noServiceProvider());
+            return TranslateResult.error(Bundle.TranslatedContentViewer_noServiceProvider());
         } catch (TranslationException ex) {
             logger.log(Level.WARNING, "Error translating text for file " + this.contentDescriptor, ex);
-            return Result.error(Bundle.TranslatedContentViewer_translationException(ex.getMessage()));
+            return TranslateResult.error(Bundle.TranslatedContentViewer_translationException(ex.getMessage()));
         }
     }
     
@@ -169,7 +202,7 @@ public abstract class TranslateTextTask extends SwingWorker<TranslateTextTask.Re
     @Override
     public void done() {
         try {
-            Result executionResult = get();
+            TranslateResult executionResult = get();
             if (this.isCancelled()) {
                 throw new InterruptedException();
             }