net.sf.okapi.common.query

## Interface IQuery

- All Superinterfaces:
    java.lang.AutoCloseable, java.util.Iterator<QueryResult>
  All Known Subinterfaces:
    ITMQuery
  All Known Implementing Classes:
    BaseConnector

      public interface IQuery
      extends java.lang.AutoCloseable, java.util.Iterator<QueryResult>

  Provides the methods common to all query engines of translation resources that can be queried for translating text units.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `batchLeverage(java.util.List<ITextUnit> tus)` Leverages a batch of text units (segmented or not) based on the current settings.
    `java.util.List<java.util.List<QueryResult>>` | `batchQuery(java.util.List<TextFragment> fragments)` Starts a batch query for a given list of `TextFragment`s.
    `java.util.List<java.util.List<QueryResult>>` | `batchQueryText(java.util.List<java.lang.String> plainTexts)` Starts a batch query for a given list of plain texts.
    `void` | `clearAttributes()` Removes all attributes from this query engine.
    `void` | `close()` Closes this connector.
    `java.lang.String` | `getName()` Gets the name of the connector.
    `int` | `getNoQueryThreshold()` Gets the threshold for when to avoid a query.
    `IParameters` | `getParameters()` Gets the current parameters of this connector.
    `java.lang.String` | `getSettingsDisplay()` Gets a display representation of the current settings for this connector.
    `LocaleId` | `getSourceLanguage()` Gets the current source language for this query engine.
    `LocaleId` | `getTargetLanguage()` Gets the current target language for this query engine.
    `int` | `getWeight()` Get the weight for this connector.
    `boolean` | `hasNext()` Indicates of there is a hit available.
    `void` | `leverage(ITextUnit tu)` Leverages a text unit (segmented or not) based on the current settings.
    `QueryResult` | `next()` Gets the next hit for the last query.
    `void` | `open()` Opens this query engine.
    `int` | `query(java.lang.String plainText)` Starts a query for a give plain text.
    `int` | `query(TextFragment text)` Starts a query for a given text.
    `void` | `removeAttribute(java.lang.String name)` Removes a given attribute from this query engine.
    `void` | `setAttribute(java.lang.String name, java.lang.String value)` Sets an attribute for this query engine.
    `void` | `setLanguages(LocaleId sourceLocale, LocaleId targetLocale)` Sets the source and target languages for this query engine.
    `void` | `setNoQueryThreshold(int noQueryThreshold)` Sets the threshold for when to avoid executing a query.
    `void` | `setParameters(IParameters params)` Sets the parameters for opening and querying this connector.
    `void` | `setRootDirectory(java.lang.String rootDir)` Sets the root directory that may be used to replace the available ${rootDir} in the parameters of this object.
    `void` | `setWeight(int weight)` Set the relative weight of this `IQuery` connector as compared to other connectors.

    - ### Methods inherited from interface java.util.Iterator

      `forEachRemaining, remove`

- - ### Method Detail

    - #### getName

          java.lang.String getName()

      Gets the name of the connector.
      Returns:
        the name of the connector.

    - #### getSettingsDisplay

          java.lang.String getSettingsDisplay()

      Gets a display representation of the current settings for this connector. This can be a display of some of the parameters for example, or some explanations about default non-modifiable settings.
      Returns:
        a display representation of the current settings.

    - #### setLanguages

          void setLanguages(LocaleId sourceLocale,
                            LocaleId targetLocale)

      Sets the source and target languages for this query engine.
      Parameters:
        `sourceLocale` - Code of the source locale.
        `targetLocale` - Code of the target locale.

    - #### getSourceLanguage

          LocaleId getSourceLanguage()

      Gets the current source language for this query engine.
      Returns:
        Code of the source language.

    - #### getTargetLanguage

          LocaleId getTargetLanguage()

      Gets the current target language for this query engine.
      Returns:
        Code of the target language.

    - #### setAttribute

          void setAttribute(java.lang.String name,
                            java.lang.String value)

      Sets an attribute for this query engine.
      Parameters:
        `name` - name of the attribute.
        `value` - Value of the attribute.

    - #### removeAttribute

          void removeAttribute(java.lang.String name)

      Removes a given attribute from this query engine.
      Parameters:
        `name` - The name of the attribute to remove.

    - #### clearAttributes

          void clearAttributes()

      Removes all attributes from this query engine.

    - #### setParameters

          void setParameters(IParameters params)

      Sets the parameters for opening and querying this connector.
      Parameters:
        `params` - the parameters to set.

    - #### getParameters

          IParameters getParameters()

      Gets the current parameters of this connector.
      Returns:
        the current parameters of this connector or null if no parameters are used.

    - #### open

          void open()

      Opens this query engine.

    - #### close

          void close()

      Closes this connector.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`

    - #### query

          int query(java.lang.String plainText)

      Starts a query for a give plain text.
      Parameters:
        `plainText` - text to query.
      Returns:
        The number of hits for the given query.

    - #### query

          int query(TextFragment text)

      Starts a query for a given text.
      Parameters:
        `text` - The text to query.
      Returns:
        The number of hits for the given query.

    - #### leverage

          void leverage(ITextUnit tu)

      Leverages a text unit (segmented or not) based on the current settings. Any options or attributes needed must be set before calling this method.
      Parameters:
        `tu` - the text unit to leverage.

    - #### batchLeverage

          void batchLeverage(java.util.List<ITextUnit> tus)

      Leverages a batch of text units (segmented or not) based on the current settings. Any options or attributes needed must be set before calling this method.
      Parameters:
        `tus` - of the text unit to leverage.

    - #### batchQueryText

          java.util.List<java.util.List<QueryResult>> batchQueryText(java.util.List<java.lang.String> plainTexts)

      Starts a batch query for a given list of plain texts.
      Note that batchQueryText does not use hasNext and next methods. Callers must use the returned list directly.
      Parameters:
        `plainTexts` - list of the plain texts to translate.
      Returns:
        a list of lists of query result. Each list corresponds to a source text (in the same order)

    - #### batchQuery

          java.util.List<java.util.List<QueryResult>> batchQuery(java.util.List<TextFragment> fragments)

      Starts a batch query for a given list of `TextFragment`s. Some `IQuery` implementations are significantly faster when a using batch query.
      Note that batchQuery does not use hasNext and next methods. Callers must use the returned list directly.
      Parameters:
        `fragments` - list of the text fragments to translate.
      Returns:
        a list of lists of query result. Each list corresponds to a source text (in the same order)

    - #### hasNext

          boolean hasNext()

      Indicates of there is a hit available.
      Specified by:
        `hasNext` in interface `java.util.Iterator<QueryResult>`
      Returns:
        True if a hit is available, false if not.

    - #### next

          QueryResult next()

      Gets the next hit for the last query.
      Specified by:
        `next` in interface `java.util.Iterator<QueryResult>`
      Returns:
        A QueryResult object that holds the source and target text of the hit, or null if there is no more hit.

    - #### setRootDirectory

          void setRootDirectory(java.lang.String rootDir)

      Sets the root directory that may be used to replace the available ${rootDir} in the parameters of this object.
      Parameters:
        `rootDir` - the root directory.

    - #### setWeight

          void setWeight(int weight)

      Set the relative weight of this `IQuery` connector as compared to other connectors. Used to set `QueryResult.weight`.
      Parameters:
        `weight` - the new relative weight.

    - #### getWeight

          int getWeight()

      Get the weight for this connector.
      Returns:
        the weight for this connector

    - #### setNoQueryThreshold

          void setNoQueryThreshold(int noQueryThreshold)

      Sets the threshold for when to avoid executing a query.

      If the entry to leverage has already one candidate with a score equals or above this value, no query is performed. Use 101 to always allow the query.

      Parameters:
        `noQueryThreshold` - no-query threshold (a value between 0 and 101).

    - #### getNoQueryThreshold

          int getNoQueryThreshold()

      Gets the threshold for when to avoid a query.
      Returns:
        the current no-query threshold.