OPENNLP-1757: Expose probs() method in thread-safe probabilistic ME classes (OpenNLP 2.x)

- adds Probabilistic marker interface to API
- adjusts classic ME related thread-safe classes to implement common probs() method via Probabilistic interface
- declares non-common probs-like methods 'getSentenceProbabilities' and 'getTokenProbabilities' deprecated as 'probs()' must now be implemented by all ME classes.
- improves JavaDoc along the path

Author: mawiesne

opennlp-tools/src/main/java/opennlp/tools/chunker/ChunkerME.java

@@ -24,6 +24,7 @@
 
 import opennlp.tools.ml.BeamSearch;
 import opennlp.tools.ml.EventTrainer;
+import opennlp.tools.ml.Probabilistic;
 import opennlp.tools.ml.SequenceTrainer;
 import opennlp.tools.ml.TrainerFactory;
 import opennlp.tools.ml.TrainerFactory.TrainerType;
@@ -40,10 +41,13 @@
 import opennlp.tools.util.TrainingParameters;
 
 /**
- * The class represents a maximum-entropy-based {@link Chunker}. This chunker can be used to
+ * The class represents a maximum-entropy-based {@link Chunker}. A chunker can be used to
  * find flat structures based on sequence inputs such as noun phrases or named entities.
+ *
+ * @see Chunker
+ * @see Probabilistic
  */
-public class ChunkerME implements Chunker {
+public class ChunkerME implements Chunker, Probabilistic {
 
   public static final int DEFAULT_BEAM_SIZE = 10;
 
@@ -128,12 +132,13 @@ public void probs(double[] probs) {
   }
 
   /**
-   * Returns an array with the probabilities of the last decoded sequence. The
-   * sequence was determined based on the previous call to {@link #chunk(String[], String[])}.
+   * {@inheritDoc}
+   * The sequence was determined based on the previous call to {@link #chunk(String[], String[])}.
    *
    * @return An array with the same number of probabilities as tokens when
    *         {@link ChunkerME#chunk(String[], String[])} was last called.
    */
+  @Override
   public double[] probs() {
     return bestSequence.getProbs();
   }

opennlp-tools/src/main/java/opennlp/tools/chunker/ThreadSafeChunkerME.java

@@ -18,27 +18,30 @@
 package opennlp.tools.chunker;
 
 import opennlp.tools.commons.ThreadSafe;
+import opennlp.tools.ml.Probabilistic;
 import opennlp.tools.util.Sequence;
 import opennlp.tools.util.Span;
 
 /**
  * A thread-safe version of the {@link ChunkerME}. Using it is completely transparent.
  * You can use it in a single-threaded context as well, it only incurs a minimal overhead.
- *
- * @implNote
+ * <p>
+ * <b>Note:</b><br/>
  * This implementation uses a {@link ThreadLocal}. Although the implementation is
  * lightweight because the model is not duplicated, if you have many long-running threads,
  * you may run into memory problems.
  * <p>
  * Be careful when using this in a Jakarta EE application, for example.
  * </p>
- * The user is responsible for clearing the {@link ThreadLocal}.
+ * The user is responsible for clearing the {@link ThreadLocal}
+ * via calling {@link #close()}.
  *
  * @see Chunker
  * @see ChunkerME
+ * @see Probabilistic
  */
 @ThreadSafe
-public class ThreadSafeChunkerME implements Chunker, AutoCloseable {
+public class ThreadSafeChunkerME implements Chunker, Probabilistic, AutoCloseable {
 
   private final ChunkerModel model;
 
@@ -88,4 +91,8 @@ public void close() {
     threadLocal.remove();
   }
 
+  @Override
+  public double[] probs() {
+    return getChunker().probs();
+  }
 }

opennlp-tools/src/main/java/opennlp/tools/langdetect/ThreadSafeLanguageDetectorME.java

@@ -22,15 +22,16 @@
 /**
  * A thread-safe version of the {@link LanguageDetectorME}. Using it is completely transparent.
  * You can use it in a single-threaded context as well, it only incurs a minimal overhead.
- *
- * @implNote
+ * <p>
+ * <b>Note:</b><br/>
  * This implementation uses a {@link ThreadLocal}. Although the implementation is
  * lightweight because the model is not duplicated, if you have many long-running threads,
  * you may run into memory problems.
  * <p>
  * Be careful when using this in a Jakarta EE application, for example.
  * </p>
- * The user is responsible for clearing the {@link ThreadLocal}.
+ * The user is responsible for clearing the {@link ThreadLocal}
+ * via calling {@link #close()}.
  *
  * @see LanguageDetector
  * @see LanguageDetectorME

opennlp-tools/src/main/java/opennlp/tools/lemmatizer/LemmatizerME.java

@@ -27,6 +27,7 @@
 import opennlp.tools.ml.BeamSearch;
 import opennlp.tools.ml.EventModelSequenceTrainer;
 import opennlp.tools.ml.EventTrainer;
+import opennlp.tools.ml.Probabilistic;
 import opennlp.tools.ml.SequenceTrainer;
 import opennlp.tools.ml.TrainerFactory;
 import opennlp.tools.ml.TrainerFactory.TrainerType;
@@ -50,8 +51,10 @@
  * Towards a Machine-Learning Architecture for Lexical Functional Grammar Parsing.
  * </a> PhD dissertation, Dublin City University
  *
+ * @see Lemmatizer
+ * @see Probabilistic
  */
-public class LemmatizerME implements Lemmatizer {
+public class LemmatizerME implements Lemmatizer, Probabilistic {
 
   public static final int LEMMA_NUMBER = 29;
   public static final int DEFAULT_BEAM_SIZE = 3;
@@ -100,8 +103,7 @@ public String[] lemmatize(String[] toks, String[] tags) {
   }
 
   @Override
-  public List<List<String>> lemmatize(List<String> toks,
-      List<String> tags) {
+  public List<List<String>> lemmatize(List<String> toks, List<String> tags) {
     String[] tokens = toks.toArray(new String[0]);
     String[] posTags = tags.toArray(new String[0]);
     String[][] allLemmas = predictLemmas(LEMMA_NUMBER, tokens, posTags);
@@ -225,13 +227,15 @@ public void probs(double[] probs) {
   }
 
   /**
-   * Returns an array with the probabilities of the last decoded sequence.
+   * {@inheritDoc}
+   *
    * The sequence was determined based on the previous call to
    * {@link #lemmatize(String[], String[])}.
    *
    * @return An array with the same number of probabilities as tokens were sent to
    *         {@link #lemmatize(String[], String[])} when it was last called.
    */
+  @Override
   public double[] probs() {
     return bestSequence.getProbs();
   }

opennlp-tools/src/main/java/opennlp/tools/lemmatizer/ThreadSafeLemmatizerME.java

@@ -20,25 +20,27 @@
 import java.util.List;
 
 import opennlp.tools.commons.ThreadSafe;
+import opennlp.tools.ml.Probabilistic;
 
 /**
  * A thread-safe version of the {@link LemmatizerME}. Using it is completely transparent.
  * You can use it in a single-threaded context as well, it only incurs a minimal overhead.
- *
- * @implNote
+ * <p>
+ * <b>Note:</b><br/>
  * This implementation uses a {@link ThreadLocal}. Although the implementation is
  * lightweight because the model is not duplicated, if you have many long-running threads,
  * you may run into memory problems.
  * <p>
  * Be careful when using this in a Jakarta EE application, for example.
  * </p>
- * The user is responsible for clearing the {@link ThreadLocal}.
+ * The user is responsible for clearing the {@link ThreadLocal}
+ * via calling {@link #close()}.
  *
  * @see Lemmatizer
  * @see LemmatizerME
  */
 @ThreadSafe
-public class ThreadSafeLemmatizerME implements Lemmatizer, AutoCloseable {
+public class ThreadSafeLemmatizerME implements Lemmatizer, Probabilistic, AutoCloseable {
 
   private final LemmatizerModel model;
 
@@ -73,6 +75,11 @@ public List<List<String>> lemmatize(List<String> toks, List<String> tags) {
     return getLemmatizer().lemmatize(toks, tags);
   }
 
+  @Override
+  public double[] probs() {
+    return getLemmatizer().probs();
+  }
+
   @Override
   public void close() {
     threadLocal.remove();

opennlp-tools/src/main/java/opennlp/tools/ml/Probabilistic.java

@@ -0,0 +1,32 @@
+/*
+ * 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.ml;
+
+/**
+ * A marker interface for classes with probabilistic capabilities.
+ */
+public interface Probabilistic {
+
+  /**
+   * Retrieves the probabilities of the last decoded sequence.
+   *
+   * @return An array with the same number of probabilities as tokens were sent to
+   *         the computational method when it was last called.
+   */
+  double[] probs();
+}

opennlp-tools/src/main/java/opennlp/tools/namefind/NameFinderME.java

@@ -30,6 +30,7 @@
 import opennlp.tools.ml.BeamSearch;
 import opennlp.tools.ml.EventModelSequenceTrainer;
 import opennlp.tools.ml.EventTrainer;
+import opennlp.tools.ml.Probabilistic;
 import opennlp.tools.ml.SequenceTrainer;
 import opennlp.tools.ml.TrainerFactory;
 import opennlp.tools.ml.TrainerFactory.TrainerType;
@@ -48,8 +49,11 @@
 
 /**
  * A maximum-entropy-based {@link TokenNameFinder name finder} implementation.
+ *
+ * @see Probabilistic
+ * @see TokenNameFinder
  */
-public class NameFinderME implements TokenNameFinder {
+public class NameFinderME implements TokenNameFinder, Probabilistic {
 
   private static final String[][] EMPTY = new String[0][0];
   public static final int DEFAULT_BEAM_SIZE = 3;
@@ -135,12 +139,14 @@ public void probs(double[] probs) {
   }
 
   /**
-   * Retrieves the probabilities of the last decoded sequence. The
-   * sequence was determined based on the previous call to {@link #find(String[])}.
+   * {@inheritDoc}
+   *
+   * The sequence was determined based on the previous call to {@link #find(String[])}.
    *
    * @return An array with the same number of probabilities as tokens were sent
    *         to {@link #find(String[])} when it was last called.
    */
+  @Override
   public double[] probs() {
     return bestSequence.getProbs();
   }

opennlp-tools/src/main/java/opennlp/tools/namefind/ThreadSafeNameFinderME.java

@@ -18,26 +18,28 @@
 package opennlp.tools.namefind;
 
 import opennlp.tools.commons.ThreadSafe;
+import opennlp.tools.ml.Probabilistic;
 import opennlp.tools.util.Span;
 
 /**
  * A thread-safe version of {@link NameFinderME}. Using it is completely transparent.
  * You can use it in a single-threaded context as well, it only incurs a minimal overhead.
- *
- * @implNote
+ * <p>
+ * <b>Note:</b><br/>
  * This implementation uses a {@link ThreadLocal}. Although the implementation is
  * lightweight because the model is not duplicated, if you have many long-running threads,
  * you may run into memory problems.
  * <p>
  * Be careful when using this in a Jakarta EE application, for example.
  * </p>
- * The user is responsible for clearing the {@link ThreadLocal}.
+ * The user is responsible for clearing the {@link ThreadLocal} via calling {@link #close()}.
  *
  * @see NameFinderME
+ * @see Probabilistic
  * @see TokenNameFinder
  */
 @ThreadSafe
-public class ThreadSafeNameFinderME implements TokenNameFinder, AutoCloseable {
+public class ThreadSafeNameFinderME implements TokenNameFinder, Probabilistic, AutoCloseable {
 
   private final TokenNameFinderModel model;
 
@@ -68,6 +70,11 @@ public Span[] find(String[] tokens) {
     return getNameFinder().find(tokens);
   }
 
+  @Override
+  public double[] probs() {
+    return getNameFinder().probs();
+  }
+
   @Override
   public void clearAdaptiveData() {
     getNameFinder().clearAdaptiveData();

opennlp-tools/src/main/java/opennlp/tools/postag/POSTaggerME.java

@@ -33,6 +33,7 @@
 import opennlp.tools.ml.BeamSearch;
 import opennlp.tools.ml.EventModelSequenceTrainer;
 import opennlp.tools.ml.EventTrainer;
+import opennlp.tools.ml.Probabilistic;
 import opennlp.tools.ml.SequenceTrainer;
 import opennlp.tools.ml.TrainerFactory;
 import opennlp.tools.ml.TrainerFactory.TrainerType;
@@ -59,8 +60,9 @@
  * @see POSModel
  * @see POSTagFormat
  * @see POSTagger
+ * @see Probabilistic
  */
-public class POSTaggerME implements POSTagger {
+public class POSTaggerME implements POSTagger, Probabilistic {
 
   private static final Logger logger = LoggerFactory.getLogger(POSTaggerME.class);
 
@@ -245,8 +247,14 @@ public void probs(double[] probs) {
   }
 
   /**
-   * @return An array with the probabilities for each tag of the last tagged sentence.
+   * {@inheritDoc}
+   *
+   * The sequence was determined based on the previous call to {@link #tag(String[])}.
+   *
+   * @return An array with the same number of probabilities as tokens were sent
+   *         to {@link #tag(String[])} when it was last called.
    */
+  @Override
   public double[] probs() {
     return bestSequence.getProbs();
   }

opennlp-tools/src/main/java/opennlp/tools/postag/ThreadSafePOSTaggerME.java

@@ -20,28 +20,31 @@
 import java.io.IOException;
 
 import opennlp.tools.commons.ThreadSafe;
+import opennlp.tools.ml.Probabilistic;
 import opennlp.tools.models.ModelType;
 import opennlp.tools.util.DownloadUtil;
 import opennlp.tools.util.Sequence;
 
 /**
  * A thread-safe version of the {@link POSTaggerME}. Using it is completely transparent.
  * You can use it in a single-threaded context as well, it only incurs a minimal overhead.
- *
- * @implNote
+ * <p>
+ * <b>Note:</b><br/>
  * This implementation uses a {@link ThreadLocal}. Although the implementation is
  * lightweight because the model is not duplicated, if you have many long-running threads,
  * you may run into memory problems.
  * <p>
  * Be careful when using this in a Jakarta EE application, for example.
  * </p>
- * The user is responsible for clearing the {@link ThreadLocal}.
+ * The user is responsible for clearing the {@link ThreadLocal}
+ * via calling {@link #close()}.
  *
  * @see POSTagger
  * @see POSTaggerME
+ * @see Probabilistic
  */
 @ThreadSafe
-public class ThreadSafePOSTaggerME implements POSTagger, AutoCloseable {
+public class ThreadSafePOSTaggerME implements POSTagger, Probabilistic, AutoCloseable {
 
   private final POSModel model;
 
@@ -122,6 +125,11 @@ public Sequence[] topKSequences(String[] sentence, Object[] additionaContext) {
     return getTagger().topKSequences(sentence, additionaContext);
   }
 
+  @Override
+  public double[] probs() {
+    return getTagger().probs();
+  }
+
   @Override
   public void close() {
     threadLocal.remove();