Package com.yahoo.search.result

Class Hit

  • All Implemented Interfaces:
    com.yahoo.component.provider.Freezable, com.yahoo.component.provider.ListenableFreezable, com.yahoo.processing.response.Data, java.lang.Cloneable, java.lang.Comparable<Hit>
    Direct Known Subclasses:
    DefaultErrorHit, HitGroup, PeakQpsSearcher.QpsHit
    public class Hit
extends com.yahoo.component.provider.ListenableFreezableClass
implements com.yahoo.processing.response.Data, java.lang.Comparable<Hit>, java.lang.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 java.lang.String RANKFEATURES_FIELD
      The hit field used to store rank features
      static java.lang.String SDDOCNAME_FIELD  

    • Constructor Summary

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

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void assignId​(com.yahoo.net.URI id)
      Assigns a new or changed id to this hit.
      HitField buildHitField​(java.lang.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​(java.lang.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.
      java.util.Iterator<java.util.Map.Entry<java.lang.String,​java.lang.Object>> fieldIterator()
      Returns a modifiable iterator over the fields of this
      java.util.Set<java.lang.String> fieldKeys()
      Returns the keys of the fields of this hit as a modifiable view.
      java.util.Map<java.lang.String,​java.lang.Object> fields()
      Returns the fields of this as a read-only map.
      void forEachField​(java.util.function.BiConsumer<java.lang.String,​java.lang.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.
      java.lang.String getDisplayId()
      Returns the id to display, or null to not display (render) the id.
      java.lang.Object getField​(java.lang.String value)
      Returns a field value or null if not present
      java.util.Set<java.lang.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
      java.lang.Object getSearcherSpecificMetaData​(Searcher searcher)
      Returns data attached to this hit for this searcher, or null if none
      java.lang.String getSource()
      Returns the name of the source creating this hit
      protected boolean hasField​(java.lang.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​(java.lang.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.
      java.lang.Object removeField​(java.lang.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.
      java.lang.Object setField​(java.lang.String key, java.lang.Object value)
      Sets the value of a field
      void setFillable()
      Tag this hit as fillable.
      void setFilled​(java.lang.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​(java.lang.String id)
      Calls setId(new URI(id))
      void setMeta​(boolean meta)  
      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, java.lang.Object data)
      Attach some data to this hit for this searcher
      void setSource​(java.lang.String source)
      Sets the name of the source creating this hit
      java.lang.String toString()  
      java.util.Set<java.lang.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 Detail

      • RANKFEATURES_FIELD

        public static final java.lang.String RANKFEATURES_FIELD
        The hit field used to store rank features
        See Also:
        Constant Field Values

    • Constructor Detail

      • Hit

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

      • Hit

        protected Hit​(Relevance relevance)

      • Hit

        public Hit​(java.lang.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​(java.lang.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​(java.lang.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:
        java.lang.IllegalArgumentException - if the given relevance is not between 0 and 1

      • Hit

        public Hit​(java.lang.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:
        java.lang.IllegalArgumentException - if the given relevance is not between 0 and 1

      • Hit

        public Hit​(java.lang.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:
        java.lang.IllegalArgumentException - if the given relevance is not between 0 and 1000

      • Hit

        public Hit​(java.lang.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:
        java.lang.IllegalArgumentException - if the given relevance is not between 0 and 1000

      • Hit

        public Hit​(java.lang.String id,
           double relevance,
           java.lang.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​(java.lang.String id,
           double relevance,
           java.lang.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​(java.lang.String id,
           Relevance relevance,
           java.lang.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​(java.lang.String id,
           Relevance relevance,
           java.lang.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 Detail

      • setId

        public void setId​(java.lang.String id)
        Calls setId(new URI(id))

      • setId

        public void setId​(com.yahoo.net.URI id)
        Initializes the id of this hit.
        Throws:
        java.lang.NullPointerException - if the uri is null
        java.lang.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 java.lang.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 getId().toString()

      • 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​(java.lang.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 java.util.Set<java.lang.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 with 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​(java.lang.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​(java.lang.String source)
        Sets the name of the source creating this hit

      • getSource

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

      • forEachField

        public void forEachField​(java.util.function.BiConsumer<java.lang.String,​java.lang.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 java.util.Map<java.lang.String,​java.lang.Object> fields()
        Returns the fields of this as a read-only map. This is more costly than fieldIterator()

      • fieldIterator

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

      • fieldKeys

        public java.util.Set<java.lang.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 java.lang.Object setField​(java.lang.String key,
                                 java.lang.Object value)
        Sets the value of a field
        Returns:
        the previous value, or null if none

      • getField

        public java.lang.Object getField​(java.lang.String value)
        Returns a field value or null if not present

      • clearFields

        public void clearFields()
        Removes all fields of this

      • removeField

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

      • hasField

        protected boolean hasField​(java.lang.String name)

      • hasFields

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

      • buildHitField

        public HitField buildHitField​(java.lang.String key,
                              boolean forceNoPreTokenize)

      • types

        public java.util.Set<java.lang.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,
                                        java.lang.Object data)
        Attach some data to this hit for this searcher

      • getSearcherSpecificMetaData

        public java.lang.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​(java.lang.Object other)
        Returns true if the argument is a hit having the same id as this
        Overrides:
        equals in class java.lang.Object

      • hashCode

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

      • compareTo

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

      • clone

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

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object