Searching for documents in a docbase

Using queries to search for specific documents in a document base.

Your program must be logged in to a docbase, and your program must have an IxiaDocBaseServices object for that docbase:
IxiaDocBaseServices docbase =   ...

An application searches for documents in a docbase by using a query. The query contains search specifications coded in the TEXTML Query Language. These specifications can refer to the content (i.e., the indexed content) of the documents, to the properties of the document, to custom properties of the document, or to any combination.

Here is a simple but very useful query: AllSystemDocuments.xml returns all the system documents in a docbase:

<?xml version="1.0" encoding="UTF-16"?>
<!-- AllSystemDocuments.xml -->
<query VERSION="4.4" RESULTSPACE="AllSystemDocuments">
    <property NAME="DocType">
        <elem>TEXTML_SYSTEM_DOCUMENT</elem>
	</property>
</query>

As you can see, the TEXTML Query Language is coded in XML. Since there are two kinds of queries (Document queries and Indexed value queries) there are two DTDs for queries: SEARCH_DOCUMENTS.DTD and SEARCH_INDEX.DTD. The above query will retrieve these DTD files, as well as all other system documents, for a specified document base.

The programming logic to search for documents is essentially the same for any query.

To search for documents in a docbase:

  1. Get a SearchServices object for your docbase:
    // Get the SearchServices for <docbase>
    IxiaSearchServices search = docbase.SearchServices();
    
  2. Define a string that contains your query:
    // ReadQuery() extracts a <query> string from <queryfilename>.
    // ReadQuery() is defined in the sample program.
    // <queryfilename> is a string containing the path\name of the query file.
    String query = ReadQuery(queryfilename));
    
  3. Using the query, search the docbase and store the search results in a ResultSpace object:
    IxiaResultSpace result = search.SearchDocuments(query);
    
    // How many hits did the search produce?
    int count = result.Count();
    

    A ResultSpace is a container for the data returned by a search. You can return only the data that you need.

    Note:

    A ResultSpace does not contain the actual documents. It is a data structure that points to the documents in the docbase that match the query. It can even point only to specific data stored in those documents. Accordingly, returning a ResultSpace can be very "light", especially if your program uses that data to reduce the number of documents that whose content it actually retrieves.

    For example, you can create a list of the hits returned by the search (e.g., a list of the titles of documents that matched the query). Then, you present the list to the user, who selects one or more documents for further processing.

  4. Store the contents of the ResultSpace as a SubList:
     IxiaSubList subList = new IxiaSubList(result);
    A SubList is an implementation the standard java.util.List interface. SubLists provide many methods for manipulating the list of hits.
  5. // Mark a range of items in the SubList. In this case, we'll mark a range that includes all the hits:
    subList.markRange(0, count - 1); 
  6. Retrieve the documents as an array of Document objects:
    IxiaDocumentServices.Result [] documents =
        docServices.GetDocuments(subList, 
                                 Constants.TEXTML_DOCUMENT_ALL_FLAGS);

    The second parameter specifies what document-related data you want retrieved from the docbase and stored in the array of Result objects. You can specify:

    • The entire document.
    • Document content.
    • Indexed content.
    • Document properties.
    • Custom properties.
    • Search result information.
    • Related errors.
    • Version number.

    Constants.TEXTML_DOCUMENT_ALL_FLAGS means that we're asking for all of the above.

  7. Process each Result object in the documents array:
     // Process each entry in the sublist.
     // Either:
     // * Success: print the document name or...
     // * Failure: print the error message.
     for (int i = 0; i < documents.length; ++i)
     {
         if (documents[i].error != null)
             System.out.println(documents[i].error);
         else
             System.out.println(documents[i].document.GetName());
     }
    

Sample program and sample queries

AllSystemDocuments.xml and the other sample queries are located in your Program Files directory for TEXTML Server: [...]\IxiaSoft\TextmlServer[version]\SDK\Queries\*.xml.

Here is the sample program for running document queries: [...]\IxiaSoft\TextmlServer[version]\SDK\java\com\ixiasoft\samples\SearchDocuments.java.