Extensions (Lucene 10.5.0 queryparser API)
Description: declaration: package: org.apache.lucene.queryparser.ext, class: Extensions

Package org.apache.lucene.queryparser.ext

# Class Extensions

java.lang.Object
org.apache.lucene.queryparser.ext.Extensions

public class Extensions extends Object
The `Extensions` class represents an extension mapping to associate `ParserExtension` instances with extension keys. An extension key is a string encoded into a Lucene standard query parser field symbol recognized by `ExtendableQueryParser`. The query parser passes each extension field token to `splitExtensionField(String, String)` to separate the extension key from the field identifier.

In addition to the key to extension mapping this class also defines the field name overloading scheme. `ExtendableQueryParser` uses the given extension to split the actual field name and extension key by calling `splitExtensionField(String, String)`. To change the order or the key / field name encoding scheme users can subclass `Extensions` to implement their own.

See Also:
  - `ExtendableQueryParser`
  - `ParserExtension`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final record`
  `Extensions.Pair<Cur,Cud>`
  This class represents a generic pair.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final char`
  `DEFAULT_EXTENSION_FIELD_DELIMITER`
  The default extension field delimiter character.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Extensions()`
  Creates a new `Extensions` instance with the `DEFAULT_EXTENSION_FIELD_DELIMITER` as a delimiter character.
  `Extensions(char extensionFieldDelimiter)`
  Creates a new `Extensions` instance

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(String key, ParserExtension extension)`
  Adds a new `ParserExtension` instance associated with the given key.
  `String`
  `buildExtensionField(String extensionKey)`
  Builds an extension field string from a given extension key and the default query field.
  `String`
  `buildExtensionField(String extensionKey, String field)`
  Builds an extension field string from a given extension key and the extensions field.
  `String`
  `escapeExtensionField(String extfield)`
  Escapes an extension field.
  `final ParserExtension`
  `getExtension(String key)`
  Returns the `ParserExtension` instance for the given key or `null` if no extension can be found for the key.
  `char`
  `getExtensionFieldDelimiter()`
  Returns the extension field delimiter
  `Extensions.Pair<String,String>`
  `splitExtensionField(String defaultField, String field)`
  Splits a extension field and returns the field / extension part as a `Extensions.Pair`.

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

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

- ## Field Details

  - ### DEFAULT_EXTENSION_FIELD_DELIMITER

    public static final char DEFAULT_EXTENSION_FIELD_DELIMITER
    The default extension field delimiter character. This constant is set to ':'
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### Extensions

    public Extensions()
    Creates a new `Extensions` instance with the `DEFAULT_EXTENSION_FIELD_DELIMITER` as a delimiter character.

  - ### Extensions

    public Extensions(char extensionFieldDelimiter)
    Creates a new `Extensions` instance
    Parameters:
      `extensionFieldDelimiter` - the extensions field delimiter character

- ## Method Details

  - ### add

    public void add(String key, ParserExtension extension)
    Adds a new `ParserExtension` instance associated with the given key.
    Parameters:
      `key` - the parser extension key
      `extension` - the parser extension

  - ### getExtension

    public final ParserExtension getExtension(String key)
    Returns the `ParserExtension` instance for the given key or `null` if no extension can be found for the key.
    Parameters:
      `key` - the extension key
    Returns:
      the `ParserExtension` instance for the given key or `null` if no extension can be found for the key.

  - ### getExtensionFieldDelimiter

    public char getExtensionFieldDelimiter()
    Returns the extension field delimiter
    Returns:
      the extension field delimiter

  - ### splitExtensionField

    public Extensions.Pair<String,String> splitExtensionField(String defaultField, String field)
    Splits a extension field and returns the field / extension part as a `Extensions.Pair`. This method tries to split on the first occurrence of the extension field delimiter, if the delimiter is not present in the string the result will contain a `null` value for the extension key and the given field string as the field value. If the given extension field string contains no field identifier the result pair will carry the given default field as the field value.
    Parameters:
      `defaultField` - the default query field
      `field` - the extension field string
    Returns:
      a `Extensions.Pair` with the field name as the `Extensions.Pair.cur` and the extension key as the `Extensions.Pair.cud`

  - ### escapeExtensionField

    public String escapeExtensionField(String extfield)
    Escapes an extension field. The default implementation is equivalent to `QueryParserBase.escape(String)`.
    Parameters:
      `extfield` - the extension field identifier
    Returns:
      the extension field identifier with all special chars escaped with a backslash character.

  - ### buildExtensionField

    public String buildExtensionField(String extensionKey)
    Builds an extension field string from a given extension key and the default query field. The default field and the key are delimited with the extension field delimiter character. This method makes no assumption about the order of the extension key and the field. By default the extension key is appended to the end of the returned string while the field is added to the beginning. Special Query characters are escaped in the result.

    Note: `Extensions` subclasses must maintain the contract between `buildExtensionField(String)` and `splitExtensionField(String, String)` where the latter inverts the former.

  - ### buildExtensionField

    public String buildExtensionField(String extensionKey, String field)
    Builds an extension field string from a given extension key and the extensions field. The field and the key are delimited with the extension field delimiter character. This method makes no assumption about the order of the extension key and the field. By default the extension key is appended to the end of the returned string while the field is added to the beginning. Special Query characters are escaped in the result.

    Note: `Extensions` subclasses must maintain the contract between `buildExtensionField(String, String)` and `splitExtensionField(String, String)` where the latter inverts the former.

    Parameters:
      `extensionKey` - the extension key
      `field` - the field to apply the extension on.
    Returns:
      escaped extension field identifier
    See Also:
      - `to use the default query field`