com.tietoenator.trip.jxp.data

## Class TdbSearch

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

- All Implemented Interfaces:
    java.lang.Iterable<TdbSearchSet>

      public class TdbSearch
      extends TdbMessageProvider
      implements java.lang.Iterable<TdbSearchSet>

  Provides functionality for search and retrieval.

  This class provides high-level functionality pertaining to search and retrieval; it uses the same protocols as the TdbRecordSet and the TdbCclCommand classes to communicate with the server.

  For examples of how to use this class, please see the example classes com.tietoenator.trip.jxp.examples.data.Search and com.tietoenator.trip.jxp.examples.data.SearchSetIteration.

- - ### Constructor Summary

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

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `TdbSearchSet` | `addSearchSet(int searchId)` Associates a pre-existing search set with this TdbSearch instance.
    `void` | `cancel()` Cancel xml transaction
    `void` | `clear()` Resets the state of the TdbSearch object.
    `void` | `close()` Release server resources associated with this TdbSearch instance.
    `void` | `execute(java.lang.String cclStatement)` Execute a CCL statement.
    `void` | `executeXPath(java.lang.String xpathStatement)` Execute an XPath statement as a query.
    `TdbKernelWindow` | `getAffectedWindow()` Returns a TdbKernelWindow object for the the kernel window affected by the most recent command.
    `boolean` | `getAutomaticRetrievalTemplate()` Determines if retrieval templates are to be automatically created (default: true).
    `TdbCclCommandType` | `getCommandType()` Retrieve the type of command executed.
    `java.lang.String` | `getCurrentBase()` Retrieve the name of the currently open database or cluster.
    `java.lang.String` | `getCurrentThesaurusDef()` Returns the definition string used for the currently defined thesaurus, or an empty string if no thesaurus is defined.
    `java.lang.String` | `getCurrentThesaurusName()` Returns the name of the currently defined thesaurus, or an empty string if no thesaurus is defined.
    `boolean` | `getHistoryDelta()` For commands that may result in more than one search set, indicates if all resulting sets are returned as TdbSearchSet instances instead of just the latest one.
    `TdbSearchSet` | `getLastSearchSet()` Returns a TdbSearchSet object for the last search conducted via this TdbSearch instance.
    `int` | `getLastSearchSetCount()` The number of search sets generated or affected by the last CCL command execution via this TdbSearch object.
    `TdbSearchSet` | `getSearchSet(int index)` Returns a TdbSearchSet object for a search associated with this TdbSearch instance.
    `TdbSearchSet` | `getSearchSetById(int searchId)` Retrieve a TdbSearchSet object for the specified search id.
    `int` | `getSearchSetCount()` The number of search sets associated with this TdbSearch object.
    `int[]` | `getSearchSetNumbers()` An array of the search set numbers associated with this search set.
    `TdbTermList` | `getTermList()` Get the instance of TdbTermList that handles the results of non-hierarchical DISPLAY commands.
    `int` | `getTermListTimeout()` Get timeout for on-demand term lists generated by future DISPLAY commands.
    `TdbTermTree` | `getTermTree()` Get the instance of TdbTermTree that handles the results of hierarchical (i.e.
    `boolean` | `getUseOnDemandTermLists()` Returns true if term lists created via this TdbSearch instance are on-demand and also possible to use concurrently.
    `boolean` | `isHistoryReplaced()` Returns true if the last command resulted in a total replacement of the search history was received from the server, and false if either no, one or a handful of sets were received.
    `java.util.Iterator<TdbSearchSet>` | `iterator()` Returns an iterator over the search sets in the current search object.
    `java.util.List<TdbSearchSet>` | `searchSets()` A read-only list of the TdbSearchSet objects associated with this TdbSearch instance.
    `void` | `setAutomaticRetrievalTemplate(boolean enable)` Determines if retrieval templates are to be automatically created (default: true).
    `void` | `setCancelable(boolean cancelable)` Set cancelable state
    `void` | `setHistoryDelta(boolean enable)` For commands that may result in more than one search set, request that all resulting sets are returned as TdbSearchSet instances instead of just the latest one.
    `void` | `setRetrievalTemplate(TdbRecord newTemplate)` Set the default retrieval template for records to retrieve.
    `void` | `setTermList(TdbTermList terms)` Assign a new instance of TdbTermList to handle the results of non-hierarchical DISPLAY commands.
    `void` | `setTermListTimeout(int seconds)` Set timeout for on-demand term lists generated by future DISPLAY commands.
    `void` | `setUseOnDemandTermLists(boolean enable)` Enable or disable the use of the on-demand term list feature.

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

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

- - ### Constructor Detail

    - #### TdbSearch

          public TdbSearch(TdbSession session)
                    throws TdbException

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

  - ### Method Detail

    - #### getLastSearchSet

          public TdbSearchSet getLastSearchSet()

      Returns a TdbSearchSet object for the last search conducted via this TdbSearch instance. The TdbSearchSet instance returned is to be regarded as volatile. A DELETE or RENUM command, for instance, may cause the search set to be deleted or renumbered. The application should therefore not keep any copies of TdbSearchSet instances, but instead access them when required via the properties on the TdbSearch class.
      Returns:
        A TdbSearchSet instance, or NULL if no search has yet been done.

    - #### searchSets

          public java.util.List<TdbSearchSet> searchSets()

      A read-only list of the TdbSearchSet objects associated with this TdbSearch instance.
      Returns:
        A list of TdbSearchSet objects.

    - #### getSearchSetCount

          public int getSearchSetCount()

      The number of search sets associated with this TdbSearch object.
      Returns:
        Search set count

    - #### getLastSearchSetCount

          public int getLastSearchSetCount()

      The number of search sets generated or affected by the last CCL command execution via this TdbSearch object.
      Returns:
        Affected search set count
      See Also:
        `TdbSearch.isHistoryReplaced()`, `TdbSearch.setHistoryDelta(boolean)`

    - #### isHistoryReplaced

          public boolean isHistoryReplaced()

      Returns true if the last command resulted in a total replacement of the search history was received from the server, and false if either no, one or a handful of sets were received.

      A total history replacement is normally the result of commands like RENUM, DELETE and LIST. The RUN command will by default also result in this, unless history deltas are enabled for this TdbSearch object.

      Returns:
        True if history was replaced and false if it was updated
      See Also:
        `TdbSearch.setHistoryDelta(boolean)`, `TdbSearch.getLastSearchSetCount()`

    - #### getSearchSetNumbers

          public int[] getSearchSetNumbers()

      An array of the search set numbers associated with this search set.
      Returns:
        Search set number array.

    - #### getSearchSet

          public TdbSearchSet getSearchSet(int index)
                                    throws TdbException

      Returns a TdbSearchSet object for a search associated with this TdbSearch instance.
      Parameters:
        `index` - The zero-based index of the search set in this TdbSearch
      Returns:
        A TdbSearchSet object
      Throws:
        `TdbException`

    - #### addSearchSet

          public TdbSearchSet addSearchSet(int searchId)
                                    throws TdbException

      Associates a pre-existing search set with this TdbSearch instance. The search set being added must not be previously assoicated with any TdbSearch instance.
      Parameters:
        `searchId` - ID of search set to associate with this TdbSearch instance.
      Returns:
        A TdbSearchSet object for the added search set
      Throws:
        `TdbException`

    - #### getAffectedWindow

          public TdbKernelWindow getAffectedWindow()

      Returns a TdbKernelWindow object for the the kernel window affected by the most recent command. If the last command failed, or if no kernel window is available, this property will return null. Use the this method when you have executed a command that results in TRIP kernel window output of some sort. Accessing the result of a SHOW command is the most typical use of this method.
      Returns:
        A TdbKernelWindow instance for the kernel window affected by the most recent command.

    - #### getCommandType

          public TdbCclCommandType getCommandType()

      Retrieve the type of command executed. Retrieve the type of command executed, at a very broad level. The value of this property is a command type taken from the TdbCclCommandType enumeration. From this, the calling application can determine what further properties are appropriate to use in response to the execution of the command.
      Returns:
        The type of the command most recently executed.

    - #### getTermList

          public TdbTermList getTermList()

      Get the instance of TdbTermList that handles the results of non-hierarchical DISPLAY commands.
      Returns:
        A TdbTermList instance.

    - #### setTermList

          public void setTermList(TdbTermList terms)

      Assign a new instance of TdbTermList to handle the results of non-hierarchical DISPLAY commands.
      Parameters:
        `terms` - A TdbTermList instance.

    - #### getTermTree

          public TdbTermTree getTermTree()

      Get the instance of TdbTermTree that handles the results of hierarchical (i.e. thesaurus) DISPLAY commands.
      Returns:
        A TdbTermTree instance.

    - #### setRetrievalTemplate

          public void setRetrievalTemplate(TdbRecord newTemplate)

      Set the default retrieval template for records to retrieve. Not setting this property to a template matching the database being queried will result in empty records returned via the TdbSearchSet instances.
      Parameters:
        `newTemplate` - The retrieval template to assign as default for search sets subsequently created via this TdbSearch object.

    - #### getAutomaticRetrievalTemplate

          public boolean getAutomaticRetrievalTemplate()

      Determines if retrieval templates are to be automatically created (default: true). If set to true, a retrieval template is automatically created upon the first successful search from a physical database. Pre-existing search sets will not be affected; they will continue to be associated with the former retrieval template. The template will be reused for subsequent searches in the same database. When the application changes database (i.e. using the BASE command), the automatic retrieval template assigned to new search sets will also change. An automatic retrieval template contains all the fields in a database. This property does NOT APPLY for cluster searches.
      Returns:
        True if automatic retrieval templates are enabled.

    - #### setAutomaticRetrievalTemplate

          public void setAutomaticRetrievalTemplate(boolean enable)

      Determines if retrieval templates are to be automatically created (default: true). In order to reduce unecessary network traffic, this property should be set to false, especially when searching in clusters, or when only a limited number of fields are of interest to the application. If set to true, a retrieval template is automatically created upon the first successful search from a physical database. Pre-existing search sets will not be affected; they will continue to be associated with the former retrieval template. The template will be reused for subsequent searches in the same database. When the application changes database (i.e. using the BASE command), the automatic retrieval template assigned to new search sets will also change. An automatic retrieval template contains all the fields in a database. This property does NOT APPLY for cluster searches.
      Parameters:
        `enable` - True to enable automatic retrieval templates.

    - #### getCurrentBase

          public java.lang.String getCurrentBase()

      Retrieve the name of the currently open database or cluster.
      Returns:
        Name of current database or cluster.

    - #### getCurrentThesaurusName

          public java.lang.String getCurrentThesaurusName()

      Returns the name of the currently defined thesaurus, or an empty string if no thesaurus is defined.

      At least one CCL command that has caused the thesaurus definition to change or generated a search set must have been issued using this TdbSearch instance before thesaurus information is available.

      This method requires TRIPsystem 8.0-2 or later.

    - #### getCurrentThesaurusDef

          public java.lang.String getCurrentThesaurusDef()

      Returns the definition string used for the currently defined thesaurus, or an empty string if no thesaurus is defined.

      At least one CCL command that has caused the thesaurus definition to change or generated a search set must have been issued using this TdbSearch instance before thesaurus information is available.

      This method requires TRIPsystem 8.0-2 or later.

    - #### getUseOnDemandTermLists

          public boolean getUseOnDemandTermLists()

      Returns true if term lists created via this TdbSearch instance are on-demand and also possible to use concurrently.
      Returns:
        True if on-demand term lists are used.
      See Also:
        `TdbTripFeature.OnDemandTermLists`

    - #### setUseOnDemandTermLists

          public void setUseOnDemandTermLists(boolean enable)
                                       throws TdbException

      Enable or disable the use of the on-demand term list feature.
      Parameters:
        `enable` - True to use on-demand term lists
      Throws:
        `TdbException` - If on-demand term lists cannot be enabled
      See Also:
        `TdbTripFeature.OnDemandTermLists`

    - #### setTermListTimeout

          public void setTermListTimeout(int seconds)

      Set timeout for on-demand term lists generated by future DISPLAY commands.

      On-demand term lists requires resources on the server to keep alive. By default, they will time out in 120 seconds. After an on-demand term list has timed out, terms from it will no longer be possible to retrieve by the application without executing the DISPLAY order again.

      Although it isn't always a good practise to do so, the timeout can be disabled by setting this value to zero.

      Parameters:
        `seconds` - Timeout to set
      See Also:
        `TdbSearch.setUseOnDemandTermLists(boolean)`

    - #### getTermListTimeout

          public int getTermListTimeout()

      Get timeout for on-demand term lists generated by future DISPLAY commands.

      On-demand term lists requires resources on the server to keep alive. By default, they will time out in 120 seconds. After an on-demand term list has timed out, terms from it will no longer be possible to retrieve by the application without executing the DISPLAY order again.

      Returns:
        Timeout in seconds, or zero if timeout has been disabled.

    - #### setHistoryDelta

          public void setHistoryDelta(boolean enable)

      For commands that may result in more than one search set, request that all resulting sets are returned as TdbSearchSet instances instead of just the latest one.

      Requires TRIPsystem 8.2-3 or later

      Parameters:
        `enable` - Enable or disable retrieval of search history deltas.
      Since:
        8.2-2

    - #### getHistoryDelta

          public boolean getHistoryDelta()

      For commands that may result in more than one search set, indicates if all resulting sets are returned as TdbSearchSet instances instead of just the latest one.

      Requires TRIPsystem 8.2-3 or later

      Returns:
        True if history deltas are to be returned and false otherwise.
      Since:
        8.2-2

    - #### clear

          public void clear()

      Resets the state of the TdbSearch object. All search sets associated with this TdbSearch instance are deleted. The kernel window state and the retrieval template is also reset to default.

    - #### close

          public void close()
                     throws TdbException

      Release server resources associated with this TdbSearch instance. This includes kernel windows and search sets.

      After a call to this method, the current TdbSearch instance is no longer valid.

      Throws:
        `TdbException`

    - #### getSearchSetById

          public TdbSearchSet getSearchSetById(int searchId)

      Retrieve a TdbSearchSet object for the specified search id.
      Parameters:
        `searchId` - The id number of the search set to retrieve.
      Returns:
        The requested TdbSearchSet instance, or null if not found.

    - #### execute

          public void execute(java.lang.String cclStatement)
                       throws TdbException

      Execute a CCL statement.

      This method accepts any type of CCL command, and not only those that generate search sets. The state of the TdbSearch object after a successful call will reflect the command just executed.

      Parameters:
        `cclStatement` - Statement to execute
      Throws:
        `TdbException`

    - #### executeXPath

          public void executeXPath(java.lang.String xpathStatement)
                            throws TdbException

      Execute an XPath statement as a query.

      This method executes an XPath statement as a query. An XML database must be open in order for this to work. Also, the server to which the current session is connected runs TRIPsystem 6.2-7 or later and TRIPxml 3.0 or later.

      Parameters:
        `xpathStatement` - Statement to execute
      Throws:
        `TdbException`

    - #### iterator

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

      Returns an iterator over the search sets in the current search object.
      Specified by:
        `iterator` in interface `java.lang.Iterable<TdbSearchSet>`

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