com.tietoenator.trip.jxp.data

## Class TdbRecordSet

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

- All Implemented Interfaces:
    com.tietoenator.trip.jxp.internal.utils.DOMSink
  Direct Known Subclasses:
    TdbGridRecordSet

      public class TdbRecordSet
      extends TdbMessageProvider
      implements com.tietoenator.trip.jxp.internal.utils.DOMSink

  Container and manipulation logic for a set of records from a database or query.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `TdbRecordSet(TdbSession session)` Constructor, creates a blank instance

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clear()` Clear the record set of any content retrieved by a get() operation This version of the method does not reset the record set to its default state, simply removes any accumulated TdbRecord instances.
    `void` | `delete()` Delete the records covered by the record set from their database(s)
    `void` | `get()` Retrieve the record set defined by the various properties of the instance.
    `org.w3c.dom.Document` | `get(TdbDataFormat fmt)` Retrieve the record set defined by the various properties of the instance.
    `int` | `getAffectedRecords()` Retrieve the number of records affected by the most recent operation This method will return the number of records (total) hit by the most recent search, or the number of records affected by the most recent insert, update or delete, depending on what the most recent activity was.
    `java.lang.String` | `getDatabase()` Retrieve the name of the database that provides the context for the record set
    `java.lang.String` | `getDidYouMean()` Returns a "did-you-mean" suggestion for the query that produced the last retrieved record set.
    `int` | `getFrom()` Retrieve the lower bound of the record set's domain
    `int` | `getId()` Retrieve the unique ID of the single record covered by this record set
    `long` | `getLongHitCount()` Retrieve the number of terms hitby the last query-driven retrieval.
    `long` | `getLongRecordCount()` Retrieve the number of records affected by the most recent operation.
    `int` | `getMapMax()` Retrieve any maximum value established for performing mapped searches (retrieval only)
    `java.lang.String` | `getName()` Retrieve the name of the single record covered by this record set
    `java.lang.String` | `getQuery()` Retrieve any query string that has been established as a retrieval context
    `int` | `getQueryHits()` Retrieve the number of terms hit by the last query-driven retrieval.
    `int` | `getQueryRecords()` Retrieve the number of records (total) hit by the last query-driven retrieval
    `int` | `getSearchSet()` Retrieve the ID of the search set with which the record will be associated
    `java.lang.String` | `getSortKeys()` Retrieve the comma-separated list of sort keys
    `int` | `getSortMax()` Retrieve any maximum value established for sorting with the record set (retrieval only)
    `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()` Check if the record set's retrieval operations are to be sorted by relevance rank
    `java.lang.String` | `getThesaurus()` Retrieve the name of the thesaurus used with the query for the record set.
    `int` | `getTo()` Retrieve the upper bound of the record set's domain
    `void` | `insert(java.util.Collection<TdbRecord> records)` Insert new records to the database associated with this record set
    `boolean` | `isQueryCCL()` Check if the provided query statement is in CCL
    `boolean` | `isQuerySQL()` Check if the provided query statement in is SQL
    `boolean` | `isQueryXPath()` Check if the provided query statement in is XPath
    `TdbRecord` | `recordAt(int offset)` Retrieve the TdbRecord at the defined offset within the set If the provided offset is outside of the bounds of the record set, an INVALID_ARGS exception is thrown.
    `java.util.List<TdbRecord>` | `records()` Retrieve the collection of records retrieved most recently by the get() method from the server
    `void` | `reset()` Clear the record set and all associated parameters All properties of the record set are reset by this method to their default state, rendering the record unusable until properties are reestablished
    `void` | `setDatabase(java.lang.String name)` Set the name of the database (or thesaurus, or cluster) that will provide the context for the record set
    `void` | `setFrom(int from)` Establish the lower bound of a ranged record set domain.
    `void` | `setId(int id)` Establish the unique ID of the single record covered by this record set
    `void` | `setMapMax(int max)` Establish the maximum number of records that will be mapped during a retrieval operation
    `void` | `setName(java.lang.String name)` Establish the name of the record covered by this record set.
    `void` | `setQuery(java.lang.String query)` Set a query statement that will be used to retrieve records
    `void` | `setQueryCCL(boolean ccl)` Establish whether the query statement is in CCL
    `void` | `setQuerySQL(boolean sql)` Establish whether the query statement is in SQL
    `void` | `setQueryXPath(boolean xpath)` Establish whether the query statement is an XPath expression.
    `void` | `setRange(long from, long to)` Set range of records to retrieve when the range's end position extends beyond Integer MAX_VALUE.
    `void` | `setRetrievalTemplate(TdbRecord template)` Set the record set template, i.e.
    `void` | `setRetrieveReversed(boolean rev)` Set whether to retrieve the result set in reverse.
    `void` | `setSearchSet(int srch)` Establish the ID of the search set with which the record will be associated
    `void` | `setSortKeys(java.lang.String keys)` Establish sort criteria for the record set (retrieval only)
    `void` | `setSortMax(int max)` Establish the maximum number of records that will be sorted during a retrieval operation
    `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 rank)` Establish whether the record set's retrieval operations are to be sorted by relevance rank
    `void` | `setThesaurus(java.lang.String thes)` Set the name of a thesaurus to use in the query for the record set.
    `void` | `setTo(int to)` Establish the upper bound of a ranged record set domain.
    `void` | `update(TdbRecord values)` Apply the same update transformation to all records covered by the record set

    - ### Methods inherited from class com.tietoenator.trip.jxp.TdbMessageProvider

      `codeList, getLastCode, getLastMessage, hasMessages, messageList, resetMessages`

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

      `cancel, getSession, isCancelable, setCancelable`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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

      `sinkNode`

- - ### Constructor Detail

    - #### TdbRecordSet

          public TdbRecordSet(TdbSession session)
                       throws TdbException

      Constructor, creates a blank instance
      Parameters:
        `session` - Active session
      Throws:
        `TdbException`

  - ### Method Detail

    - #### getQuery

          public java.lang.String getQuery()

      Retrieve any query string that has been established as a retrieval context
      Returns:
        Query string

    - #### setQuery

          public void setQuery(java.lang.String query)
                        throws TdbException

      Set a query statement that will be used to retrieve records

      Setting a query as the domain of the record set works in conjunction with the setDatabase() setting, i.e. the query works within the context of the database. The setting of a record range, using the setFrom(), setTo(), or setId() methods becomes relative to the search set generated by the query. The use of the setName() method is not legal when setting a query, and any attempt to set the value of this property after having established a name will result in an INVALID_ARGS exception being thrown. Also note that if the database property is not set, the query defined here must define its own context, e.g. using the CCL Find Save statement.

      Parameters:
        `query` - The query statement
      Throws:
        `TdbException`

    - #### isQueryCCL

          public boolean isQueryCCL()

      Check if the provided query statement is in CCL
      Returns:
        True if the provided query is CCL

    - #### setQueryCCL

          public void setQueryCCL(boolean ccl)

      Establish whether the query statement is in CCL
      Parameters:
        `ccl` - True if the provided query is in CCL

    - #### isQuerySQL

          public boolean isQuerySQL()

      Check if the provided query statement in is SQL
      Returns:
        True if the query is in SQL

    - #### isQueryXPath

          public boolean isQueryXPath()

      Check if the provided query statement in is XPath
      Returns:
        True if the query is in XPath

    - #### setQuerySQL

          public void setQuerySQL(boolean sql)

      Establish whether the query statement is in SQL
      Parameters:
        `sql` - True if the provided query is in SQL, false otherwise

    - #### setQueryXPath

          public void setQueryXPath(boolean xpath)

      Establish whether the query statement is an XPath expression.
      Parameters:
        `xpath` - True if the provided query is in XPath, false otherwise

    - #### getQueryRecords

          public int getQueryRecords()

      Retrieve the number of records (total) hit by the last query-driven retrieval
      Returns:
        Number of records hit by the last query

    - #### getAffectedRecords

          public int getAffectedRecords()

      Retrieve the number of records affected by the most recent operation
      This method will return the number of records (total) hit by the most recent search, or the number of records affected by the most recent insert, update or delete, depending on what the most recent activity was.
      Returns:
        Number of records affected by last operation

    - #### getLongRecordCount

          public long getLongRecordCount()

      Retrieve the number of records affected by the most recent operation. This property should be used instead of #getAffectedRecords() and #getQueryRecords() in case the result contains more than Integer.MAX_VALUE records.
      Since:
        8.0

    - #### getQueryHits

          public int getQueryHits()

      Retrieve the number of terms hit by the last query-driven retrieval.
      Returns:
        Number of hits

    - #### getLongHitCount

          public long getLongHitCount()

      Retrieve the number of terms hitby the last query-driven retrieval.
      Returns:
        Number of hits This property should be used instead of #getQueryHits() in case the result contains more than Integer.MAX_VALUE hits.
      Since:
        8.0

    - #### getDidYouMean

          public java.lang.String getDidYouMean()

      Returns a "did-you-mean" suggestion for the query that produced the last retrieved record set. This is an alternative query that will 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 query or an empty string.

    - #### getDatabase

          public java.lang.String getDatabase()

      Retrieve the name of the database that provides the context for the record set
      Returns:
        Database name

    - #### setDatabase

          public void setDatabase(java.lang.String name)

      Set the name of the database (or thesaurus, or cluster) that will provide the context for the record set
      Parameters:
        `name` - Name of database, thesaurus or cluster

    - #### getThesaurus

          public java.lang.String getThesaurus()

      Retrieve the name of the thesaurus used with the query for the record set.
      Returns:
        Thesaurus name

    - #### setThesaurus

          public void setThesaurus(java.lang.String thes)

      Set the name of a thesaurus to use in the query for the record set.
      Parameters:
        `thes` - Name of thesaurus

    - #### getSearchSet

          public int getSearchSet()

      Retrieve the ID of the search set with which the record will be associated
      Returns:
        Search set unique ID

    - #### setSearchSet

          public void setSearchSet(int srch)

      Establish the ID of the search set with which the record will be associated
      Parameters:
        `srch` - Search set unique ID

    - #### getFrom

          public int getFrom()

      Retrieve the lower bound of the record set's domain
      Returns:
        Lower bound

    - #### setFrom

          public void setFrom(int from)

      Establish the lower bound of a ranged record set domain.
      If this property is not set, and no other property is used to define the record set's bounds, the default is the lower limit of whatever context is defined, e.g. the start of the search set, or the first record in the database.
      Parameters:
        `from` - Lower bound

    - #### getTo

          public int getTo()

      Retrieve the upper bound of the record set's domain
      Returns:
        Upper bound

    - #### setTo

          public void setTo(int to)

      Establish the upper bound of a ranged record set domain.
      Parameters:
        `to` - Upper bound If this property is not set, and no other property is used to define the record set's retrieval range bounds, the default is the upper limit of whatever context is defined, e.g. the end of the search set, or the last record in the database.

    - #### setRange

          public void setRange(long from,
                               long to)

      Set range of records to retrieve when the range's end position extends beyond Integer MAX_VALUE.
      Parameters:
        `from` - Lower bound
        `to` - Upper bound
      Since:
        8.0

    - #### getId

          public int getId()

      Retrieve the unique ID of the single record covered by this record set
      Returns:
        The record's unique ID

    - #### setId

          public void setId(int id)

      Establish the unique ID of the single record covered by this record set
      Parameters:
        `id` - The record's unique ID

    - #### getName

          public java.lang.String getName()

      Retrieve the name of the single record covered by this record set
      Returns:
        Record name

    - #### setName

          public void setName(java.lang.String name)
                       throws TdbException

      Establish the name of the record covered by this record set.
      This property is invalid when the record set is defined as covering the result of a query, using the setQuery() method. Setting the value of this property after having set the query property will result in an INVALID_ARGS exception being thrown.
      Parameters:
        `name` - Record name
      Throws:
        `TdbException`

    - #### getSortKeys

          public java.lang.String getSortKeys()

      Retrieve the comma-separated list of sort keys
      Returns:
        Sort keys

    - #### setSortKeys

          public void setSortKeys(java.lang.String keys)

      Establish sort criteria for the record set (retrieval only)
      Parameters:
        `keys` - A comma-separated list of keys

    - #### getSortRanked

          public boolean getSortRanked()

      Check if the record set's retrieval operations are to be sorted by relevance rank
      Returns:
        True / false

    - #### setSortRanked

          public void setSortRanked(boolean rank)

      Establish whether the record set's retrieval operations are to be sorted by relevance rank
      Parameters:
        `rank` - If true, records will be primarily sorted by relevance, with any other sort keys being used as secondary sort criteria

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

    - #### setRetrieveReversed

          public void setRetrieveReversed(boolean rev)

      Set whether to retrieve the result set in reverse.
      Parameters:
        `rev` - If true, records will be returned from the search set in reverse.

    - #### getSortMax

          public int getSortMax()

      Retrieve any maximum value established for sorting with the record set (retrieval only)
      Returns:
        Sort max

    - #### setSortMax

          public void setSortMax(int max)

      Establish the maximum number of records that will be sorted during a retrieval operation
      Parameters:
        `max` - Sort max

    - #### getMapMax

          public int getMapMax()

      Retrieve any maximum value established for performing mapped searches (retrieval only)
      Returns:
        map max

    - #### setMapMax

          public void setMapMax(int max)

      Establish the maximum number of records that will be mapped during a retrieval operation
      Parameters:
        `max` - Map max

    - #### setRetrievalTemplate

          public void setRetrievalTemplate(TdbRecord template)

      Set the record set template, i.e. the fields and restrictions that are to be requested from the server.
      Parameters:
        `template` - The retrieval template

    - #### records

          public java.util.List<TdbRecord> records()

      Retrieve the collection of records retrieved most recently by the get() method from the server
      Returns:
        Any available records

    - #### reset

          public void reset()

      Clear the record set and all associated parameters
      All properties of the record set are reset by this method to their default state, rendering the record unusable until properties are reestablished

    - #### clear

          public void clear()

      Clear the record set of any content retrieved by a get() operation
      This version of the method does not reset the record set to its default state, simply removes any accumulated TdbRecord instances.

    - #### recordAt

          public TdbRecord recordAt(int offset)
                             throws TdbException

      Retrieve the TdbRecord at the defined offset within the set
      If the provided offset is outside of the bounds of the record set, an INVALID_ARGS exception is thrown. When a request is made to read the record at one index beyond the end of the set, i.e. the record "after" the last record, an END_OF_DATA exception is thrown.
      Parameters:
        `offset` - The zero-based offset within the set of the record to retrieve
      Returns:
        The appropriate record, if available
      Throws:
        `TdbException`

    - #### get

          public void get()
                   throws TdbException

      Retrieve the record set defined by the various properties of the instance.

      Any records retrieved are deserialized into a collection of TdbRecord objects that can be accessed using the records(), or recordAt() methods.

      This method causes network I/O.

      Throws:
        `TdbException`

    - #### get

          public org.w3c.dom.Document get(TdbDataFormat fmt)
                                   throws TdbException

      Retrieve the record set defined by the various properties of the instance.

      This method does not deserialize into the record collection, which will be blank after invocation.

      Values for any string fields requested are returned inline encoded as base64. This may result in a very large response document and may cause session timeout or lack of enough memory resources to complete processing. Make sure to set up the retrieval template to exclude any unnecessary STRING fields.

      This method causes network I/O.

      Parameters:
        `fmt` - The format of the XML to retrieve
      Returns:
        An XML document containing the records suitable for transformation
      Throws:
        `TdbException`

    - #### delete

          public void delete()
                      throws TdbException

      Delete the records covered by the record set from their database(s)

      This method causes network I/O.

      Throws:
        `TdbException`

    - #### update

          public void update(TdbRecord values)
                      throws TdbException

      Apply the same update transformation to all records covered by the record set

      This method causes network I/O.

      Parameters:
        `values` - A valid record, containing field updates to be applied to all records covered by the record set.
      Throws:
        `TdbException`

    - #### insert

          public void insert(java.util.Collection<TdbRecord> records)
                      throws TdbException

      Insert new records to the database associated with this record set

      Only the database (see setDatabase()) property is valid for this method. If the record set has been established using the setQuery() method, an INVALID_ARGS exception will be thrown.

      This method causes network I/O.

      Parameters:
        `records` - A collection of TdbRecord objects to be inserted to the named database
      Throws:
        `TdbException`