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 class` | `Monitor.QueryCacheStats` | Statistics for the query cache and query index

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected 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

    All Methods Instance Methods Concrete Methods
    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 Detail

    - #### presearcher

          protected final Presearcher presearcher

  - ### Constructor Detail

    - #### 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 Detail

    - #### 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