Package com.yahoo.search.result

Class Hit

java.lang.Object
com.yahoo.component.provider.FreezableClass
com.yahoo.component.provider.ListenableFreezableClass
com.yahoo.search.result.Hit
All Implemented Interfaces:
com.yahoo.component.provider.Freezable, com.yahoo.component.provider.ListenableFreezable, com.yahoo.processing.response.Data, Cloneable, Comparable<Hit>
Direct Known Subclasses:
DefaultErrorHit, FastHit, GroupingListHit, HitGroup
public class Hit extends com.yahoo.component.provider.ListenableFreezableClass implements com.yahoo.processing.response.Data, Comparable<Hit>, Cloneable

An item in the result of executing a query.

Hits may be of the meta type, meaning that they contain some information about the query or result which does not represent a particular matched item. Meta hits are not counted in the hit count of the result, and should usually never be filtered out.

Some hit sources may produce hits which are not filled. A non-filled hit may miss some or all of its property values. To fill those, fill must be called on the search chain by the searcher which requires those properties. This mechanism allows initial filtering to be done of a lightweight version of the hits, which is cheaper if a significant number of hits are filtered out.

Do not cache this as it holds references to objects that should be garbage collected.

Author:
bratseth

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    Hit.RawUtf8Consumer
     

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    RANKFEATURES_FIELD
    The hit field used to store rank features
    static final String
    SDDOCNAME_FIELD
     

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Hit()
    Creates an (invalid) empty hit.
    protected
    Hit(Relevance relevance)
     
     
    Hit(String id)
    Creates a minimal valid hit having relevance 1
     
    Hit(String id, double relevance)
    Creates a minimal valid hit.
     
    Hit(String id, double relevance, Query query)
    Creates a minimal valid hit.
     
    Hit(String id, double relevance, String source)
    Creates a hit.
     
    Hit(String id, double relevance, String source, Query query)
    Creates a hit.
     
    Hit(String id, Query query)
    Creates a minimal valid hit having relevance 1
     
    Hit(String id, Relevance relevance)
    Creates a minimal valid hit.
     
    Hit(String id, Relevance relevance, Query query)
    Creates a minimal valid hit.
     
    Hit(String id, Relevance relevance, String source)
    Creates a hit.
     
    Hit(String id, Relevance relevance, String source, Query query)
    Creates a hit.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected final void
    assignId(com.yahoo.net.URI id)
    Assigns a new or changed id to this hit.
    HitField
    buildHitField(String key, boolean forceNoPreTokenize)
     
    void
    clearFields()
    Removes all fields of this
    Hit
    clone()
     
    protected void
    close()
    Releases the resources held by this, making it irreversibly unusable
    int
    compareTo(Hit other)
    Compares this hit to another hit
    boolean
    equals(Object other)
    Returns true if the argument is a hit having the same id as this
    FeatureData
    features()
    Returns the features computed for this hit.
    Iterator<Map.Entry<String,Object>>
    fieldIterator()
    Returns a modifiable iterator over the fields of this
    Set<String>
    fieldKeys()
    Returns the keys of the fields of this hit as a modifiable view.
    Map<String,Object>
    fields()
    Returns the fields of this as a read-only map.
    void
    forEachField(BiConsumer<String,Object> consumer)
    Receive a callback on the given object for each field in this hit.
    void
    forEachFieldAsRaw(Hit.RawUtf8Consumer consumer)
    Receive a callback on the given object for each field in this hit, where the callback will provide raw utf-8 byte data for strings whose data is already available at this form.
    String
    getDisplayId()
    Returns the id to display, or null to not display (render) the id.
    Object
    getField(String value)
    Returns a field value or null if not present
    Set<String>
    getFilled()
    Returns the set of summary classes for which this hit is filled as an unmodifiable set.
    com.yahoo.net.URI
    getId()
    Returns the hit id
    Query
    getQuery()
    Returns the query which produced this hit, or null if not known
    Relevance
    getRelevance()
    Returns the relevance of this hit
    Object
    getSearcherSpecificMetaData(Searcher searcher)
    Returns data attached to this hit for this searcher, or null if none
    String
    getSource()
    Returns the name of the source creating this hit
    protected boolean
    hasField(String name)
     
    protected boolean
    hasFields()
    Returns whether any fields are set in this
    int
    hashCode()
    Returns the hashCode of this hit: The hashcode of its id
    boolean
    isAuxiliary()
    Auxiliary hits are not counted towards the concrete number of hits to satisfy in the users request.
    boolean
    isCached()
    Returns whether this hit was added to this result from a cache or not
    boolean
    isFillable()
     
    boolean
    isFilled(String summaryClass)
    Returns whether this hit has been filled with the properties contained in the given summary class.
    boolean
    isMeta()
    Returns whether this is a concrete hit, containing content of the requested kind, or a meta hit containing information on the collection of hits, the query, the service and so on.
    Object
    removeField(String field)
    Removes a field from this
    com.yahoo.processing.Request
    request()
    Returns the query which produced this hit as a request, or null if not known
    void
    reserve(int minSize)
    Allocate room for the given number of fields to avoid resizing.
    void
    setAuxiliary(boolean auxiliary)
     
    void
    setCached(boolean cached)
    Sets whether this hit is returned from a cache.
    Object
    setField(String key, Object value)
    Sets the value of a field
    void
    setFillable()
    Tag this hit as fillable.
    void
    setFilled(String summaryClass)
    Register that this hit has been filled with properties using the given summary class.
    void
    setId(com.yahoo.net.URI id)
    Initializes the id of this hit.
    void
    setId(String id)
    Calls setId(new URI(id))
    void
    setMeta(boolean meta)
     
    final void
    setQuery(Query query)
    Sets the query which produced this.
    void
    setRelevance(double relevance)
    Does setRelevance(new Relevance(relevance)
    void
    setRelevance(Relevance relevance)
    Sets the relevance of this hit
    void
    setSearcherSpecificMetaData(Searcher searcher, Object data)
    Attach some data to this hit for this searcher
    void
    setSource(String source)
    Sets the name of the source creating this hit
    String
    toString()
     
    Set<String>
    types()
    Returns the types of this as a modifiable set.

    Methods inherited from class com.yahoo.component.provider.ListenableFreezableClass

    addFreezeListener, freeze

    Methods inherited from class com.yahoo.component.provider.FreezableClass

    ensureNotFrozen, isFrozen

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface com.yahoo.component.provider.Freezable

    freeze, isFrozen

    Methods inherited from interface com.yahoo.component.provider.ListenableFreezable

    addFreezeListener

  • Field Details

  • Constructor Details

    • Hit

      protected Hit()
      Creates an (invalid) empty hit. Id and relevance must be set before handoff

    • Hit

      protected Hit(Relevance relevance)

    • Hit

      public Hit(String id)
      Creates a minimal valid hit having relevance 1
      Parameters:
      id - the URI of a hit. This should be unique for this hit (but not for this object instance of course). For hit types refering to resources, this will be the full, valid url of the resource, for self-contained hits it is simply any unique string identification

    • Hit

      public Hit(String id, Query query)
      Creates a minimal valid hit having relevance 1
      Parameters:
      id - the URI of a hit. This should be unique for this hit (but not for this object instance of course). For hit types referring to resources, this will be the full, valid url of the resource, for self-contained hits it is simply any unique string identification
      query - the query having this as a hit

    • Hit

      public Hit(String id, double relevance)
      Creates a minimal valid hit.
      Parameters:
      id - the URI of a hit. This should be unique for this hit (but not for this object instance of course). For hit types referring to resources, this will be the full, valid url of the resource, for self-contained hits it is simply any unique string identification
      relevance - a relevance measure, preferably normalized between 0 and 1
      Throws:
      IllegalArgumentException - if the given relevance is not between 0 and 1

    • Hit

      public Hit(String id, double relevance, Query query)
      Creates a minimal valid hit.
      Parameters:
      id - the URI of a hit. This should be unique for this hit (but not for this object instance of course). For hit types referring to resources, this will be the full, valid url of the resource, for self-contained hits it is simply any unique string identification
      relevance - a relevance measure, preferably normalized between 0 and 1
      query - the query having this as a hit
      Throws:
      IllegalArgumentException - if the given relevance is not between 0 and 1

    • Hit

      public Hit(String id, Relevance relevance)
      Creates a minimal valid hit.
      Parameters:
      id - the URI of a hit. This should be unique for this hit (but not for this object instance of course). For hit types refering to resources, this will be the full, valid url of the resource, for self-contained hits it is simply any unique string identification
      relevance - the relevance of this hit
      Throws:
      IllegalArgumentException - if the given relevance is not between 0 and 1000

    • Hit

      public Hit(String id, Relevance relevance, Query query)
      Creates a minimal valid hit.
      Parameters:
      id - the URI of a hit. This should be unique for this hit (but not for this object instance of course). For hit types refering to resources, this will be the full, valid url of the resource, for self-contained hits it is simply any unique string identification
      relevance - the relevance of this hit
      query - the query having this as a hit
      Throws:
      IllegalArgumentException - if the given relevance is not between 0 and 1000

    • Hit

      public Hit(String id, double relevance, String source)
      Creates a hit.
      Parameters:
      id - the URI of a hit. This should be unique for this hit (but not for this object instance of course). For hit types refering to resources, this will be the full, valid url of the resource, for self-contained hits it is simply any unique string identification
      relevance - a relevance measure, preferably normalized between 0 and 1
      source - the name of the source of this hit, or null if no source is being specified

    • Hit

      public Hit(String id, double relevance, String source, Query query)
      Creates a hit.
      Parameters:
      id - the URI of a hit. This should be unique for this hit (but not for this object instance of course). For hit types refering to resources, this will be the full, valid url of the resource, for self-contained hits it is simply any unique string identification
      relevance - a relevance measure, preferably normalized between 0 and 1
      source - the name of the source of this hit, or null if no source is being specified
      query - the query having this as a hit

    • Hit

      public Hit(String id, Relevance relevance, String source)
      Creates a hit.
      Parameters:
      id - the URI of a hit. This should be unique for this hit (but not for this object instance of course). For hit types refering to resources, this will be the full, valid url of the resource, for self-contained hits it is simply any unique string identification
      relevance - the relevance of this hit
      source - the name of the source of this hit

    • Hit

      public Hit(String id, Relevance relevance, String source, Query query)
      Creates a hit.
      Parameters:
      id - the URI of a hit. This should be unique for this hit (but not for this object instance of course). For hit types refering to resources, this will be the full, valid url of the resource, for self-contained hits it is simply any unique string identification
      relevance - the relevance of this hit
      source - the name of the source of this hit
      query - the query having this as a hit

  • Method Details

    • setId

      public void setId(String id)
      Calls setId(new URI(id))

    • setId

      public void setId(com.yahoo.net.URI id)
      Initializes the id of this hit.
      Throws:
      NullPointerException - if the uri is null
      IllegalStateException - if the uri of this hit is already set

    • assignId

      protected final void assignId(com.yahoo.net.URI id)
      Assigns a new or changed id to this hit. As this is protected, reassigning isn't legal for Hits by default, however, subclasses may allow it using this method.

    • getId

      public com.yahoo.net.URI getId()
      Returns the hit id

    • getDisplayId

      public String getDisplayId()
      Returns the id to display, or null to not display (render) the id. This is useful to avoid displaying ids when they are not assigned explicitly but are just generated values for internal use. This default implementation returns the field DOCUMENT_ID if set, and getId().toString() otherwise.

    • setRelevance

      public void setRelevance(Relevance relevance)
      Sets the relevance of this hit

    • setRelevance

      public void setRelevance(double relevance)
      Does setRelevance(new Relevance(relevance)

    • getRelevance

      public Relevance getRelevance()
      Returns the relevance of this hit

    • setCached

      public void setCached(boolean cached)
      Sets whether this hit is returned from a cache. Default is false

    • isCached

      public boolean isCached()
      Returns whether this hit was added to this result from a cache or not

    • setFillable

      public void setFillable()
      Tag this hit as fillable. This means that additional properties for this hit may be obtained by fetching document summaries. This also enables tracking of which summary classes have been used for filling so far. Invoking this method multiple times is allowed and will have no addition effect. Note that a fillable hit may not be made unfillable.

    • setFilled

      public void setFilled(String summaryClass)
      Register that this hit has been filled with properties using the given summary class. Note that this method will implicitly tag this hit as fillable if it is currently not.
      Parameters:
      summaryClass - summary class used for filling

    • isFillable

      public boolean isFillable()

    • getFilled

      public Set<String> getFilled()
      Returns the set of summary classes for which this hit is filled as an unmodifiable set. If this set is 'null', it means that this hit is unfillable, which is equivalent to a hit where all summary classes have already been used for filling, or a hit where further filling will yield no extra information, if you prefer to look at it that way. Note that you might need to overload isFilled if you overload this one.

    • isFilled

      public boolean isFilled(String summaryClass)
      Returns whether this hit has been filled with the properties contained in the given summary class. Note that this method will also return true if this hit is not fillable.

    • setSource

      public void setSource(String source)
      Sets the name of the source creating this hit

    • getSource

      public String getSource()
      Returns the name of the source creating this hit

    • forEachField

      public void forEachField(BiConsumer<String,Object> consumer)
      Receive a callback on the given object for each field in this hit. This is more efficient than accessing the fields as a map or iterator.

    • forEachFieldAsRaw

      public void forEachFieldAsRaw(Hit.RawUtf8Consumer consumer)
      Receive a callback on the given object for each field in this hit, where the callback will provide raw utf-8 byte data for strings whose data is already available at this form. This is the most resource efficient way of traversing all the fields of a hit in renderers which produces utf-8.

    • fields

      public Map<String,Object> fields()
      Returns the fields of this as a read-only map. This is more costly than fieldIterator()

    • fieldIterator

      public Iterator<Map.Entry<String,Object>> fieldIterator()
      Returns a modifiable iterator over the fields of this

    • fieldKeys

      public Set<String> fieldKeys()
      Returns the keys of the fields of this hit as a modifiable view. This follows the rules of key sets returned from maps: Key removals are reflected in the map, add and addAll is not supported.

    • reserve

      public void reserve(int minSize)
      Allocate room for the given number of fields to avoid resizing.

    • setField

      public Object setField(String key, Object value)
      Sets the value of a field
      Returns:
      the previous value, or null if none

    • getField

      public Object getField(String value)
      Returns a field value or null if not present

    • clearFields

      public void clearFields()
      Removes all fields of this

    • removeField

      public Object removeField(String field)
      Removes a field from this
      Returns:
      the removed value of the field, or null if none

    • hasField

      protected boolean hasField(String name)

    • hasFields

      protected boolean hasFields()
      Returns whether any fields are set in this

    • buildHitField

      public HitField buildHitField(String key, boolean forceNoPreTokenize)

    • types

      public Set<String> types()
      Returns the types of this as a modifiable set. Modifications to this set are directly reflected in this hit

    • isMeta

      public boolean isMeta()
      Returns whether this is a concrete hit, containing content of the requested kind, or a meta hit containing information on the collection of hits, the query, the service and so on. This default implementation return false.

    • setMeta

      public void setMeta(boolean meta)

    • isAuxiliary

      public boolean isAuxiliary()
      Auxiliary hits are not counted towards the concrete number of hits to satisfy in the users request. Any kind of meta hit is auxiliary, but hits containing concrete results can also be auxiliary, for example ads in a service which does not primarily serve ads, or groups in a hierarchical organization.
      Returns:
      true if the auxiliary value is true, or if this is a meta hit

    • setAuxiliary

      public void setAuxiliary(boolean auxiliary)

    • getQuery

      public Query getQuery()
      Returns the query which produced this hit, or null if not known

    • request

      public com.yahoo.processing.Request request()
      Returns the query which produced this hit as a request, or null if not known
      Specified by:
      request in interface com.yahoo.processing.response.Data

    • setQuery

      public final void setQuery(Query query)
      Sets the query which produced this. This is ignored (except if this is a HitGroup) if a query is already set

    • features

      public FeatureData features()
      Returns the features computed for this hit. This is never null but may be empty. This default implementation always returns empty.

    • setSearcherSpecificMetaData

      public void setSearcherSpecificMetaData(Searcher searcher, Object data)
      Attach some data to this hit for this searcher

    • getSearcherSpecificMetaData

      public Object getSearcherSpecificMetaData(Searcher searcher)
      Returns data attached to this hit for this searcher, or null if none

    • close

      protected void close()
      Releases the resources held by this, making it irreversibly unusable

    • equals

      public boolean equals(Object other)
      Returns true if the argument is a hit having the same id as this
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Returns the hashCode of this hit: The hashcode of its id
      Overrides:
      hashCode in class Object

    • compareTo

      public int compareTo(Hit other)
      Compares this hit to another hit
      Specified by:
      compareTo in interface Comparable<Hit>

    • clone

      public Hit clone()
      Overrides:
      clone in class com.yahoo.component.provider.ListenableFreezableClass

    • toString

      public String toString()
      Overrides:
      toString in class Object