Class TdbFacet

  • All Implemented Interfaces:
    java.lang.Iterable<TdbFacetValue>
    Direct Known Subclasses:
    TdbFieldTermFacet, TdbSearchFacet

    public abstract class TdbFacet
    extends java.lang.Object
    implements java.lang.Iterable<TdbFacetValue>
    Represents a facet for use in search and navigation.

    Note that the following properties have been deprecated from version 8.0:

    • FetchFrom
    • FetchTo
    • BaselineSize

    Applications that use the Fetch-properties must be modified to instead select the desired values by index (by using the getValue(int) method) after calling TdbFacetSet.get(). TRIPjxp will handle range retrieval itself internally as needed.

    After facet baseline support was added to the TRIP kernel, the baseline size (number of terms to recall) is no longer used. All values from the baseline are always recalled in the kernel.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void clear()
      Clears accumulated state from this object.
      abstract void close()
      Closes this facet by releasing server-side resources and removes the the accumulated state from the object.
      java.lang.String getBaselineKey()
      Gets the key identifying the facet baseline to set or use.
      int getBaselineSize()
      Deprecated.
      Baseline size is not used in TRIP 8.0 and later.
      java.lang.String getDatabase()
      Returns the name of the database from which the facets in this set are to be retrieved.
      static int getDefaultTimeout()
      Get the default timeout value in seconds for on-demand loaded facets.
      int getFetchFrom()
      Deprecated.
      Facet fetch intervals are no longer required nor recommended.
      int getFetchTo()
      Deprecated.
      Facet fetch intervals are no longer required nor recommended.
      int getLowerFrequencyLimit()
      Returns the lower limit of the facet frequency (value count) of facet values to retrieve.
      java.lang.String getName()
      Returns the name or identity of this facet.
      int getSearchSet()
      Retrieve the search set number from which facet values are to be taken.
      TdbFacetSortOrder getSortOrder()
      Returns the sort order for the values of this facet.
      int getTimeout()
      Get timeout value in seconds for delay-loaded facets.
      int getUpdateValueCount()
      Returns the total number of non-zero record count values associated with this facet.
      int getUpperFrequencyLimit()
      Returns the upper limit of the facet frequency (value count) of facet values to retrieve.
      abstract TdbFacetValue getValue​(int index)
      Retrieve a facet value object.
      int getValueCount()
      Returns the total number of values associated with this facet.
      boolean isBaselineAtEnd()
      Returns the flag determining where to place facet values that are present in the baseline but not in the latest update of the facet.
      boolean isOpenExisting()
      Returns the flag determining if a previously created baseline facet is to be opened or if one is to be created or further refined.
      boolean isRegisterBaseline()
      Returns true if the facet values should be registered as a baseline.
      boolean isResetBaseline()
      Returns true if the counts of existing baseline are to be reset.
      boolean isUseBaseline()
      Returns true if a previously registered baseline should be used.
      java.util.Iterator<TdbFacetValue> iterator()
      Returns an iterator over the values in this facet.
      void setBaselineAtEnd​(boolean atend)
      Determines where to place facet values that are present in the baseline but not in the latest update of the facet.
      void setBaselineKey​(java.lang.String key)
      Set a key identifying the facet baseline to set or use.
      void setBaselineSize​(int size)
      Deprecated.
      Baseline size is not used in TRIP 8.0 and later.
      void setDatabase​(java.lang.String database)
      Assigns the name of the database from which the facets in this set are to be retrieved.
      static void setDefaultTimeout​(int timeoutValue)
      Set the default timeout value in seconds for on-demand loaded facets.
      void setFetchFrom​(int fetchFrom)
      Deprecated.
      Facet fetch intervals are no longer required nor recommended.
      void setFetchTo​(int fetchTo)
      Deprecated.
      Facet fetch intervals are no longer required nor recommended.
      void setFrequencyLimits​(int lowerLimit, int upperLimit)
      Assigns the upper and lower limits of the facet frequency (value count) of facet values to retrieve.
      void setOpenExisting​(boolean openExisting)
      Determines if a previously created baseline facet is to be opened or if one is to be created or further refined.
      void setRegisterBaseline​(boolean enable)
      Register the facet results for this facet as a baseline.
      void setResetBaseline​(boolean enable)
      Set to true to reset the counts of an existing baseline for this facet to the counts of its most recent refinement.
      void setSearchSet​(int searchSet)
      Retrieve the search set number from which facet values are to be taken.
      void setSortOrder​(TdbFacetSortOrder sortOrder)
      Sets the sort order for the values of this facet.
      void setTimeout​(int timeout)
      Set timeout value in seconds for delay-loaded facets.
      void setUseBaseline​(boolean enable)
      Set to true to use a previously registered baseline for this facet.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator
    • Method Detail

      • iterator

        public java.util.Iterator<TdbFacetValue> iterator()
        Returns an iterator over the values in this facet.
        Specified by:
        iterator in interface java.lang.Iterable<TdbFacetValue>
        Returns:
        A facet value iterator object to use with the "foreach" statement.
      • getName

        public java.lang.String getName()
        Returns the name or identity of this facet.
      • getDatabase

        public java.lang.String getDatabase()
        Returns the name of the database from which the facets in this set are to be retrieved.

        Note that cluster names are not valid here. In order to fetch facet values from a cluster, you need to use search set that contains records from the cluster.

        Returns:
        Database name
      • setDatabase

        public void setDatabase​(java.lang.String database)
        Assigns the name of the database from which the facets in this set are to be retrieved.

        Note that cluster names are not valid here. In order to fetch facet values from a cluster, you need to use search set that contains records from the cluster.

        Parameters:
        database - Database name
      • getSearchSet

        public int getSearchSet()
        Retrieve the search set number from which facet values are to be taken.
        Returns:
        Search set number or -1 if no search set has been defined.
      • setSearchSet

        public void setSearchSet​(int searchSet)
        Retrieve the search set number from which facet values are to be taken.
        Parameters:
        searchSet - Search set number or -1 for no search set.
      • getValueCount

        public int getValueCount()
        Returns the total number of values associated with this facet.
        Returns:
        Number of values in this facet
      • getUpdateValueCount

        public int getUpdateValueCount()
        Returns the total number of non-zero record count values associated with this facet. For facets that do not use baselines, this value is the same as the regular valueCount.

        Requires TRIPsystem 8.0-1 or later. For older versions, this property will always have a value identical to valueCount.

        Returns:
        Number of values with a count larger than zero.
        Since:
        8.0-1
      • getSortOrder

        public TdbFacetSortOrder getSortOrder()
        Returns the sort order for the values of this facet.
      • setSortOrder

        public void setSortOrder​(TdbFacetSortOrder sortOrder)
                          throws TdbException
        Sets the sort order for the values of this facet.
        Parameters:
        sortOrder - Sort order type to use with this facet
        Throws:
        TdbException - If the sort order type is not valid for this facet
      • isBaselineAtEnd

        public boolean isBaselineAtEnd()
        Returns the flag determining where to place facet values that are present in the baseline but not in the latest update of the facet.
        Returns:
        True if zero-count baseline values are located at the end, or false if they sorted inline with the other values.
      • setBaselineAtEnd

        public void setBaselineAtEnd​(boolean atend)
        Determines where to place facet values that are present in the baseline but not in the latest update of the facet.
        Parameters:
        atend - True to place all zero-count baseline values at end, and false to place them inline with the other values.
      • isOpenExisting

        public boolean isOpenExisting()
        Returns the flag determining if a previously created baseline facet is to be opened or if one is to be created or further refined.
        Returns:
        True to open an existing baselined facet, and false otherwise.
        Since:
        TRIP 8.0
      • setOpenExisting

        public void setOpenExisting​(boolean openExisting)
        Determines if a previously created baseline facet is to be opened or if one is to be created or further refined.
        Parameters:
        openExisting - True to open an existing baselined facet, and false otherwise.
        Since:
        TRIP 8.0

        This property should only be set to true if a previously created facet for which a baseline has been set is to be opened without further refining it. E.g. when retrieving additional ranges of values.

      • getFetchTo

        @Deprecated
        public int getFetchTo()
        Deprecated.
        Facet fetch intervals are no longer required nor recommended.
        Returns the highest (by sort order) ordinal number of the value to fetch.
        Returns:
        1-based number of smallest facet value to fetch.
      • setFetchTo

        @Deprecated
        public void setFetchTo​(int fetchTo)
        Deprecated.
        Facet fetch intervals are no longer required nor recommended.

        This parameter will be ignored with TRIP 8.0 and later.

        The use of this property to specify the range values to retrieve is no longer supported. Instead, iterate over the getValue(int) method to obtain the values in the desired range. TRIPjxp will retrieve the values from the server as needed.

        Assigns the highest (by sort order) ordinal number of the value to fetch.
        Parameters:
        fetchTo - 1-based number of smallest facet value to fetch.
      • getFetchFrom

        @Deprecated
        public int getFetchFrom()
        Deprecated.
        Facet fetch intervals are no longer required nor recommended.
        Returns the lowest (by sort order) ordinal number of the value to fetch.
        Returns:
        1-based number of largest facet value to fetch.
      • setFetchFrom

        @Deprecated
        public void setFetchFrom​(int fetchFrom)
        Deprecated.
        Facet fetch intervals are no longer required nor recommended.

        This parameter will be ignored with TRIP 8.0 and later.

        The use of this property to specify the range values to retrieve is no longer supported. Instead, iterate over the getValue(int) method to obtain the values in the desired range. TRIPjxp will retrieve the values from the server as needed.

        Assigns the lowest (by sort order) ordinal number of the value to fetch.
        Parameters:
        fetchFrom - 1-based number of lowest facet value to fetch.
      • getLowerFrequencyLimit

        public int getLowerFrequencyLimit()
        Returns the lower limit of the facet frequency (value count) of facet values to retrieve.
        Returns:
        Lower limit or 0 for no limit.
      • getUpperFrequencyLimit

        public int getUpperFrequencyLimit()
        Returns the upper limit of the facet frequency (value count) of facet values to retrieve.
        Returns:
        Upper limit or 0 for no limit.
      • setFrequencyLimits

        public void setFrequencyLimits​(int lowerLimit,
                                       int upperLimit)
        Assigns the upper and lower limits of the facet frequency (value count) of facet values to retrieve.
        Parameters:
        lowerLimit - Lower limit or 0 for no limit.
        upperLimit - Upper limit or 0 for no limit.
      • getTimeout

        public int getTimeout()
        Get timeout value in seconds for delay-loaded facets.

        Facets with delay-loaded values cease to be accessible after this timeout period. If the timeout value is zero, timeout has been disabled. The default timeout is 1800 seconds (30 minutes).

        Returns:
        Timeout value in seconds
      • setTimeout

        public void setTimeout​(int timeout)
        Set timeout value in seconds for delay-loaded facets.

        Facets with delay-loaded values cease to be accessible after this timeout period. If the timeout value is zero, timeout has been disabled. The default timeout is 1800 seconds (30 minutes).

        Parameters:
        timeout - Timeout value in seconds
      • getDefaultTimeout

        public static int getDefaultTimeout()
        Get the default timeout value in seconds for on-demand loaded facets.

        All TdbFacet instances will have their initial Timeout value set to that of the DefaultTimeout property.

        Returns:
        Default timeout value in seconds
      • setDefaultTimeout

        public static void setDefaultTimeout​(int timeoutValue)
        Set the default timeout value in seconds for on-demand loaded facets.

        After this property has been set, all TdbFacet instances subsequently created will have their Timeout set to that of the DefaultTimeout property.

        x * @param timeoutValue Default timeout value in seconds
      • setRegisterBaseline

        public void setRegisterBaseline​(boolean enable)
        Register the facet results for this facet as a baseline.
        Parameters:
        enable - True to enable the creation of a baseline

        The idea with a baseline is to enble recall of a previous, initial set of facet values so that a new facet request can 1) include the previous counts as a comparison, and 2) add values from the baseline to the new result if the new result is smaller than the requested range.

        The baselines for all facets in a TdbFacetSet are registered at the same time, upon the next call to TdbFacetSet.get().

        Even though each facet in a facet set can have its own baseline, there is only single collection of baselines. This means that using multiple TdbFacetSet instances in parallel in an appliction is not fully supported.

        In order to use a previously established baseline, call the TdbFacet.setUseBaseline() method with the argument set to true. Either call setRegisterBaseline with the 'enable' argument set to false for that facet instance, or do not not call it at all.

      • isRegisterBaseline

        public boolean isRegisterBaseline()
        Returns true if the facet values should be registered as a baseline.
      • setBaselineSize

        @Deprecated
        public void setBaselineSize​(int size)
        Deprecated.
        Baseline size is not used in TRIP 8.0 and later.

        This parameter will be ignored with TRIP 8.0 and later.

        Set the number of values to recall for the baseline. Used together with registerBaseline.
        Parameters:
        size - The maximum number of values to store in the baseline (minimum 100).
      • getBaselineSize

        @Deprecated
        public int getBaselineSize()
        Deprecated.
        Baseline size is not used in TRIP 8.0 and later.
        Return the number of values to recall for the baseline. Used together with registerBaseline.
      • setUseBaseline

        public void setUseBaseline​(boolean enable)
        Set to true to use a previously registered baseline for this facet.
      • isUseBaseline

        public boolean isUseBaseline()
        Returns true if a previously registered baseline should be used.
      • setResetBaseline

        public void setResetBaseline​(boolean enable)
        Set to true to reset the counts of an existing baseline for this facet to the counts of its most recent refinement.
        Since:
        TRIP 8.0
      • isResetBaseline

        public boolean isResetBaseline()
        Returns true if the counts of existing baseline are to be reset.
        Since:
        TRIP 8.0
      • setBaselineKey

        public void setBaselineKey​(java.lang.String key)
        Set a key identifying the facet baseline to set or use. This is by default the same as the name supplied to the constructor. You will normally not have to set this property, unless you have more than one field term facet for the same field, or you have a search facet against the same field as a field term facet.
        Parameters:
        key - Baseline key
      • getBaselineKey

        public java.lang.String getBaselineKey()
        Gets the key identifying the facet baseline to set or use. By
      • close

        public abstract void close()
        Closes this facet by releasing server-side resources and removes the the accumulated state from the object.
      • clear

        public void clear()
        Clears accumulated state from this object.
      • getValue

        public abstract TdbFacetValue getValue​(int index)
                                        throws TdbException
        Retrieve a facet value object.
        Parameters:
        index - 0-based index of facet value
        Returns:
        TdbFacetValue object
        Throws:
        TdbException - If facet value could not be returned.