// Commented out mbk Feb 2019 // //
Search this site:
Enterprise Search Blog
« NIE Newsletter

Searching with the Ultraseek XPA Java API

Last Updated Mar 2009

By: Mark Bennett & Miles Kehoe, - Volume 2 - Number 4 - January 2005

In our first newsletter back in 2003, we provided a sample Windows Shell Script program to allow command line searching of Verity K2 collections.

Ultraseek, Verity's other search product line, is thought to be more of a web-based tool with a powerful and friendly browser-based console and search; but using the XPA Java library, you can access Ultraseek collections from within command line programs. This month we will show you how.

Why a Command Line Anyway?

With such a great browser-based application, you might wonder why anyone would want to use command line tools on Ultraseek. I can think of many good reasons:

  • create reports and status for export to other people
  • integrate information into other applications (Excel, Powerpoint, etc.)
  • gain access to some fine control points not available in the console
  • some people just prefer the command line "black screen of death"

First Steps

The first thing you need to use command line Ultraseek is the XPA Search API. If you don't already have it, contact your Verity sales representative to see if you can obtain a copy. And you'll need a Java compiler on your system, available from http://java.sun.com. We've tested the code here on Java 1.3.x and 1.4.x.

Now you're ready to get going. Copy the sample program listed in Figure 1 and save it as Search1.java. Note that Java is case sensitive, so be sure to save the file using the exact name specified in the "public class" statement just after the imports.

You'll also need to know the Ultraseek server name and port. You can discover these by firing up the Ultraseek Administrative Console shortcut in your browser and observing the system name and port you use to access the console. In Figure 1, the host name is titan and the port is the standard Ultraseek port 8765. Your host may be a fully qualified name, something like max.ideaeng.com.

/* A very simple Ultraseek XPA example, based loosely on
Verity's SearchOneCollection example
import java.io.*;
import java.util.*;
import com.ultraseek.xpa.search.*;
import com.ultraseek.xpa.server.*;

public class Search1 {

// Null constructor
Search1() { }

// The entire demo runs in main()
public static void main(String[] args) throws Exception {
// We will be asking the user to type in queries
InputStreamReader inputStreamReader = new InputStreamReader(System.in);
BufferedReader bufferedReader = new BufferedReader(inputStreamReader);

// Change this to the name of your Ultraseek server
String host = "titan";
// The default port for Ultraseek is 8765, so you can usually
// leave this as is
int port = 8765;
System.out.println( "Using " + host + ':' + port );

UltraseekServer searchServer = new UltraseekServer(host,port);
System.out.println("Remote Version: " + searchServer.getVersionString() );


System.out.println("Enter searches; enter empty search to exit");
// Loop until done
for (;;) {
System.out.print("search: ");
String line = bufferedReader.readLine();

// Exit if we got a null or blank line
if (line==null) break;
if( line.trim().length() == 0 )

// Parse and Compile the query
Query query = Query.parse(line);

// Run the search
SearchResultList searchResultList = searchServer.search(query);


// If we have some results
if( !searchResultList.isEmpty() ) {
Iterator iterator = searchResultList.iterator();
// Need try/catch to detect end of results list
try {
// For each matching document
while (iterator.hasNext()) {
SearchResult searchResult = (SearchResult)iterator.next();
// Print the score
System.out.print( "" + searchResult.getScore() + " " );
// Print the title
System.out.println( searchResult.getTitle() );
// - OR -
// Print the URL
// System.out.println( searchResult.getURL() );
} catch (NoSuchElementException e) {
// No more results from server, this is not an error
} else { // Else No results
System.out.println( "No matches found" );


Figure 1

The Code and Supporting Files

Once you have saved the Java code, you will need to compile it before you can run it. If you are an experienced Java developer, you can probably just set up the environment yourself and compile it; but if you're new to Java, you might find the Windows BAT file in Figure 2 helpful. It assumes that the Java compiler is in your PATH, and that the directory where you have your XPA jar file is defined as MYCP. You may also want to use the Windows BAT file in Figure 3 to set up the environment to run your Search1 program.

@echo off
set TARGET=Search1.java
set MYCP=C:\Apps\Ultraseek53\lib\xpasearch.jar
set JAVAC=javac

"%JAVAC%" -classpath .;"%MYCP%" %TARGET%


@echo off
set TARGET=Search1
set MYCP=C:\Apps\Ultraseek53\lib\xpasearch.jar
set JAVA=java

"%JAVA%" -cp .;"%MYCP%" %TARGET%


Compiling and Running the Program

Once you have the Java file and the two batch files saved, compile the program by typing:


You should see no messages if the program compiles correctly. If you get any errors or messages, re-check your steps; check with someone in your organization who knows Java; or contact us at New Idea Engineering for help.

Once your code does compile, you're ready to run Figure 4 shows a session in our development labs:

Using titan:8765
Remote Version: 5.3.1

Enter searches; enter empty search to exit

search: xpa

0.42 Verity Ultraseek XPA ProgrammerÆs Guide 2.1
0.35999998 Verity Ultraseek Customization Guide
0.35999998 Verity Ultraseek Administrator Guide
0.29 Verity Ultraseek Installation Guide
0.29 Verity Ultraseek Implementation Guide


Figure 4: Sample Session

The program prompts you for a query, here shown in bold. Ultraseek searches all active Ultraseek collections for the term. The results display on your screen. Enter a null search term to exit the program.

That's it!

Reviewing The Steps

In preparing to use the sample program here, be sure to:

  • Copy Figure 1 into a file called Search1.java
    • Make sure the host name and port match your configuration
  • Copy Figure 2 into a file called COMPILE_SEARCH1.BAT
    • Make sure the MYCP variable points to where xpasearch.jar is stored
  • Copy Figure 3 into a file called RUN_SEARCH1.BAT
    • Make sure the MYCP variable points to where xpasearch.jar is stored
  • Verify that the Java compiler is in your path
    • From the command line type javac to confirm
  • Compile the program
    • From the command line type COMPILE_SEARCH1
    • Look for no errors or messages
  • Run the program
    • From the command line type RUN_SEARCH1
    • Enter search terms
    • Enter a blank search to exit

Keep an eye out for more Ultraseek and XPA articles here in Enterprise Search in the future.