BeamSearch (Apache OpenNLP :: Core :: ML :: Commons 3.0.0-M4 API)
Description: declaration: package: opennlp.tools.ml, class: BeamSearch

Package opennlp.tools.ml

# Class BeamSearch

java.lang.Object
opennlp.tools.ml.BeamSearch

All Implemented Interfaces:
  `AutoCloseable`, `opennlp.tools.ml.model.SequenceClassificationModel`

@ThreadSafe public class BeamSearch extends Object implements opennlp.tools.ml.model.SequenceClassificationModel, AutoCloseable
Performs k-best search over a sequence.

This is based on the description in Ratnaparkhi (1998), PhD diss, Univ. of Pennsylvania.

This implementation is thread-safe. The contexts cache and probability buffer are maintained per-thread via `ThreadLocal`.

Note: In container environments with classloader isolation (e.g. Jakarta EE), `ThreadLocal` state may pin the classloader. Ensure instances do not outlive the application's lifecycle, or call `ThreadLocal.remove()` on pooled threads.

See Also:
  - `Sequence`
  - `SequenceValidator`
  - `BeamSearchContextGenerator`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `BEAM_SIZE_PARAMETER`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BeamSearch(int size, opennlp.tools.ml.model.MaxentModel model)`
  Initializes a `BeamSearch` instance.
  `BeamSearch(int size, opennlp.tools.ml.model.MaxentModel model, int cacheSize)`
  Initializes a `BeamSearch` instance with an optional per-thread contexts cache.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<T> opennlp.tools.util.Sequence`
  `bestSequence(T[] sequence, Object[] additionalContext, opennlp.tools.util.BeamSearchContextGenerator<T> cg, opennlp.tools.util.SequenceValidator<T> validator)`
  `<T> opennlp.tools.util.Sequence[]`
  `bestSequences(int numSequences, T[] sequence, Object[] additionalContext, double minSequenceScore, opennlp.tools.util.BeamSearchContextGenerator<T> cg, opennlp.tools.util.SequenceValidator<T> validator)`
  `<T> opennlp.tools.util.Sequence[]`
  `bestSequences(int numSequences, T[] sequence, Object[] additionalContext, opennlp.tools.util.BeamSearchContextGenerator<T> cg, opennlp.tools.util.SequenceValidator<T> validator)`
  `void`
  `close()`
  Clears `ThreadLocal` state for the current thread only.
  `String[]`
  `getOutcomes()`

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

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

- ## Field Details

  - ### BEAM_SIZE_PARAMETER

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

- ## Constructor Details

  - ### BeamSearch

    public BeamSearch(int size, opennlp.tools.ml.model.MaxentModel model)
    Initializes a `BeamSearch` instance.
    Parameters:
      `size` - The size of the beam (k).
      `model` - The `MaxentModel` for assigning probabilities to the sequence outcomes.

  - ### BeamSearch

    public BeamSearch(int size, opennlp.tools.ml.model.MaxentModel model, int cacheSize)
    Initializes a `BeamSearch` instance with an optional per-thread contexts cache.
    Parameters:
      `size` - The size of the beam (k).
      `model` - The `MaxentModel` for assigning probabilities to the sequence outcomes.
      `cacheSize` - The capacity of the per-thread contexts cache. Use `0` to disable only that cache; per-thread score buffers are still allocated so evaluation stays thread-safe (see `BeamSearch.CacheState`).

- ## Method Details

  - ### bestSequences

    public <T> opennlp.tools.util.Sequence[] bestSequences(int numSequences, T[] sequence, Object[] additionalContext, double minSequenceScore, opennlp.tools.util.BeamSearchContextGenerator<T> cg, opennlp.tools.util.SequenceValidator<T> validator)
    Specified by:
      `bestSequences` in interface `opennlp.tools.ml.model.SequenceClassificationModel`

  - ### bestSequences

    public <T> opennlp.tools.util.Sequence[] bestSequences(int numSequences, T[] sequence, Object[] additionalContext, opennlp.tools.util.BeamSearchContextGenerator<T> cg, opennlp.tools.util.SequenceValidator<T> validator)
    Specified by:
      `bestSequences` in interface `opennlp.tools.ml.model.SequenceClassificationModel`

  - ### bestSequence

    public <T> opennlp.tools.util.Sequence bestSequence(T[] sequence, Object[] additionalContext, opennlp.tools.util.BeamSearchContextGenerator<T> cg, opennlp.tools.util.SequenceValidator<T> validator)
    Specified by:
      `bestSequence` in interface `opennlp.tools.ml.model.SequenceClassificationModel`

  - ### getOutcomes

    public String[] getOutcomes()
    Specified by:
      `getOutcomes` in interface `opennlp.tools.ml.model.SequenceClassificationModel`

  - ### close

    public void close()
    Clears `ThreadLocal` state for the current thread only. This is intentionally not a "shut down the `BeamSearch` instance" operation: a single `BeamSearch` is typically shared across many pool threads, and each one owns an independent `BeamSearch.CacheState` entry.

    Typical usage patterns:

    - Worker thread returning to a pool: call `close()` (or wrap a single decode call in try-with-resources) on each pool thread that has touched the instance.
    - Application shutdown / classloader unload: `close()` on a single thread is not sufficient to release every per-thread slot — those die with their owning threads, or must be cleared on each thread before the application classloader is released.

    Same lifecycle contract as `clearThreadLocalState()` on the seven ME classes.

    Specified by:
      `close` in interface `AutoCloseable`