OPENNLP-855: New SentimentAnalysisParser

- adapts existing Sentiment code to OpenNLP 3.x module structures
- introduces SentimentDetector API interface

Author: mawiesne

opennlp-api/src/main/java/opennlp/tools/sentiment/SentimentDetector.java

@@ -0,0 +1,65 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package opennlp.tools.sentiment;
+
+import opennlp.tools.util.Span;
+
+public interface SentimentDetector {
+
+  /**
+   * Conducts a sentiment prediction for the specifed sentence.
+   *
+   * @param sentence The text to be analysed for its sentiment.
+   * @return The predicted sentiment.
+   */
+  String predict(String sentence);
+
+  /**
+   * Conducts a sentiment prediction for the specifed sentence.
+   *
+   * @param tokens The text to be analysed for its sentiment.
+   * @return The predicted sentiment.
+   */
+  String predict(String[] tokens);
+
+  /**
+   * Generates sentiment tags for the given sequence, typically a sentence,
+   * returning token spans for any identified sentiments.
+   *
+   * @param tokens
+   *          an array of the tokens or words of the sequence, typically a
+   *          sentence
+   * @return an array of spans for each of the names identified.
+   */
+  Span[] find(String[] tokens);
+
+  /**
+   * Generates sentiment tags for the given sequence, typically a sentence,
+   * returning token spans for any identified sentiments.
+   *
+   * @param tokens
+   *          an array of the tokens or words of the sequence, typically a
+   *          sentence.
+   * @param additionalContext
+   *          features which are based on context outside of the sentence but
+   *          which should also be used.
+   *
+   * @return an array of spans for each of the names identified.
+   */
+  Span[] find(String[] tokens, String[][] additionalContext);
+}

opennlp-tools/src/main/java/opennlp/tools/sentiment/SentimentEvaluationMonitor.java renamed to opennlp-api/src/main/java/opennlp/tools/sentiment/SentimentEvaluationMonitor.java

@@ -20,9 +20,10 @@
 import opennlp.tools.util.eval.EvaluationMonitor;
 
 /**
- * Evaluation Monitor to be used by the evaluator
+ * An sentiment specific {@link EvaluationMonitor} to be used by the evaluator.
+ *
+ * @see SentimentSample
  */
-public interface SentimentEvaluationMonitor
-    extends EvaluationMonitor<SentimentSample> {
+public interface SentimentEvaluationMonitor extends EvaluationMonitor<SentimentSample> {
 
 }

opennlp-tools/src/main/java/opennlp/tools/sentiment/SentimentSample.java renamed to opennlp-api/src/main/java/opennlp/tools/sentiment/SentimentSample.java

@@ -17,12 +17,18 @@
 
 package opennlp.tools.sentiment;
 
+import java.io.Serial;
 import java.util.List;
 
+import opennlp.tools.commons.Sample;
+
 /**
  * Class for holding text used for sentiment analysis.
  */
-public class SentimentSample {
+public class SentimentSample implements Sample {
+
+  @Serial
+  private static final long serialVersionUID = 2477213313738337539L;
 
   private final String sentiment;
   private final List<String> sentence;

opennlp-tools/src/main/java/opennlp/tools/cmdline/sentiment/SentimentCrossValidatorTool.java renamed to opennlp-core/opennlp-cli/src/main/java/opennlp/tools/cmdline/sentiment/SentimentCrossValidatorTool.java

@@ -53,8 +53,7 @@ protected SentimentEvaluationErrorListener(OutputStream outputStream) {
    *          the sentiment sampple prediction
    */
   @Override
-  public void misclassified(SentimentSample reference,
-      SentimentSample prediction) {
+  public void misclassified(SentimentSample reference, SentimentSample prediction) {
     printError(new String[] { reference.getSentiment() },
         new String[] { prediction.getSentiment() }, reference, prediction,
         reference.getSentence());

opennlp-tools/src/main/java/opennlp/tools/cmdline/sentiment/SentimentDetailedFMeasureListener.java renamed to opennlp-core/opennlp-cli/src/main/java/opennlp/tools/cmdline/sentiment/SentimentDetailedFMeasureListener.java

@@ -20,8 +20,8 @@
 import java.io.IOException;
 
 import opennlp.tools.cmdline.ArgumentParser;
-import opennlp.tools.cmdline.CmdLineUtil;
 import opennlp.tools.cmdline.StreamFactoryRegistry;
+import opennlp.tools.cmdline.TerminateToolException;
 import opennlp.tools.cmdline.params.BasicFormatParams;
 import opennlp.tools.sentiment.SentimentSample;
 import opennlp.tools.sentiment.SentimentSampleStream;
@@ -47,37 +47,33 @@ protected SentimentSampleStreamFactory(Class<P> params) {
   }
 
   /**
-   * Creates a sentiment sample stream factory
+   * Creates a sentiment sample stream.
    *
    * @param args
    *          the necessary arguments
-   * @return SentimentSample stream (factory)
+   * @return A {@link SentimentSample} stream.
    */
   @Override
   public ObjectStream<SentimentSample> create(String[] args) {
-    BasicFormatParams params = ArgumentParser.parse(args,
-        BasicFormatParams.class);
+    BasicFormatParams params = ArgumentParser.parse(args, BasicFormatParams.class);
 
-    CmdLineUtil.checkInputFile("Data", params.getData());
-    InputStreamFactory sampleDataIn = CmdLineUtil
-        .createInputStreamFactory(params.getData());
-    ObjectStream<String> lineStream = null;
+    FormatUtil.checkInputFile("Data", params.getData());
+    ObjectStream<String> lineStream;
     try {
-      lineStream = new PlainTextByLineStream(sampleDataIn,
-          params.getEncoding());
+      InputStreamFactory sampleDataIn = FormatUtil.createInputStreamFactory(params.getData());
+      lineStream = new PlainTextByLineStream(sampleDataIn, params.getEncoding());
     } catch (IOException ex) {
-      CmdLineUtil.handleCreateObjectStreamError(ex);
+      throw new TerminateToolException(-1,
+              "IO Error while creating an Input Stream: " + ex.getMessage(), ex);
     }
-
     return new SentimentSampleStream(lineStream);
   }
 
   /**
    * Registers a SentimentSample stream factory
    */
   public static void registerFactory() {
-    StreamFactoryRegistry.registerFactory(SentimentSample.class,
-        StreamFactoryRegistry.DEFAULT_FORMAT,
+    StreamFactoryRegistry.registerFactory(SentimentSample.class, StreamFactoryRegistry.DEFAULT_FORMAT,
         new SentimentSampleStreamFactory<>(BasicFormatParams.class));
   }