Class HitGroup

  • All Implemented Interfaces:
    com.yahoo.component.provider.Freezable, com.yahoo.component.provider.ListenableFreezable, com.yahoo.processing.response.Data, com.yahoo.processing.response.DataList<Hit>, java.lang.Cloneable, java.lang.Comparable<Hit>, java.lang.Iterable<Hit>
    Direct Known Subclasses:
    AbstractList, Group, SectionHitGroup

    public class HitGroup
    extends Hit
    implements com.yahoo.processing.response.DataList<Hit>, java.lang.Cloneable, java.lang.Iterable<Hit>

    A group of ordered hits. Since hitGroup is itself a kind of Hit, this can compose hierarchies of grouped hits.

    Group hits has a relevancy just as other hits - they can be ordered between each other and in comparison to other hits.

    Note that a group is by default a meta hit, but it can also contain its own content in addition to subgroup content, in which case it should be set to non-meta.

    Author:
    bratseth
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        HitGroup()
      Creates an invalid group of hits.
        HitGroup​(java.lang.String id)
      Creates a hit group with max relevancy (1)
        HitGroup​(java.lang.String id, double relevance)
      Creates a hit group
        HitGroup​(java.lang.String id, Relevance relevance)
      Creates a group hit
      protected HitGroup​(java.lang.String id, Relevance relevance, com.yahoo.processing.response.IncomingData<Hit> incomingHits)
      Creates a group hit
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(int index, Hit hit)
      Adds a hit to this group in the specified index, all existing hits on this index and higher will have their index increased by one.
      Hit add​(Hit hit)
      Adds a hit to this group.
      void addAll​(java.util.List<Hit> hits)
      Adds a list of hits to this group, the same
      void addDataListener​(java.lang.Runnable runnable)  
      void addError​(ErrorMessage error)
      Adds an error to this result
      void analyze()
      Update concreteHitCount, cached and filled by iterating trough the hits of this result.
      java.util.List<Hit> asList()
      Returns a read only list view of the hits in this
      java.util.List<Hit> asUnorderedHits()
      Returns a read only list view of the hits in this which is potentially unsorted.
      HitGroup clone()  
      void close()
      Releases the resources held by this, making it irreversibly unusable
      com.google.common.util.concurrent.ListenableFuture<com.yahoo.processing.response.DataList<Hit>> complete()  
      void copyOrdering​(HitGroup hitGroup)
      Sets sorting information to be the same as for the provided hitGroup.
      static HitGroup createAsync​(java.lang.String id)
      Creates a HitGroup which contains data which arrives in the future.
      java.util.Iterator<Hit> deepIterator()
      Returns an iterator that does depth-first traversal of leaf hits of this group.
      void ensureCapacity​(int minCapacity)  
      Hit get​(int index)
      Returns the hit at the given (0-base) index in this group of hit (without searching any subgroups).
      Hit get​(com.yahoo.net.URI id, int depth)
      Returns the hit with the given id, or null if there is no hit with this id in this group or any subgroup.
      Hit get​(java.lang.String id)
      Hit get​(java.lang.String id, int depth)  
      int getConcreteSize()
      Returns the number of concrete hits contained in this group and all subgroups.
      int getConcreteSizeShallow()
      Returns the number of concrete hits contained in this group, without counting hits in subgroups.
      boolean getDeletionBreaksOrdering()  
      ErrorMessage getError()
      Returns the first error in this result, or null if no searcher has produced an error AND the query doesn't contain an error
      ErrorHit getErrorHit()
      Returns the error hit containing all error information, or null if no error has occurred
      java.util.Set<java.lang.String> getFilled()
      Returns the set of summaries for which all concrete hits recursively below this is filled.
      HitOrderer getOrderer()
      Returns the orderer used by this group, or null if the default relevancy order is used
      int getSubgroupCount()
      Returns the number of HitGroups present immediately in this list of hits.
      com.yahoo.processing.response.IncomingData<Hit> incoming()
      Returns the incoming hit buffer to which new hits can be added to this asynchronous, if supported by the instance
      boolean isCached()
      Returns true if all the hits recursively contained in this is cached
      boolean isFillable()  
      boolean isFilled​(java.lang.String summaryClass)
      Returns whether all hits in this result have been filled with the properties contained in the given summary class.
      java.util.Iterator<Hit> iterator()
      Returns an iterator of the hits in this group.
      Hit remove​(int index)
      Removes a hit from this group (not considering the hits of any subgroup)
      Hit remove​(com.yahoo.net.URI uri)
      Removes a hit from this group or any subgroup.
      Hit remove​(java.lang.String uriString)
      Removes a hit from this group or any subgroup
      DefaultErrorHit removeErrorHit()
      Removes the error hit of this.
      void set​(int index, Hit hit)
      Inserts the given hit at the specified index in this group.
      void setDeletionBreaksOrdering​(boolean flag)  
      void setFillable()
      Tag this hit as fillable.
      void setFilled​(java.lang.String summaryClass)
      Ignored as this should always be derived from the content hits
      void setId​(com.yahoo.net.URI id)
      Assign an id to this hit.
      void setId​(java.lang.String id)
      Calls setId(new URI(id))
      void setOrdered​(boolean ordered)
      Turn off internal resorting of hits.
      void setOrderer​(HitOrderer hitOrderer)
      Sets the hit orderer for this group.
      void setSorted​(boolean sorted)
      Explicitly set whether the hits in this group are correctly sorted at this moment.
      int size()
      Returns the number of hits available immediately in this group (counting a subgroup as one hit).
      void sort()
      Force hit sorting now.
      void trim​(int offset, int numHits)
      Remove the first offset concrete hits in this group, and hits beyond offset+numHits
      java.util.Iterator<Hit> unorderedDeepIterator()
      Returns an iterator that does depth-first traversal of leaf hits of this group, in a potentially unsorted order.
      java.util.Iterator<Hit> unorderedIterator()
      Returns an iterator of the hits in this group in a potentially unsorted order.
      • 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.processing.response.Data

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

        freeze, isFrozen
      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator
      • Methods inherited from interface com.yahoo.component.provider.ListenableFreezable

        addFreezeListener
    • Constructor Detail

      • HitGroup

        public HitGroup()
        Creates an invalid group of hits. Id must be set before handoff.
      • HitGroup

        public HitGroup​(java.lang.String id)
        Creates a hit group with max relevancy (1)
        Parameters:
        id - the id of this hit - any string, it is convenient to make this unique in the result containing this
      • HitGroup

        public HitGroup​(java.lang.String id,
                        double relevance)
        Creates a hit group
        Parameters:
        id - the id of this hit - any string, it is convenient to make this unique in the result containing this
        relevance - the relevance of this group of hits, preferably a number between 0 and 1
      • HitGroup

        public HitGroup​(java.lang.String id,
                        Relevance relevance)
        Creates a group hit
        Parameters:
        id - the id of this hit - any string, it is convenient to make this unique in the result containing this
        relevance - the relevancy of this group of hits
      • HitGroup

        protected HitGroup​(java.lang.String id,
                           Relevance relevance,
                           com.yahoo.processing.response.IncomingData<Hit> incomingHits)
        Creates a group hit
        Parameters:
        id - the id of this hit - any string, it is convenient to make this unique in the result containing this
        relevance - the relevancy of this group of hits
        incomingHits - the incoming buffer to which new hits can be added asynchronously
    • Method Detail

      • createAsync

        public static HitGroup createAsync​(java.lang.String id)
        Creates a HitGroup which contains data which arrives in the future.
        Parameters:
        id - the id of this
        Returns:
        a HitGroup which is incomplete and which has an incoming() where new hits can be added later
      • setId

        public void setId​(java.lang.String id)
        Calls setId(new URI(id))
        Overrides:
        setId in class Hit
      • setId

        public void setId​(com.yahoo.net.URI id)
        Assign an id to this hit. For HitGroups, this is a legal call also when an id is already set, i.e hit groups allows their ids to be reassigned. This is to allow hit groups to be inserted in new structures with an id reflecting their role/placement in the structure.
        Overrides:
        setId in class Hit
        Parameters:
        id - the new or initial iof of this hit
      • setOrdered

        public void setOrdered​(boolean ordered)
        Turn off internal resorting of hits.
        Parameters:
        ordered - set to true to tell this group that the hits set in it is already correctly ordered and should never be resorted. Set to false to use the default lazy resorting by hit ordering.
      • size

        public int size()
        Returns the number of hits available immediately in this group (counting a subgroup as one hit).
      • ensureCapacity

        public void ensureCapacity​(int minCapacity)
      • getConcreteSize

        public int getConcreteSize()

        Returns the number of concrete hits contained in this group and all subgroups. This should equal the requested hits count if the query has that many matches.

      • getConcreteSizeShallow

        public int getConcreteSizeShallow()

        Returns the number of concrete hits contained in this group, without counting hits in subgroups.

      • getSubgroupCount

        public int getSubgroupCount()
        Returns the number of HitGroups present immediately in this list of hits.
      • add

        public Hit add​(Hit hit)
        Adds a hit to this group. If the given hit is an ErrorHit and this group already have an error hit, the errors in the given hit are merged into the errors of this.
        Specified by:
        add in interface com.yahoo.processing.response.DataList<Hit>
        Returns:
        the resulting hit - this is usually the input hit, but if an error hit was added, and there was already an error hit present, that hit, containing the merged information is returned
      • addAll

        public void addAll​(java.util.List<Hit> hits)
        Adds a list of hits to this group, the same
      • get

        public Hit get​(int index)
        Returns the hit at the given (0-base) index in this group of hit (without searching any subgroups).
        Specified by:
        get in interface com.yahoo.processing.response.DataList<Hit>
        Parameters:
        index - the index into this list
        Throws:
        java.lang.IndexOutOfBoundsException - if there is no hit at the given index
      • get

        public Hit get​(java.lang.String id,
                       int depth)
      • get

        public Hit get​(com.yahoo.net.URI id,
                       int depth)
        Returns the hit with the given id, or null if there is no hit with this id in this group or any subgroup. This method is o(min(number of nested hits in this result, depth)).
        Parameters:
        id - the id of the hit to return from this or any nested group
        depth - the max depth to recurse into nested groups: -1: Recurse infinitely deep, 0: Only look at hits in the list of this group, 1: Look at hits in this group, and the hits of any immediate nested HitGroups, etc.
        Returns:
        the hit, or null if not found
      • set

        public void set​(int index,
                        Hit hit)
        Inserts the given hit at the specified index in this group.
      • add

        public void add​(int index,
                        Hit hit)
        Adds a hit to this group in the specified index, all existing hits on this index and higher will have their index increased by one. Note: If the group was sorted, it will still be considered sorted after this call.
      • remove

        public Hit remove​(java.lang.String uriString)
        Removes a hit from this group or any subgroup
        Parameters:
        uriString - the uri of the hit to remove
        Returns:
        the hit to remove, or null if the hit was not present
      • remove

        public Hit remove​(com.yahoo.net.URI uri)
        Removes a hit from this group or any subgroup.
        Parameters:
        uri - the uri of the hit to remove.
        Returns:
        the hit removed, or null if not found.
      • remove

        public Hit remove​(int index)
        Removes a hit from this group (not considering the hits of any subgroup)
        Parameters:
        index - the position of the hit to remove
        Returns:
        the hit removed
        Throws:
        java.lang.IndexOutOfBoundsException - if there is no hit at the given position
      • addError

        public void addError​(ErrorMessage error)
        Adds an error to this result
      • getErrorHit

        public ErrorHit getErrorHit()
        Returns the error hit containing all error information, or null if no error has occurred
      • removeErrorHit

        public DefaultErrorHit removeErrorHit()
        Removes the error hit of this. This removes all error messages of this and the query producing it.
        Returns:
        the error hit which was removed, or null if there were no errors
      • getError

        public ErrorMessage getError()
        Returns the first error in this result, or null if no searcher has produced an error AND the query doesn't contain an error
      • trim

        public void trim​(int offset,
                         int numHits)
        Remove the first offset concrete hits in this group, and hits beyond offset+numHits
      • iterator

        public java.util.Iterator<Hit> iterator()
        Returns an iterator of the hits in this group.

        This iterator is modifiable - removals will take effect in this group of hits.

        Specified by:
        iterator in interface java.lang.Iterable<Hit>
      • deepIterator

        public java.util.Iterator<Hit> deepIterator()
        Returns an iterator that does depth-first traversal of leaf hits of this group. Calling this method has the side-effect of sorting the internal list of hits.
        Returns:
        A modifiable iterator.
      • unorderedDeepIterator

        public java.util.Iterator<Hit> unorderedDeepIterator()
        Returns an iterator that does depth-first traversal of leaf hits of this group, in a potentially unsorted order. As opposed to deepIterator(), this method has no side-effect.
        Returns:
        A modifiable iterator.
      • asList

        public java.util.List<Hit> asList()
        Returns a read only list view of the hits in this
        Specified by:
        asList in interface com.yahoo.processing.response.DataList<Hit>
      • asUnorderedHits

        public java.util.List<Hit> asUnorderedHits()
        Returns a read only list view of the hits in this which is potentially unsorted. Using this over getHits is potentially faster when a sorted view is not needed.
      • unorderedIterator

        public java.util.Iterator<Hit> unorderedIterator()
        Returns an iterator of the hits in this group in a potentially unsorted order.

        Using this over getPreludeHitIterator is potentially faster when a sorted view is not needed.

        This iterator is modifiable - removals will take effect in this group of hits.

      • sort

        public void sort()
        Force hit sorting now. This is not normally useful because a group will stay sorted automatically, but it is in the case where the hits have changed their internal state in a way that should change ordering
      • setOrderer

        public void setOrderer​(HitOrderer hitOrderer)

        Sets the hit orderer for this group.

        Parameters:
        hitOrderer - the new hit orderer, or null to use default relevancy ordering
      • setSorted

        public void setSorted​(boolean sorted)
        Explicitly set whether the hits in this group are correctly sorted at this moment. If the contained hits are modified directly in a way that may break ordering, you should call setSorted(false).
      • getOrderer

        public HitOrderer getOrderer()
        Returns the orderer used by this group, or null if the default relevancy order is used
      • setDeletionBreaksOrdering

        public void setDeletionBreaksOrdering​(boolean flag)
      • getDeletionBreaksOrdering

        public boolean getDeletionBreaksOrdering()
      • isCached

        public boolean isCached()
        Returns true if all the hits recursively contained in this is cached
        Overrides:
        isCached in class Hit
      • isFilled

        public boolean isFilled​(java.lang.String summaryClass)
        Returns whether all hits in this result have been filled with the properties contained in the given summary class. Note that this method will also return true if no hits in this result are fillable.
        Overrides:
        isFilled in class Hit
      • copyOrdering

        public void copyOrdering​(HitGroup hitGroup)
        Sets sorting information to be the same as for the provided hitGroup. The contained hits should already be sorted in the order specified by the hitGroup given as argument.
      • analyze

        public void analyze()
        Update concreteHitCount, cached and filled by iterating trough the hits of this result. Recursively also update all subgroups.
      • setFillable

        public void setFillable()
        Description copied from class: Hit
        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.
        Overrides:
        setFillable in class Hit
      • setFilled

        public void setFilled​(java.lang.String summaryClass)
        Ignored as this should always be derived from the content hits
        Overrides:
        setFilled in class Hit
        Parameters:
        summaryClass - summary class used for filling
      • isFillable

        public boolean isFillable()
        Overrides:
        isFillable in class Hit
      • getFilled

        public java.util.Set<java.lang.String> getFilled()
        Returns the set of summaries for which all concrete hits recursively below this is filled.
        Overrides:
        getFilled in class Hit
      • incoming

        public com.yahoo.processing.response.IncomingData<Hit> incoming()
        Returns the incoming hit buffer to which new hits can be added to this asynchronous, if supported by the instance
        Specified by:
        incoming in interface com.yahoo.processing.response.DataList<Hit>
      • complete

        public com.google.common.util.concurrent.ListenableFuture<com.yahoo.processing.response.DataList<Hit>> complete()
        Specified by:
        complete in interface com.yahoo.processing.response.DataList<Hit>
      • addDataListener

        public void addDataListener​(java.lang.Runnable runnable)
        Specified by:
        addDataListener in interface com.yahoo.processing.response.DataList<Hit>
      • close

        public void close()
        Description copied from class: Hit
        Releases the resources held by this, making it irreversibly unusable
        Specified by:
        close in interface com.yahoo.processing.response.DataList<Hit>
        Overrides:
        close in class Hit