Class TdbSearch

All Implemented Interfaces:
Iterable<TdbSearchSet>

public class TdbSearch extends TdbMessageProvider implements 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 Details

  • Method Details

    • 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 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:
    • 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:
    • 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 String getCurrentBase()
      Retrieve the name of the currently open database or cluster.
      Returns:
      Name of current database or cluster.
    • getCurrentThesaurusName

      public 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 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:
    • 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:
    • 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:
    • 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(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(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 Iterator<TdbSearchSet> iterator()
      Returns an iterator over the search sets in the current search object.
      Specified by:
      iterator in interface 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