Hit (container-search 6.288.1 API)

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, PeakQpsSearcher.QpsHit
```
public class Hit
extends com.yahoo.component.provider.ListenableFreezableClass
implements com.yahoo.processing.response.Data, Comparable<Hit>, Cloneable
```
A search hit. The identifier of the hit is the uri (the uri is immutable once set). If two hits have the same uri they are equal per definition. Hits are naturally ordered by decreasing relevance. Note that this definition of equals and natural ordering is inconsistent.

Hits may be of the meta type, meaning that they contain some information about the query or result which does not represent a particular piece of matched content. 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.

Author:

bratseth

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static interface Hit.RawUtf8Consumer

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

Field Summary

Fields
Modifier and Type Field and Description

static String RANKFEATURES_FIELD
The hit field used to store rank features.

static String SDDOCNAME_FIELD

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

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`Hit()` Creates an (invalid) empty hit.
	`Hit(String id)` Creates a minimal valid hit having relevance 1000
	`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

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`protected void`	`assignId(com.yahoo.net.URI id)` Assigns a new or changed id to this hit.
`HitField`	`buildHitField(String key)` Generate a HitField from a field if the field exists
`HitField`	`buildHitField(String key, boolean forceNoPreTokenize)` Generate a HitField from a field if the field exists
`HitField`	`buildHitField(String key, boolean forceNoPreTokenize, boolean forceStringHandling)` Deprecated.
`void`	`changeFieldKey(String oldKey, String newKey)` Deprecated. do not use
`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 object)` Returns true if the argument is a hit having the same uri as this
`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.
`int`	`getAddNumber()` Deprecated. do not use
`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
`String`	`getFieldXML(String key)` Deprecated. do not use
`Set<String>`	`getFilled()` Returns the set of summary classes for which this hit is filled as an unmodifiable set.
`protected Set<String>`	`getFilledInternal()` For internal use only.
`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
`int`	`getSourceNumber()` Deprecated. do not use
`String`	`getTypeString()` Deprecated. do not use
`String`	`getUnboldedField(String key, boolean escape)` Deprecated. do not use
`protected boolean`	`hasField(String name)`
`protected boolean`	`hasFields()` Returns whether any fields are set in this
`int`	`hashCode()` Returns the hashCode of this hit, which is the hashcode of its uri.
`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`	`setAddNumber(int addNumber)` Deprecated. do not use
`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.
`protected void`	`setFilledInternal(Set<String> filled)` Internal - do not use
`void`	`setId(String id)` Calls setId(new URI(id))
`void`	`setId(com.yahoo.net.URI id)` Initializes the id of this hit.
`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, Object data)` Attach some data to this hit for this searcher
`void`	`setSource(String source)` Sets the name of the source creating this hit
`void`	`setSourceNumber(int number)` Deprecated. do not use
`static String`	`stripCharacter(char strip, String toStripFrom)` Deprecated. do not use
`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.ListenableFreezable
addFreezeListener

Methods inherited from interface com.yahoo.component.provider.Freezable
freeze, isFrozen

- Field Detail
  - RANKFEATURES_FIELD
```
public static final String RANKFEATURES_FIELD
```
    The hit field used to store rank features. TODO: Remove on Vespa 7
    
    See Also:
    
    Constant Field Values
  - SDDOCNAME_FIELD
```
public static final String SDDOCNAME_FIELD
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - Hit
```
protected Hit()
```
    Creates an (invalid) empty hit. Id and relevance must be set before handoff
  - Hit
```
public Hit(String id)
```
    Creates a minimal valid hit having relevance 1000
    
    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
    
    Throws:
    
    IllegalArgumentException - if the given relevance is not between 0 and 1000
  - 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
    
    Throws:
    
    IllegalArgumentException - if the given relevance is not between 0 and 1000
  - 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
    
    Throws:
    
    IllegalArgumentException - if the given relevance is not between 0 and 1000
  - 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
    
    Throws:
    
    IllegalArgumentException - if the given relevance is not between 0 and 1000
- Method Detail
  - 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 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(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 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(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
  - changeFieldKey
```
@Deprecated
public void changeFieldKey(String oldKey,
                                       String newKey)
```
    Deprecated. do not use
    
    Changes the key under which a value is found. This is useful because it allows keys to be changed without accessing the value (which may be lazily created).
  - buildHitField
```
public HitField buildHitField(String key)
```
    Generate a HitField from a field if the field exists
  - buildHitField
```
public HitField buildHitField(String key,
                              boolean forceNoPreTokenize)
```
    Generate a HitField from a field if the field exists
  - buildHitField
```
@Deprecated
public HitField buildHitField(String key,
                                          boolean forceNoPreTokenize,
                                          boolean forceStringHandling)
```
    Deprecated.
  - types
```
public Set<String> types()
```
    Returns the types of this as a modifiable set. Modifications to this set are directly reflected in this hit
  - getTypeString
```
@Deprecated
public String getTypeString()
```
    Deprecated. do not use
  - getAddNumber
```
@Deprecated
public int getAddNumber()
```
    Deprecated. do not use
    
    Returns the add number, assigned when adding the hit to a Result. Used to order equal relevant hit by add order. -1 if this hit has never been added to a result.
  - setAddNumber
```
@Deprecated
public void setAddNumber(int addNumber)
```
    Deprecated. do not use
    
    Sets the add number, assigned when adding the hit to a Result, used to order equal relevant hit by add order.
  - 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)
```
  - getSourceNumber
```
@Deprecated
public int getSourceNumber()
```
    Deprecated. do not use
  - setSourceNumber
```
@Deprecated
public void setSourceNumber(int number)
```
    Deprecated. do not use
  - 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
  - getFieldXML
```
@Deprecated
public String getFieldXML(String key)
```
    Deprecated. do not use
    
    Returns a field of this hit XML escaped and without token delimiters.
    
    Returns:
    
    a field of this hit, or null if the property is not set
  - getUnboldedField
```
@Deprecated
public String getUnboldedField(String key,
                                           boolean escape)
```
    Deprecated. do not use
  - 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
  - setFilledInternal
```
protected final void setFilledInternal(Set<String> filled)
```
    Internal - do not use
    
    Parameters:
    
    filled - the backing set
  - getFilledInternal
```
protected final Set<String> getFilledInternal()
```
    For internal use only. Gives access to the modifiable backing set of filled summaries. This set might be unmodifiable if the size is less than or equal to 1
    
    Returns:
    
    the set of filled summaries.
  - stripCharacter
```
@Deprecated
public static String stripCharacter(char strip,
                                                String toStripFrom)
```
    Deprecated. do not use
  - close
```
protected void close()
```
    Releases the resources held by this, making it irreversibly unusable
  - equals
```
public boolean equals(Object object)
```
    Returns true if the argument is a hit having the same uri as this
    
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Returns the hashCode of this hit, which is the hashcode of its uri.
    
    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

Class Hit

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

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

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

Methods inherited from class java.lang.Object

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

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

Field Detail

RANKFEATURES_FIELD

SDDOCNAME_FIELD

Constructor Detail

Hit

Hit

Hit

Hit

Hit

Hit

Hit

Hit

Hit

Hit

Hit

Method Detail

setId

setId

assignId

getId

getDisplayId

setRelevance

setRelevance

getRelevance

setCached

isCached

setFillable

setFilled

isFillable

getFilled

isFilled

setSource

getSource

forEachField

forEachFieldAsRaw

fields

fieldIterator

fieldKeys

reserve

setField

getField

clearFields

removeField

hasField

hasFields

changeFieldKey

buildHitField

buildHitField

buildHitField

types

getTypeString

getAddNumber

setAddNumber

isMeta

setMeta

isAuxiliary

setAuxiliary

getSourceNumber

setSourceNumber

getQuery

request

setQuery

getFieldXML

getUnboldedField

setSearcherSpecificMetaData

getSearcherSpecificMetaData

setFilledInternal

getFilledInternal

stripCharacter

close