NameFinderME (Apache OpenNLP :: Core :: Runtime 3.0.0-M4 API)
Description: declaration: package: opennlp.tools.namefind, class: NameFinderME

Package opennlp.tools.namefind

# Class NameFinderME

java.lang.Object
opennlp.tools.namefind.NameFinderME

All Implemented Interfaces:
  `opennlp.tools.ml.Probabilistic`, `opennlp.tools.namefind.TokenNameFinder`

@ThreadSafe public class NameFinderME extends Object implements opennlp.tools.namefind.TokenNameFinder, opennlp.tools.ml.Probabilistic
A maximum-entropy-based `name finder` implementation.

A name finder instance is thread-safe. One instance can be shared across multiple threads to save memory.

Note: In container environments with classloader isolation (e.g. Jakarta EE), ensure instances do not outlive the application's lifecycle, as underlying components use `ThreadLocal` state that may pin the classloader.

See Also:
  - `Probabilistic`
  - `TokenNameFinder`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `CONTINUE`
  `static final int`
  `DEFAULT_BEAM_SIZE`
  `static final String`
  `OTHER`
  `static final String`
  `START`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `NameFinderME(TokenNameFinderModel model)`
  Initializes a `NameFinderME` with a `TokenNameFinderModel`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clearAdaptiveData()`
  `void`
  `clearThreadLocalState()`
  Releases the calling thread's per-thread state for this `NameFinderME` (the last decoded sequence stashed for `probs()` access, plus the additional-context slot held by `AdditionalContextFeatureGenerator`).
  `static opennlp.tools.util.Span[]`
  `dropOverlappingSpans(opennlp.tools.util.Span[] spans)`
  Removes `spans` with are intersecting or crossing in any way.
  `opennlp.tools.util.Span[]`
  `find(String[] tokens)`
  `opennlp.tools.util.Span[]`
  `find(String[] tokens, String[][] additionalContext)`
  Generates name tags for the given sequence, typically a sentence, returning `token spans` for any identified names.
  `double[]`
  `probs()`
  The sequence was determined based on the previous call to `find(String[])`.
  `void`
  `probs(double[] probs)`
  Populates the specified array with the probabilities of the last decoded sequence.
  `double[]`
  `probs(opennlp.tools.util.Span[] spans)`
  Retrieves an array of probabilities for each of the specified spans which is the arithmetic mean of the probabilities for each of the outcomes which make up the span.
  `static TokenNameFinderModel`
  `train(String languageCode, String type, opennlp.tools.util.ObjectStream<opennlp.tools.namefind.NameSample> samples, opennlp.tools.util.TrainingParameters params, TokenNameFinderFactory factory)`
  Starts a training of a `TokenNameFinderModel` with the given parameters.

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### DEFAULT_BEAM_SIZE

    public static final int DEFAULT_BEAM_SIZE
    See Also:
      - Constant Field Values

  - ### START

    public static final String START
    See Also:
      - Constant Field Values

  - ### CONTINUE

    public static final String CONTINUE
    See Also:
      - Constant Field Values

  - ### OTHER

    public static final String OTHER
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### NameFinderME

    public NameFinderME(TokenNameFinderModel model)
    Initializes a `NameFinderME` with a `TokenNameFinderModel`.
    Parameters:
      `model` - The `TokenNameFinderModel` to initialize with.

- ## Method Details

  - ### find

    public opennlp.tools.util.Span[] find(String[] tokens)
    Specified by:
      `find` in interface `opennlp.tools.namefind.TokenNameFinder`

  - ### find

    public opennlp.tools.util.Span[] find(String[] tokens, String[][] additionalContext)
    Generates name tags for the given sequence, typically a sentence, returning `token spans` for any identified names.
    Parameters:
      `tokens` - An array of the tokens or words of a sequence, typically a sentence.
      `additionalContext` - Features based on context outside of the sentence but which should also be used.
    Returns:
      An array of `token spans` for each of the names identified.

  - ### clearAdaptiveData

    public void clearAdaptiveData()
    Specified by:
      `clearAdaptiveData` in interface `opennlp.tools.namefind.TokenNameFinder`

  - ### probs

    public void probs(double[] probs)
    Populates the specified array with the probabilities of the last decoded sequence. The sequence was determined based on the previous call to `find(String[])`. The specified array should be at least as large as the number of tokens in the previous call to `find(String[])`.
    Parameters:
      `probs` - An array with the probabilities of the last decoded sequence.

  - ### probs

    public double[] probs()
    The sequence was determined based on the previous call to `find(String[])`.
    Specified by:
      `probs` in interface `opennlp.tools.ml.Probabilistic`
    Returns:
      an array with the same number of probabilities as tokens were sent to `find(String[])` when it was last called

  - ### probs

    public double[] probs(opennlp.tools.util.Span[] spans)
    Retrieves an array of probabilities for each of the specified spans which is the arithmetic mean of the probabilities for each of the outcomes which make up the span.
    Parameters:
      `spans` - The `spans` of the names for which probabilities are requested.
    Returns:
      An array of probabilities for each of the specified spans.

  - ### clearThreadLocalState

    public void clearThreadLocalState()
    Releases the calling thread's per-thread state for this `NameFinderME` (the last decoded sequence stashed for `probs()` access, plus the additional-context slot held by `AdditionalContextFeatureGenerator`).

    This is intentionally a per-thread, not a per-instance, operation: a single `NameFinderME` is typically shared across many pool threads, and each one owns an independent slot. Call this when a worker thread is being returned to a pool, or when the name finder is being disposed in a container with classloader isolation.

    Note that this does not release per-thread state inside the underlying `BeamSearch` cache or other feature generators in the pipeline; those live for the duration of the owning thread.

  - ### train

    public static TokenNameFinderModel train(String languageCode, String type, opennlp.tools.util.ObjectStream<opennlp.tools.namefind.NameSample> samples, opennlp.tools.util.TrainingParameters params, TokenNameFinderFactory factory) throws IOException
    Starts a training of a `TokenNameFinderModel` with the given parameters.
    Parameters:
      `languageCode` - The ISO conform language code.
      `type` - The type to use.
      `samples` - The `ObjectStream` of `NameSample` used as input for training.
      `params` - The `TrainingParameters` for the context of the training.
      `factory` - The `TokenNameFinderFactory` for creating related objects defined via `params`.
    Returns:
      A valid, trained `TokenNameFinderModel` instance.
    Throws:
      `IOException` - Thrown if IO errors occurred during training.

  - ### dropOverlappingSpans

    public static opennlp.tools.util.Span[] dropOverlappingSpans(opennlp.tools.util.Span[] spans)
    Removes `spans` with are intersecting or crossing in any way.

    The following rules are used to remove the spans:
    Identical spans: The first span in the array after sorting it remains.
    Intersecting spans: The first span after sorting remains.
    Contained spans: All spans which are contained by another are removed.

    Parameters:
      `spans` - The input `spans`.
    Returns:
      The resulting non-overlapping `spans`.