Monitor (Lucene 10.5.0 monitor API)
Description: declaration: package: org.apache.lucene.monitor, class: Monitor

Package org.apache.lucene.monitor

# Class Monitor

java.lang.Object
org.apache.lucene.monitor.Monitor

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`

public class Monitor extends Object implements Closeable
A Monitor contains a set of `Query` objects with associated IDs, and efficiently matches them against sets of `Document` objects.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final record`
  `Monitor.QueryCacheStats`
  Statistics for the query cache and query index

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final Presearcher`
  `presearcher`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Monitor(Analyzer analyzer)`
  Create a non-persistent Monitor instance with the default term-filtering Presearcher
  `Monitor(Analyzer analyzer, MonitorConfiguration config)`
  Create a new Monitor instance with a specific configuration
  `Monitor(Analyzer analyzer, Presearcher presearcher)`
  Create a new non-persistent Monitor instance
  `Monitor(Analyzer analyzer, Presearcher presearcher, MonitorConfiguration configuration)`
  Create a new Monitor instance

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addQueryIndexUpdateListener(MonitorUpdateListener listener)`
  Register a `MonitorUpdateListener` that will be notified whenever changes are made to the Monitor's queryindex
  `void`
  `clear()`
  Delete all queries from the monitor
  `void`
  `close()`
  `<T extends QueryMatch>
  PresearcherMatches<T>`
  `debug(Document[] docs, MatcherFactory<T> factory)`
  Match a DocumentBatch against the queries stored in the Monitor, also returning information about which queries were selected by the presearcher, and why.
  `<T extends QueryMatch>
  PresearcherMatches<T>`
  `debug(Document doc, MatcherFactory<T> factory)`
  Match a single `Document` against the queries stored in the Monitor, also returning information about which queries were selected by the presearcher, and why.
  `void`
  `deleteById(String... queryIds)`
  Delete queries from the monitor by ID
  `void`
  `deleteById(List<String> queryIds)`
  Delete queries from the monitor by ID
  `int`
  `getDisjunctCount()`
  `MonitorQuery`
  `getQuery(String queryId)`
  Get the MonitorQuery for a given query id
  `Monitor.QueryCacheStats`
  `getQueryCacheStats()`
  `int`
  `getQueryCount()`
  `Set<String>`
  `getQueryIds()`
  `<T extends QueryMatch>
  MultiMatchingQueries<T>`
  `match(Document[] docs, MatcherFactory<T> factory)`
  Match an array of `Document`s against the queryindex, calling a `CandidateMatcher` produced by the supplied `MatcherFactory` for each possible matching query.
  `<T extends QueryMatch>
  MatchingQueries<T>`
  `match(Document doc, MatcherFactory<T> factory)`
  Match a single `Document` against the queryindex, calling a `CandidateMatcher` produced by the supplied `MatcherFactory` for each possible matching query.
  `void`
  `purgeCache()`
  Remove unused queries from the query cache.
  `void`
  `register(Iterable<MonitorQuery> queries)`
  Add new queries to the monitor
  `void`
  `register(MonitorQuery... queries)`
  Add new queries to the monitor

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

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

- ## Field Details

  - ### presearcher

    protected final Presearcher presearcher

- ## Constructor Details

  - ### Monitor

    public Monitor(Analyzer analyzer) throws IOException
    Create a non-persistent Monitor instance with the default term-filtering Presearcher
    Parameters:
      `analyzer` - to analyze `Document`s at match time
    Throws:
      `IOException`

  - ### Monitor

    public Monitor(Analyzer analyzer, Presearcher presearcher) throws IOException
    Create a new non-persistent Monitor instance
    Parameters:
      `analyzer` - to analyze `Document`s at match time
      `presearcher` - the presearcher to use
    Throws:
      `IOException`

  - ### Monitor

    public Monitor(Analyzer analyzer, MonitorConfiguration config) throws IOException
    Create a new Monitor instance with a specific configuration
    Parameters:
      `analyzer` - to analyze `Document`s at match time
      `config` - the configuration
    Throws:
      `IOException`

  - ### Monitor

    public Monitor(Analyzer analyzer, Presearcher presearcher, MonitorConfiguration configuration) throws IOException
    Create a new Monitor instance
    Parameters:
      `analyzer` - to analyze `Document`s at match time
      `presearcher` - the presearcher to use
      `configuration` - the configuration
    Throws:
      `IOException`

- ## Method Details

  - ### addQueryIndexUpdateListener

    public void addQueryIndexUpdateListener(MonitorUpdateListener listener)
    Register a `MonitorUpdateListener` that will be notified whenever changes are made to the Monitor's queryindex
    Parameters:
      `listener` - listener to register

  - ### getQueryCacheStats

    public Monitor.QueryCacheStats getQueryCacheStats() throws IOException
    Returns:
      Statistics for the internal query index and cache
    Throws:
      `IOException`

  - ### purgeCache

    public void purgeCache() throws IOException
    Remove unused queries from the query cache.

    This is normally called from a background thread at a rate set by configurePurgeFrequency().

    When Monitor is in read-only mode, cache is NEVER purged automatically you MUST call it when you want new changes.

    Throws:
      `IOException` - on IO errors

  - ### close

    public void close() throws IOException
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Throws:
      `IOException`

  - ### register

    public void register(Iterable<MonitorQuery> queries) throws IOException
    Add new queries to the monitor
    Parameters:
      `queries` - the MonitorQueries to add
    Throws:
      `IOException`

  - ### register

    public void register(MonitorQuery... queries) throws IOException
    Add new queries to the monitor
    Parameters:
      `queries` - the MonitorQueries to add
    Throws:
      `IOException` - on IO errors

  - ### deleteById

    public void deleteById(List<String> queryIds) throws IOException
    Delete queries from the monitor by ID
    Parameters:
      `queryIds` - the IDs to delete
    Throws:
      `IOException` - on IO errors

  - ### deleteById

    public void deleteById(String... queryIds) throws IOException
    Delete queries from the monitor by ID
    Parameters:
      `queryIds` - the IDs to delete
    Throws:
      `IOException` - on IO errors

  - ### clear

    public void clear() throws IOException
    Delete all queries from the monitor
    Throws:
      `IOException` - on IO errors

  - ### match

    public <T extends QueryMatch> MultiMatchingQueries<T> match(Document[] docs, MatcherFactory<T> factory) throws IOException
    Match an array of `Document`s against the queryindex, calling a `CandidateMatcher` produced by the supplied `MatcherFactory` for each possible matching query.
    Type Parameters:
      `T` - the type of `QueryMatch` to return
    Parameters:
      `docs` - the DocumentBatch to match
      `factory` - a `MatcherFactory` to use to create a `CandidateMatcher` for the match run
    Returns:
      a `MatchingQueries` object summarizing the match run.
    Throws:
      `IOException` - on IO errors

  - ### match

    public <T extends QueryMatch> MatchingQueries<T> match(Document doc, MatcherFactory<T> factory) throws IOException
    Match a single `Document` against the queryindex, calling a `CandidateMatcher` produced by the supplied `MatcherFactory` for each possible matching query.
    Type Parameters:
      `T` - the type of `QueryMatch` to return
    Parameters:
      `doc` - the InputDocument to match
      `factory` - a `MatcherFactory` to use to create a `CandidateMatcher` for the match run
    Returns:
      a `MatchingQueries` object summarizing the match run.
    Throws:
      `IOException` - on IO errors

  - ### getQuery

    public MonitorQuery getQuery(String queryId) throws IOException
    Get the MonitorQuery for a given query id
    Parameters:
      `queryId` - the id of the query to get
    Returns:
      the MonitorQuery stored for this id, or null if not found
    Throws:
      `IOException` - on IO errors
      `IllegalStateException` - if queries are not stored in the queryindex

  - ### getDisjunctCount

    public int getDisjunctCount() throws IOException
    Returns:
      the number of queries (after decomposition) stored in this Monitor
    Throws:
      `IOException`

  - ### getQueryCount

    public int getQueryCount() throws IOException
    Returns:
      the number of queries stored in this Monitor
    Throws:
      `IOException` - on IO errors

  - ### getQueryIds

    public Set<String> getQueryIds() throws IOException
    Returns:
      the set of query ids of the queries stored in this Monitor
    Throws:
      `IOException` - on IO errors

  - ### debug

    public <T extends QueryMatch> PresearcherMatches<T> debug(Document[] docs, MatcherFactory<T> factory) throws IOException
    Match a DocumentBatch against the queries stored in the Monitor, also returning information about which queries were selected by the presearcher, and why.
    Type Parameters:
      `T` - the type of QueryMatch produced by the CandidateMatcher
    Parameters:
      `docs` - a DocumentBatch to match against the index
      `factory` - a `MatcherFactory` to use to create a `CandidateMatcher` for the match run
    Returns:
      a `PresearcherMatches` object containing debug information
    Throws:
      `IOException` - on IO errors

  - ### debug

    public <T extends QueryMatch> PresearcherMatches<T> debug(Document doc, MatcherFactory<T> factory) throws IOException
    Match a single `Document` against the queries stored in the Monitor, also returning information about which queries were selected by the presearcher, and why.
    Type Parameters:
      `T` - the type of QueryMatch produced by the CandidateMatcher
    Parameters:
      `doc` - an InputDocument to match against the index
      `factory` - a `MatcherFactory` to use to create a `CandidateMatcher` for the match run
    Returns:
      a `PresearcherMatches` object containing debug information
    Throws:
      `IOException` - on IO errors