# ibi Patterns - Search Java Interface

# ibi™ Patterns - Search Java Interface Overview

The ibi Patterns - Search Java interface is designed to interact with the ibi Patterns - Search Server. A ibi Patterns - Search Server may be a stand alone server or a gateway to a cluster of servers or it may be an embedded server running within the Java JVM. The same Java interface and the same methods are used to communicate with all three of these.

This overview covers what is included with the Java interface and a brief description of the interface at a high level.

Package Contents

The Java interface package consists of the following:

- TIB_tps_java_interface.jar A jar file containing the complete server interface (but not the sample files).
- sample This directory contains both the source and an executable jar for some examples of how to use the interface. Currently the example concentrates on showing how to use transactions and the join feature. These examples are more extensive then the short examples at the end of this overview.

The documentation for the Java interface and the example code is included in the product documentation. It is provided in standard javadoc HTML format.

Compatibility

The interface is compiled to be compatible with Java release 1.8 or higher. Your Java run time environment and compiler must support release 1.8 or higher in order to use this interface.

Each release of the ibi Patterns - Search Server includes a new release of the Java API. The Java API release and the ibi Patterns - Search Server release should always be the same, the compatibility of a Java API with a newer or older ibi Patterns - Search Server release is not guaranteed.

Related Documentation

This documentation is intended as a reference guide to the Java interface. It is not intended to be a tutorial on using the ibi Patterns - Search Server or a complete reference on the features provided by the server. It is strongly recommended that you review the following documentation before using the Java Interface.

- ibi Patterns - Search Concepts Guide. This document provides an overview of the ibi Patterns - Search Server, its features and how to use them. The Java API reference documents assume the reader is familiar with the basic concepts presented in this guide.

Interface Overview

The Java interface is organized into the following types of objects:

- Connection Manager Objects hold all of the information needed to connect to a particular ibi Patterns - Search Server. Their purpose is to create Interface Objects used to communicate with the ibi Patterns - Search Server.
- Server Control Objects are used to start and stop a server, and set various configuration parameters. Currently only the Java embedded server can be controlled through the Java API.
- Interface Objects perform all interaction with the ibi Patterns - Search Server, they are the only objects that do so. All operations of the ibi Patterns - Search Server are exposed as method calls on these objects.
- Exception Objects are extensions of the Java Exception class and are used to report errors. All errors are reported via thrown exceptions.
- Input Argument Objects represent arguments to methods of the Interface Objects. These objects don't communicate with the ibi Patterns - Search Server, they are holders of structured data, providing a convenient and controlled means of constructing or accessing that data.
- Returned Data Objects represent results obtained from calls of Interface Object methods. These objects don't communicate with the ibi Patterns - Search Server, they are holders of structured data, providing a convenient and controlled means of accessing that data.
- Record Handlers represent a record in a ibi Patterns - Search Server table, or a source that generates such records. Records are passed into and returned by the methods of Interface Objects, so in some sense they are both Input Argument Objects and Returned Data Objects.
- File Handlers are used to read and parse files. Some of the other API classes use these classes to read files.

All of the public classes in the Java API are listed below, grouped by the types described above. Other classes not listed here are used internally and are not part of the actual API.

Connection Manager Objects

There is only one class of this type: NetricsConMgr.

Server Control Objects

The NetricsEmbedded class is used to control the ibi Patterns - Search Server embedded within the Java JVM. (Note: An embedded server is not available on all platforms, see the release Readme document for a list of supported platforms.) It is used to start and stop the server and set its start up parameters.

Interface Objects

- NetricsServerInterface
- NetricsTransaction

NetricsServerInterface and NetricsTransaction are identical with one important distinction: all operations performed through a NetricsTransaction object are grouped together within a single transaction on the ibi Patterns - Search Server. When all operations to be associated with the transaction are complete they can be committed or aborted as a whole by calling one of the commitWork, forceCommitWork or abortWork methods provided by the NetricsTransaction class, after which the transaction is closed and the NetricsTransaction object will no longer accept commands.

The NetricsServerInterface object on the other hand performs each operation in a separate transaction, each being automatically committed or aborted (they are performed in implicit transactions as described in the ibi Patterns - Search Concepts Guide).

There is one other difference between these two classes: to maintain backward compatibility NetricsServerInterface objects can be created directly through a set of public constructors, NetricsTransaction objects can only be created through the NetricsConMgr factory class.

These objects are for the most part stateless. Each method formats the data given and transmits it to the ibi Patterns - Search Server, reads the results and returns it to the caller. The data is not retained, nor is any state information retained in the interface objests. All data is maintained on the ibi Patterns - Search Server. Exceptions to this are: the necessary information needed to connect to the ibi Patterns - Search Server, logging and debugging settings, the layout selection and, in the case of the NetricsTransaction class, information needed to identify the transaction it is associated with and whether the transaction has been closed or is still open.

Record Handlers

- NetricsRecord
  This represents a single record.
- NetricsMappedRecord
  This is an extension of NetricsRecord that allows record fields to be accessed by the associated table field names.
- NetricsRecSrc
  This is an interface that defines a generic source of NetricsRecords. Objects and methods that accept a set of records expect objects that implement this interface. By creating an implementation of the NetricsRecSrc interface and passing these to the Java API the Java API can read records directly from any source. For example an implementation of the NetricsRecSrc interface that read records from an Oracle table would allow records to be streamed direct from Oracle into the ibi Patterns - Search Server.
- NetricsArrayRecSrc, NetricsCSVRecSrc
  These are implementations of NetricsRecSrc for a simple internal array of records and for reading a CSV file of records respectively.
- NetricsRecOp
  This combines an operation code and a NetricsRecord. It is used to stream a mixed set of operations to the ibi Patterns - Search Server.
- NetricsRecOpSrc
  This defines an interface for reading a stream of NetricsRecOp objects. Applications that wish to stream a mixed set of Add/Update/Delete operations to the ibi Patterns - Search Server can do so by creating an implementation of this interface. NetricsArrayRecOpSrc is an array backed implementation of this interface.

File Handlers

- NetricsFieldedReader
  This is an interface used by other classes in the Java API when they must read fielded data from a file.
- NetricsCSVReader
  This is an implementation of the NetricsFieldedReader interface for standard format CSV files.

Exception Objects

- NetricsException
  Most errors are reported using NetricsException. All errors returned by the ibi Patterns - Search Server are reported as thrown NetricsException objects. Most errors generated by the Java API itself are also reported by thrown NetricsExceptions.
- NetricsErrorItem
  This is a utility class used by the NetricsException class to expose data items returned by the ibi Patterns - Search Server in the error message.
- NetricsRecSrcException
  These are thrown by the record source classes. It is an extension of the NetricsException class.
- NetricsFileFormatException
  These are thrown by the file handler classes. It is an extension of the NetricsRecSrcException class providing additional file specific information such as line numbers.

Input Argument Objects

- NetricsEmbeddedSettings
  This holds the configuration settings for the ibi Patterns Server embedded in the Java JVM. It is passed to the NetricsEmbedded class to specify the configuration of the embedded server.
- NetricsThesaurus, NetricsCombinedThesaurus, NetricsWeightedDictionary.
  These represent the three types of thesaurus. They can hold the complete thesaurus definition or a reference to a file that contains the thesaurus data.
- NetricsCharmap
  This represents the definition of a custom character map.
- NetricsTable
  This represents the definition of a table. The definition can also hold the records of a table as a NetricsRecSrc object. This is mostly used as an input argument but is also returned as a Returned Data Object by the table dump methods.
- NetricsPsiEncoding, NetricsSortEncoding
  These are used to defined the encodings for the PSI and SORT prefilters. They are used when creating and initializing a NetricsTable object. (And so represent input parameters to an input parameter.)
- NetricsTableCursor
  This is both an input and an output parameter. It holds the current position information when scanning through all records in a table.
- NetricsSearchCfg, NetricsQuery
  These objects are used to define an inexact query. As inexact matching is the primary purpose of the ibi Patterns - Search Server these objects are key elements of the interface. A NetricsQuery object represents any of the basic query types. They are combined to create a complete query tree. NetricsSearchCfg is used to associate the query with a particular table. It also holds various table related options such as the filtering predicate to apply. Old style queries, now deprecated, are created using a NetricsSearchCfg object.
- NetricsJoin
  This class is used to define a join relationship. It is used with the NetricsSearchCfg class.
- NetricsSearchOpts
  This class defines the global search options to be associated with a query.
- NetricsPredicate
  This class is used to construct predicate expressions. It also provides various constants associated with predicate expressions. In most cases predicate expressions are now more easily constructed using predicate string expressions, but the methods provided by this class may be usefull in some cases.
- ANetricsQueryBuilder
  This abstract class is used to create or set the query input objects listed above. Most commonly used in record matching scenarios, it defines and partly implements an interface used to convert a record into a query that will return matching records. By creating different implementations of this abstract class the same base code can be used to match almost any record data.
- NetricsRecFile
  This class defines a file containing record information. It holds the file name and information on the format of the file.
- NetricsVarAttr
  This class is used to construct and parse the special variable attributes field values. A variable attributes field encodes an arbitrary set of name value pairs into a single record field.

All input argument objects should be created and initialized once, the same object should not be updated repeatedly. Think of them as constant data items.

Returned Data Objects

- NetricsCharmapStats, NetricsTableStats, NetricsIdxStats, NetricsModelStats, NetricsThesStats
  These classes hold settings and statistics on the various data items held in the ibi Patterns - Search Server. NetricsIdxStats holds information on the partitioned indexes within a table, so represents just a portion of a data item.
- NetricsCmdStats
  This holds the usage statistics for a single command. This is used for performance evaluation and monitoring.
- NetricsLock
  This is both a returned value and an input value. It is used in the old style table locking, which is now deprecated. This should no longer be used, explicit transactions should be used instead.
- NetricsSearchResponse, NetricsSearchResult
  These contain the results of a search request. NetricsSearchResponse is the complete search response. It includes overall statistics plus an array of the records found, returned as an array of NetricsSearchResult items. A NetricsSearchResult item is an extension of NetricsMappedRecord that includes all of the scoring results from the search for that record.
- NetricsServerStats
  This contains the configuration information for the ibi Patterns - Search Server.
- NetricsTranStats
  This contains status information on one currently open transaction.
- NetricsVersionInfo
  This contains information on the server version and current server configuration. It is returned by the server version command.

The classes: NetricsArrayDbRecSrc, NetricsDb, NetricsDbRecSrc NetricsDbSearchCfg and NetricsDbStats are old names for: NetricsArrayRecSrc, NetricsTable, NetricsRecSrc NetricsSearchCfg and NetricsTableStats respectively. They are all deprecated and shouldn't be used.

Examples

Here is a simple example of how to use the search method of the NetricsServerInterface class.

    import com.netrics.likeit.*;
    import java.io.*;
    import java.util.*;
    import java.lang.*;

    //
    // Perform a simple query against a table.
    // We assume the table is loaded already.
    //
    class example1 {

      public static void main(String args[]) throws Exception
      {
        // Get a connection to the server.
        // -------------------------------
        // Here we use the legacy connection method, creating a
        // NetricsServerInterface object directly.  We assume the
        // host and port are in first and second arguments.
        // Note: this call will NOT verify the connection.  We won't know
        //       if the server is there until we issue a command.
        NetricsServerInterface si = null ;
        si = new NetricsServerInterface(args[0], new Integer(args[1]).intValue()) ;

        // Define our input items
        String table_name = "city_names" ;
        String [] field_names =  new String [] { "full name", "common name" } ;
        String query_str = "thecityoflakesalt" ;

        // Create a query request
        // ----------------------
        // First we define a simple query.
        NetricsQuery qry = NetricsQuery.Simple(query_str, field_names, null) ;
        // Now we associate it with a table
        NetricsSearchCfg cfg = new NetricsSearchCfg(table_name) ;
        cfg.setNetricsQuery(qry) ;

        // Perform the search, getting the results
        NetricsSearchResponse response = null ;
        try {
            response = si.search(cfg, null) ;
        } catch (NetricsException ne) {
            // Handle exception here
            System.out.println("Search Call Failed: "+ne.toString()) ;
            return ;
        } catch (IOException ioe) {
            // Handle IO exception here
            System.out.println("Couldn't connect to server: "+ioe.toString()) ;
            return ;
        }

        // Print the record match score, key and full name for each record
        // ---------------------------------------------------------------
        // Get the list of records returned by the search.
        NetricsSearchResult [] results = response.getSearchResults() ;
        for ( int i = 0 ; i < results.length ; i++ ) {
            // Print out the desired info for each record.
            System.out.println("Score: "+results[i].getMatchScore()+
                               " Key: "+results[i].getKey()+
                               " Full Name: "+results[i].getField("full name") ) ;
        }

        return ;
      }

    }

The second example shows how to use a transaction to create and checkpoint a table.

    import com.netrics.likeit.*;
    import java.io.*;
    import java.util.*;
    import java.lang.*;

    // Example 2: Create and load a table and checkpoint it in a
    //            single transaction.
    class example2 {

      public static void main(String args[]) throws Exception
      {
        // Start a Transaction.
        // --------------------
        // Here we assume that either the default connection parameters
        // are used or they are defined in the environment (see NetricsConMgr).
        NetricsConMgr    conmgr = new NetricsConMgr() ;
        // Now create our transaction Interface Object.
        // Note: this call will verify the connection, throwing an
        //       exception if the server can't be contacted.
        NetricsTransaction tx = null ;
        try {
            tx = conmgr.beginWork() ;
        } catch (NetricsException ne) {
            // Handle error here.
            System.out.println("Exception creating transaction: "+ne.toString() ) ;
            return ;
        } catch (IOException ioe) {
            // Handle I/O errors, probably couldn't connect to server.
            System.out.println("Couldn't connect to server: "+ioe.toString() ) ;
            return ;
        }
        System.out.println("Created Transaction: "+tx.getTranId() ) ;

        String table_name = "city_names" ;
        String file_name = "city_names.csv" ;

        // -------------------------------------------------
        // We do all transaction operations in a try finally
        // block to make sure the transaction gets closed.
        // -------------------------------------------------
        try {

            // Create a table.
            // --------------
            // We load the table from a CSV file using the Java API.
            // (CSV files can also be read directly by the server.)
            // The CSV file includes the field names as the first line
            // in the file.  Our CSV file doesn't contain record keys,
            // so we have the Java API generate them.  This is the
            // default record file configuration so we can use the
            // basic constructor.
            NetricsRecFile rec_file = new NetricsRecFile(file_name) ;

            // Create a Record Source to read records from the CSV file.
            NetricsCSVRecSrc rec_reader = null ;
            try {
                rec_reader = new NetricsCSVRecSrc(rec_file) ;
            } catch (FileNotFoundException nfe) {
                // Handle file not found or couln't be opened errors.
                System.out.println("The file: "+file_name+" couldn't be opened: "
                                   +nfe.toString() ) ;
                return ;
            } catch (NetricsFileFormatException nffe) {
                // Handle CSV format errors.
                System.out.println("The file "+file_name
                                   +" has formatting errors: "
                                   +nffe.toString() ) ;
                return ;
            }

            // Create a table definition.  This includes the record source.
            // We get the field names from the record source.
            NetricsTable table_def = new NetricsTable(table_name,
                                                      rec_reader.getFieldNames(),
                                                      rec_reader) ;

            // Now we can create and load the table.
            NetricsTableStats table_stats = null ;
            try {
                table_stats = tx.tblload(table_def) ;
            } catch (NetricsException ne) {
                // handle errors from server.
                System.out.println("Table load failed: "+ne.toString() ) ;
                return ;
            } catch (IOException ioe) {
                // handle communications errors.
                System.out.println("Communications error: "+ioe.toString() );
                return ;
            }

            // Now checkpoint the table.
            try {
                tx.checkpoint( new String [] { table_name } ) ;
            } catch (NetricsException ne) {
                System.out.println("Checkpoint failed: "+ne.toString() ) ;
                return ;
            }

            // And commit the transaction.
            try {
                tx.commitWork() ;
                // transaction closed, null it out so we don't do so again.
                System.out.println("Committed Transaction: "+tx.getTranId() ) ;
                tx = null ;
            } catch (NetricsException ne) {
                System.out.println("Commit failed: "+ne.toString() ) ;
            }
        } finally {
            // -------------------------------------------------------------
            // If we still have a transaction we errored out, abort it.
            // It is important to ensure that transactions are not left open.
            // Using a try-finally block can help ensure that transactions
            // are not left open.
            // -------------------------------------------------------------
            if (tx != null) {
                try {
                    tx.abortWork() ;
                    System.out.println("Aborted Transaction: "+tx.getTranId() ) ;
                    tx = null ;
                } catch (NetricsException ne) {
                    System.out.println("Clean up abort failed: "+ne.toString() ) ;
                } catch (IOException ioe) {
                    System.out.println("Clean up abort IO failed: "
                                       +ioe.toString() ) ;
                }
            }
        }

        return ;
      }

    }

Packages
Package | Description
--- | ---
com.netrics.likeit |