AttributeSource (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.util, class: AttributeSource

Package org.apache.lucene.util

# Class AttributeSource

java.lang.Object
org.apache.lucene.util.AttributeSource

Direct Known Subclasses:
  `TokenStream`

public class AttributeSource extends Object
An AttributeSource contains a list of different `AttributeImpl`s, and methods to add and get them. There can only be a single instance of an attribute in the same AttributeSource instance. This is ensured by passing in the actual type of the Attribute (Class<Attribute>) to the `addAttribute(Class)`, which then checks if an instance of that type is already present. If yes, it returns the instance, otherwise it creates a new instance and returns it.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `AttributeSource.State`
  This class holds the state of an AttributeSource.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AttributeSource()`
  An AttributeSource using the default attribute factory `AttributeFactory.DEFAULT_ATTRIBUTE_FACTORY`.
  `AttributeSource(AttributeFactory factory)`
  An AttributeSource using the supplied `AttributeFactory` for creating new `Attribute` instances.
  `AttributeSource(AttributeSource input)`
  An AttributeSource that uses the same attributes as the supplied one.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final <T extends Attribute>
  T`
  `addAttribute(Class<T> attClass)`
  The caller must pass in a Class<? extends Attribute> value.
  `final void`
  `addAttributeImpl(AttributeImpl att)`
  Expert: Adds a custom AttributeImpl instance with one or more Attribute interfaces.
  `final AttributeSource.State`
  `captureState()`
  Captures the state of all Attributes.
  `final void`
  `clearAttributes()`
  Resets all Attributes in this AttributeSource by calling `AttributeImpl.clear()` on each Attribute implementation.
  `final AttributeSource`
  `cloneAttributes()`
  Performs a clone of all `AttributeImpl` instances returned in a new `AttributeSource` instance.
  `final void`
  `copyTo(AttributeSource target)`
  Copies the contents of this `AttributeSource` to the given target `AttributeSource`.
  `final void`
  `endAttributes()`
  Resets all Attributes in this AttributeSource by calling `AttributeImpl.end()` on each Attribute implementation.
  `boolean`
  `equals(Object obj)`
  `final <T extends Attribute>
  T`
  `getAttribute(Class<T> attClass)`
  Returns the instance of the passed in Attribute contained in this AttributeSource
  `final Iterator<Class<? extends Attribute>>`
  `getAttributeClassesIterator()`
  Returns a new iterator that iterates the attribute classes in the same order they were added in.
  `final AttributeFactory`
  `getAttributeFactory()`
  returns the used AttributeFactory.
  `final Iterator<AttributeImpl>`
  `getAttributeImplsIterator()`
  Returns a new iterator that iterates all unique Attribute implementations.
  `final boolean`
  `hasAttribute(Class<? extends Attribute> attClass)`
  The caller must pass in a Class<? extends Attribute> value.
  `final boolean`
  `hasAttributes()`
  Returns true, iff this AttributeSource has any attributes
  `int`
  `hashCode()`
  `final String`
  `reflectAsString(boolean prependAttClass)`
  This method returns the current attribute values as a string in the following format by calling the `reflectWith(AttributeReflector)` method: iff `prependAttClass=true`: `"AttributeClass#key=value,AttributeClass#key=value"` iff `prependAttClass=false`: `"key=value,key=value"`
  `final void`
  `reflectWith(AttributeReflector reflector)`
  This method is for introspection of attributes, it should simply add the key/values this AttributeSource holds to the given `AttributeReflector`.
  `final void`
  `removeAllAttributes()`
  Removes all attributes and their implementations from this AttributeSource.
  `final void`
  `restoreState(AttributeSource.State state)`
  Restores this state by copying the values of all attribute implementations that this state contains into the attributes implementations of the targetStream.
  `String`
  `toString()`
  Returns a string consisting of the class's simple name, the hex representation of the identity hash code, and the current reflection of all attributes.

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

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### AttributeSource

    public AttributeSource()
    An AttributeSource using the default attribute factory `AttributeFactory.DEFAULT_ATTRIBUTE_FACTORY`.

  - ### AttributeSource

    public AttributeSource(AttributeSource input)
    An AttributeSource that uses the same attributes as the supplied one.

  - ### AttributeSource

    public AttributeSource(AttributeFactory factory)
    An AttributeSource using the supplied `AttributeFactory` for creating new `Attribute` instances.

- ## Method Details

  - ### getAttributeFactory

    public final AttributeFactory getAttributeFactory()
    returns the used AttributeFactory.

  - ### getAttributeClassesIterator

    public final Iterator<Class<? extends Attribute>> getAttributeClassesIterator()
    Returns a new iterator that iterates the attribute classes in the same order they were added in.

  - ### getAttributeImplsIterator

    public final Iterator<AttributeImpl> getAttributeImplsIterator()
    Returns a new iterator that iterates all unique Attribute implementations. This iterator may contain less entries that `getAttributeClassesIterator()`, if one instance implements more than one Attribute interface.

  - ### addAttributeImpl

    public final void addAttributeImpl(AttributeImpl att)
    Expert: Adds a custom AttributeImpl instance with one or more Attribute interfaces.

    NOTE: It is not guaranteed, that `att` is added to the `AttributeSource`, because the provided attributes may already exist. You should always retrieve the wanted attributes using `getAttribute(java.lang.Class<T>)` after adding with this method and cast to your class. The recommended way to use custom implementations is using an `AttributeFactory`.

    This method will only add the Attribute interfaces directly implemented by the class and its super classes.

  - ### addAttribute

    public final <T extends Attribute> T addAttribute(Class<T> attClass)
    The caller must pass in a Class<? extends Attribute> value. This method first checks if an instance of that class is already in this AttributeSource and returns it. Otherwise a new instance is created, added to this AttributeSource and returned.

  - ### hasAttributes

    public final boolean hasAttributes()
    Returns true, iff this AttributeSource has any attributes

  - ### hasAttribute

    public final boolean hasAttribute(Class<? extends Attribute> attClass)
    The caller must pass in a Class<? extends Attribute> value. Returns true, iff this AttributeSource contains the passed-in Attribute.

  - ### getAttribute

    public final <T extends Attribute> T getAttribute(Class<T> attClass)
    Returns the instance of the passed in Attribute contained in this AttributeSource

    The caller must pass in a Class<? extends Attribute> value.

    Returns:
      instance of the passed in Attribute, or `null` if this AttributeSource does not contain the Attribute. It is recommended to always use `addAttribute(java.lang.Class<T>)` even in consumers of TokenStreams, because you cannot know if a specific TokenStream really uses a specific Attribute. `addAttribute(java.lang.Class<T>)` will automatically make the attribute available. If you want to only use the attribute, if it is available (to optimize consuming), use `hasAttribute(java.lang.Class<? extends org.apache.lucene.util.Attribute>)`.

  - ### clearAttributes

    public final void clearAttributes()
    Resets all Attributes in this AttributeSource by calling `AttributeImpl.clear()` on each Attribute implementation.

  - ### endAttributes

    public final void endAttributes()
    Resets all Attributes in this AttributeSource by calling `AttributeImpl.end()` on each Attribute implementation.

  - ### removeAllAttributes

    public final void removeAllAttributes()
    Removes all attributes and their implementations from this AttributeSource.

  - ### captureState

    public final AttributeSource.State captureState()
    Captures the state of all Attributes. The return value can be passed to `restoreState(org.apache.lucene.util.AttributeSource.State)` to restore the state of this or another AttributeSource.

    Be careful, this method comes with a cost of deep copying all attributes in the source.

  - ### restoreState

    public final void restoreState(AttributeSource.State state)
    Restores this state by copying the values of all attribute implementations that this state contains into the attributes implementations of the targetStream. The targetStream must contain a corresponding instance for each argument contained in this state (e.g. it is not possible to restore the state of an AttributeSource containing a TermAttribute into a AttributeSource using a Token instance as implementation).

    Note that this method does not affect attributes of the targetStream that are not contained in this state. In other words, if for example the targetStream contains an OffsetAttribute, but this state doesn't, then the value of the OffsetAttribute remains unchanged. It might be desirable to reset its value to the default, in which case the caller should first call `clearAttributes()` on the targetStream.

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### equals

    public boolean equals(Object obj)
    Overrides:
      `equals` in class `Object`

  - ### reflectAsString

    public final String reflectAsString(boolean prependAttClass)
    This method returns the current attribute values as a string in the following format by calling the `reflectWith(AttributeReflector)` method:
    - iff `prependAttClass=true`: `"AttributeClass#key=value,AttributeClass#key=value"`
    - iff `prependAttClass=false`: `"key=value,key=value"`
    See Also:
      - `reflectWith(AttributeReflector)`

  - ### reflectWith

    public final void reflectWith(AttributeReflector reflector)
    This method is for introspection of attributes, it should simply add the key/values this AttributeSource holds to the given `AttributeReflector`.

    This method iterates over all Attribute implementations and calls the corresponding `AttributeImpl.reflectWith(org.apache.lucene.util.AttributeReflector)` method.

    See Also:
      - `AttributeImpl.reflectWith(org.apache.lucene.util.AttributeReflector)`

  - ### cloneAttributes

    public final AttributeSource cloneAttributes()
    Performs a clone of all `AttributeImpl` instances returned in a new `AttributeSource` instance. This method can be used to e.g. create another TokenStream with exactly the same attributes (using `AttributeSource(AttributeSource)`). You can also use it as a (non-performant) replacement for `captureState()`, if you need to look into / modify the captured state.

  - ### copyTo

    public final void copyTo(AttributeSource target)
    Copies the contents of this `AttributeSource` to the given target `AttributeSource`. The given instance has to provide all `Attribute`s this instance contains. The actual attribute implementations must be identical in both `AttributeSource` instances; ideally both AttributeSource instances should use the same `AttributeFactory`. You can use this method as a replacement for `restoreState(org.apache.lucene.util.AttributeSource.State)`, if you use `cloneAttributes()` instead of `captureState()`.

  - ### toString

    public String toString()
    Returns a string consisting of the class's simple name, the hex representation of the identity hash code, and the current reflection of all attributes.
    Overrides:
      `toString` in class `Object`
    See Also:
      - `reflectAsString(boolean)`