Class 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 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
      • 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:
        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.
      • 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>