Package 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:
  `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 Summary

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

- ## Method Summary

  Modifier and Type
  Method
  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(String cclStatement)`
  Execute a CCL statement.
  `void`
  `executeXPath(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.
  `String`
  `getCurrentBase()`
  Retrieve the name of the currently open database or cluster.
  `String`
  `getCurrentThesaurusDef()`
  Returns the definition string used for the currently defined thesaurus, or an empty string if no thesaurus is defined.
  `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.
  `Iterator<TdbSearchSet>`
  `iterator()`
  Returns an iterator over the search sets in the current search object.
  `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 Details

  - ### TdbSearch

    public TdbSearch(TdbSession session) throws TdbException
    Constructor, creates a blank instance.
    Parameters:
      `session` - Active session
    Throws:
      `TdbException`

- ## 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()`
      - `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:
      - `setHistoryDelta(boolean)`
      - `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 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:
      - `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:
      - `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(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`