com.tietoenator.trip.jxp.data

## Class TdbSearchSet

- java.lang.Object
- - com.tietoenator.trip.jxp.session.TdbSessionObject
  - - com.tietoenator.trip.jxp.data.TdbSearchSet

- All Implemented Interfaces:
    com.tietoenator.trip.jxp.internal.utils.DOMSink, java.lang.Iterable<TdbRecord>

      public class TdbSearchSet
      extends TdbSessionObject
      implements java.lang.Iterable<TdbRecord>, com.tietoenator.trip.jxp.internal.utils.DOMSink

  Represents a TRIP search set.

  This class is able to enumerate the records in the search set. Records are fetched in blocks of 10 from the server as required.

  The TdbSearchSet class employs a cache of configurable size that holds blocks of records recently accessed. When a record is accessed that is not available in the cache, it is fetched from the server. If the cache is full at that time, the least recently used region of records is removed and replaced with the new one.

- - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `org.w3c.dom.Document` | `asFragmentSet(java.lang.String xpathExpression, int from, int to, boolean hitMarkup)` Get this search set as an XML fragment set.
    `void` | `cancel()` Cancel xml transaction
    `void` | `clearCache()` Clears the record cache.
    `void` | `delete()` Delete the current search set.
    `int` | `getCacheSize()` Get the size of the record cache.
    `java.lang.String` | `getDatabase()` Retrieve the name of the database or cluster that was used with the search.
    `java.lang.String` | `getDidYouMean()` Returns a "did-you-mean" suggestion for the command just executed.
    `int` | `getHitCount()` The total number of hits in the search set.
    `long` | `getLongHitCount()` The total number of hits in the search set.
    `long` | `getLongRecordCount()` The number of records in the search set.
    `java.lang.String` | `getParsedCommand()` Retrieve a constructed version of the command with fully expanded tokens, suitable for display to an end user.
    `TdbRecord` | `getRecord(int index)` Returns a TdbRecord instance for a record in the current search set.
    `TdbRecord` | `getRecord(long index)` Returns a TdbRecord instance for a record in the current search set.
    `int` | `getRecordCount()` The number of records in the search set.
    `TdbRecord` | `getRetrievalTemplate()` Get the retrieval template for records to retrieve.
    `boolean` | `getRetrieveReversed()` Get whether to retrieve the result set in reverse.
    `int` | `getSearchId()` The numeric ID of the search set.
    `java.lang.String` | `getSortKeys()` Get a comma-separated list of field names to use as sort criteria.
    `TdbSortMergeType` | `getSortMerge()` Returns the order in which records from different databases should be ordered when sorting a search result from a database cluster.
    `boolean` | `getSortRanked()` Get whether results should be sorted by relevance.
    `java.util.Iterator<TdbRecord>` | `iterator()` Returns an iterator over the records in the current search set.
    `void` | `setCacheSize(int maxBlocks)` Set the size of the record cache.
    `void` | `setCancelable(boolean cancelable)` Set cancelable state
    `void` | `setRetrievalTemplate(TdbRecord newTemplate)` Set the retrieval template for records to retrieve.
    `void` | `setRetrieveReversed(boolean reversed)` Set whether to retrieve the result set in reverse.
    `void` | `setSortKeys(java.lang.String newSortKeys)` Get a comma-separated list of field names to use as sort criteria.
    `void` | `setSortMerge(TdbSortMergeType mergetype)` Define the order in which records from different databases should be ordered when sorting a search result from a database cluster.
    `void` | `setSortRanked(boolean ranked)` Get whether results should be sorted by relevance.

    - ### Methods inherited from class com.tietoenator.trip.jxp.session.TdbSessionObject

      `getSession, isCancelable`

    - ### 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`

    - ### Methods inherited from interface com.tietoenator.trip.jxp.internal.utils.DOMSink

      `sinkNode`

- - ### Method Detail

    - #### getSearchId

          public int getSearchId()

      The numeric ID of the search set.
      Returns:
        Search set id.

    - #### getRecordCount

          public int getRecordCount()

      The number of records in the search set.
      Returns:
        Record count If the record count is larger than Integer.MAX_VALUE, this property will return Integer.MAX_VALUE. To get the actual record count of search sets with more than Integer.MAX_VALUE records, use the #getLongRecordCount() method.

    - #### getLongRecordCount

          public long getLongRecordCount()

      The number of records in the search set.
      Returns:
        Record count

    - #### getHitCount

          public int getHitCount()

      The total number of hits in the search set.
      Returns:
        Hit count If the hit count is larger than Integer.MAX_VALUE, this property will return Integer.MAX_VALUE. To get the actual hit count of search sets with more than Integer.MAX_VALUE hits, use the #getLongHitCount() method.

    - #### getLongHitCount

          public long getLongHitCount()

      The total number of hits in the search set.
      Returns:
        Hit count

    - #### getDatabase

          public java.lang.String getDatabase()

      Retrieve the name of the database or cluster that was used with the search.

      This property requires TRIPsystem 7.2-1 or later on the server. For older TRIPsystem versions, this property will return an empty string.

      Returns:
        The database name
      Since:
        7.2-1

    - #### getParsedCommand

          public java.lang.String getParsedCommand()

      Retrieve a constructed version of the command with fully expanded tokens, suitable for display to an end user.
      Returns:
        The CCL command that generated this search set.

    - #### getDidYouMean

          public java.lang.String getDidYouMean()

      Returns a "did-you-mean" suggestion for the command just executed. This is an alternative CCL command that is likely to yield a greater amount of hits. Only the FUZZ command can result in a did-you-mean suggestion, and requires TRIPsystem v6.2 or later in order to do so.
      Returns:
        An alternative CCL command, or an empty string if nothing is available.

    - #### getSortKeys

          public java.lang.String getSortKeys()

      Get a comma-separated list of field names to use as sort criteria.
      Returns:
        The current sort key specifciation.

    - #### setSortKeys

          public void setSortKeys(java.lang.String newSortKeys)

      Get a comma-separated list of field names to use as sort criteria.
      Parameters:
        `newSortKeys` - Sort key specification

    - #### getRetrieveReversed

          public boolean getRetrieveReversed()

      Get whether to retrieve the result set in reverse.
      Returns:
        True if records are to be retrieved from the set in reverse order.

    - #### setRetrieveReversed

          public void setRetrieveReversed(boolean reversed)

      Set whether to retrieve the result set in reverse.
      Parameters:
        `reversed` - True to retrieve records from the set in reverse order.

    - #### getSortRanked

          public boolean getSortRanked()

      Get whether results should be sorted by relevance.
      Returns:
        True if sort by relevance

    - #### setSortRanked

          public void setSortRanked(boolean ranked)

      Get whether results should be sorted by relevance.
      Parameters:
        `ranked` - True to sort by relevance

    - #### setSortMerge

          public void setSortMerge(TdbSortMergeType mergetype)

      Define the order in which records from different databases should be ordered when sorting a search result from a database cluster.
      Parameters:
        `mergetype` - The merge type to use for the request.

    - #### getSortMerge

          public TdbSortMergeType getSortMerge()

      Returns the order in which records from different databases should be ordered when sorting a search result from a database cluster.
      Returns:
        A TdbSortMergeType instance definining the merge choice

    - #### asFragmentSet

          public org.w3c.dom.Document asFragmentSet(java.lang.String xpathExpression,
                                                    int from,
                                                    int to,
                                                    boolean hitMarkup)
                                             throws TdbException

      Get this search set as an XML fragment set.

      This method can only be used when the current search set contains records from an XML database and the server to which the current session is connected runs TRIPsystem 6.2-7 or later and TRIPxml 3.0 or later.

      Note that the retrieved fragments will only be those matched by the supplied XPATH expression; if this expression does not match a certain record in the current search set, no fragments (and hence no information) from that record will be retrived.

      Please refer to the TRIPxml documentation for information on valid XPath syntax for TRIP.

      Parameters:
        `xpathExpression` - An XPath expression that evaulates to the node set to use as fragment roots
        `from` - The lower bound of the range of records in the search set that will be covered by the fragment set. Pass -1 for no lower bound.
        `to` - The upper bound of the range of records in the search set that will be covered by the fragment set. Pass -1 for no upper bound.
        `hitMarkup` - Set to true to apply hit markup to the fragments.
      Returns:
        An XML Document instance representing the fragment set.
      Throws:
        `TdbException`

    - #### getCacheSize

          public int getCacheSize()

      Get the size of the record cache. The value of this property is the number of blocks of 10 records the cache can hold. A CacheSize of 10 (the default) means that the cache can hold up to 100 records.
      Returns:
        The size of the cache (in blocks of 10 records).

    - #### setCacheSize

          public void setCacheSize(int maxBlocks)
                            throws TdbException

      Set the size of the record cache. The value of this property is the number of blocks of 10 records the cache can hold. A CacheSize of 10 (the default) means that the cache can hold up to 100 records.
      Parameters:
        `maxBlocks` - The new cache size in number of blocks of 10 records.
      Throws:
        `TdbException` - If the value assigned is not a positive integer.

    - #### clearCache

          public void clearCache()

      Clears the record cache.

    - #### getRetrievalTemplate

          public TdbRecord getRetrievalTemplate()

      Get the retrieval template for records to retrieve.

      This property will default to the retrieval template defined for the TdbSearch instance that provided this object. If the retrieval template is not set, either in the associated TdbSearch object, or directly on this object using the setRetrievalTemplate method, no field values will be returned for the records accessible via this object.

      Returns:
        The current retrieval template for this search set.

    - #### setRetrievalTemplate

          public void setRetrievalTemplate(TdbRecord newTemplate)

      Set the retrieval template for records to retrieve.

      This property will default to the retrieval template defined for the TdbSearch instance that provided this object. If the retrieval template is not set, either in the associated TdbSearch object, or directly on this object using this property, no field values will be returned for the records accessible via this object.

      If you wish to change the retrieval template after having retrieved some records, you must first call the clearCache method. This makes sure that the records you access after having changed the retreival template actually will be retrieved according to the new template specification.

      Parameters:
        `newTemplate` - The new retrieval template to assign.

    - #### delete

          public void delete()
                      throws TdbException

      Delete the current search set.

      After a successful call to this method, the current TdbSearchSet instance is no longer valid and must no longer be used.

      Throws:
        `TdbException` - If the delete operation failed.

    - #### getRecord

          public TdbRecord getRecord(int index)
                              throws TdbException

      Returns a TdbRecord instance for a record in the current search set.
      Parameters:
        `index` - The zero-based index of the record in the search set.
      Returns:
        A TdbRecord instance If the requested record is in the cache, it will be returned from there. Otherwise, the appropriate block of 10 records will be fetched from the server, cached, and the requested record returned to the caller. If the cache has reached its size limit, the least recently used block of records will be removed from the cache to make room for the new one. To retrieve records with an index larger than Integer.MAX_VALUE (2147483647), use the #getRecord(long) method.
      Throws:
        `TdbException`
      See Also:
        `TdbSearchSet.getRecord(long)`

    - #### getRecord

          public TdbRecord getRecord(long index)
                              throws TdbException

      Returns a TdbRecord instance for a record in the current search set. If the requested record is in the cache, it will be returned from there. Otherwise, the appropriate block of 10 records will be fetched from the server, cached, and the requested record returned to the caller. If the cache has reached its size limit, the least recently used block of records will be removed from the cache to make room for the new one.
      Parameters:
        `index` - The zero-based index of the record in the search set.
      Returns:
        A TdbRecord instance
      Throws:
        `TdbException`

    - #### iterator

          public java.util.Iterator<TdbRecord> iterator()

      Returns an iterator over the records in the current search set.
      Specified by:
        `iterator` in interface `java.lang.Iterable<TdbRecord>`

    - #### setCancelable

          public void setCancelable(boolean cancelable)
                             throws TdbException

      Description copied from class: `TdbSessionObject`
      Set cancelable state
      Overrides:
        `setCancelable` in class `TdbSessionObject`
      Parameters:
        `cancelable` - true if object is cancelable
      Throws:
        `TdbException`

    - #### cancel

          public void cancel()
                      throws TdbException

      Description copied from class: `TdbSessionObject`
      Cancel xml transaction
      Overrides:
        `cancel` in class `TdbSessionObject`
      Throws:
        `TdbException`