TIBCO Patterns Interface Documentation

COMPANY CONFIDENTIAL

The TIBCO Patterns .Net interface is designed to interact with the TIBCO Patterns Engine. Most of this documentation explains how to program with the .Net API. This overview will cover what is included in this interface package, how to install it, and a brief overview of the included interface.

Package Contents

The .Net interface is delivered as a ZIP archive. In this archive you should find the following:

NetricsServerInterface/bin/Release/NetricsServerInterface.dll - This contains the complete implementation of the interface.

sample - This directory is a pre-built Visual Studio Project directory containing the source and executables for a simple command line utility for managing a TIBCO Patterns Engine. It also contains a user's guide for the utility in WORD and PDF format.

NetricsServerInterface/docs - A directory tree containing the API documentation. The documentation is provided in 3 forms: as a Window Help (.chm) file named: TMEreleaseDotNetAPIDocumentation.chm, where release is the current release number, as a self installer for Visual Studio 2008 help named: TMEreleaseDotNetAPIDocumentation.msi and a set of HTML files formated in MSDN style. The base file is at: index.html.

Installation

The complete API is contained in the single NetricsServerInterface.dll. When building with the API you only need to provide a reference to the DLL file in your Visual Studio project. Visual Studio can then create an installer that installs both your application with the NetricsServerInterface DLL.

If installing manually the API DLL file should be placed in the same directory as the executable that will be using it.

See the sample program documentation: "NSCguide.pdf" or "NSCguide.docx" in the sample directory for instructions on running the sample program.

The interface is compiled to be compatible with .Net 2.0 or higher.

Interface Overview

Before describing the interface a brief description of what the matching engine does may be helpful in understanding it.

The TIBCO Patterns Engine is an in-memory table manager that uses patented advanced matching technology to search data with a tolerance for errors. Data is stored in tables as records which have field structure. A field can be a number of types, including integer, float, date, date/time, text and searchable text. Error tolerant matching can only be performed on searchable text fields (exact matching can be performed on any field type). All fields will be returned from the matching engine whenever a record is accessed. Records also must include a record key which is a unique, user-specified id for the record. Records are grouped into tables much the same way as within a DBMS system with all records within a table having the same field structure.

It's important to point out that there are four basic versions of the matching engine. Not all features described here are applicable to every version. The three basic versions are:

TIBCO Patterns - Search This provides the TIBCO advanced matching capabilities with integrated indexing suitable for handling large data sets.

TIBCO Patterns - Learn This provides only the ability to apply the special machine learning decision algorithm. It does not support matching or the in-memory tables. Thus most of this API is not relevant to this version.

TIBCO Patterns - Search+Learn This combines both the advanced matching capabilities of the Search Engine and the machine learning decision algorithm into a single package.

The NetricsServerInterface object and its auxiliary objects:

The NetricsServerInterface object is the core object of the TIBCO Patterns Engine .Net interface. It is the only object one can use to communicate with a TIBCO Patterns Engine. All operations (e.g. creating a table, adding a record, and searching a table) happen through the NetricsServerInterface object. The auxiliary objects - NetricsRecord, NetricsSearchOpts, and the other objects - are only used as parameters passed to or returned from a NetricsServerInterface object.

Other than maintaining the connection information, the NetricsServerInterface object is entirely stateless. That is, no information is stored in the object, and the object requires no memory overhead other than that required for the object itself. All data is stored in the TIBCO Patterns Engine. The NetricsServerInterface object serves only to transport the information supplied to it in the auxiliary objects (NetricsRecord, NetricsTable, etc.) to the TIBCO Patterns Engine, where they are stored or processed.

Each call to the API is translated into the TIBCO Patterns Engine Protocol (the text-based raw socket communication) which is sent to the matching engine. The matching engine then completes the request and returns a response (also in the protocol) which is parsed by the interface. In this way all raw socket communication is hidden from the user of the NetricsServerInterface, and the matching engine can be run on any computer under any supported operating system. Note that all communications with the server is synchronous, that is the call always waits until a response is received from the server before returning.

The NetricsServerInterface object has methods for most familiar database operations. It can load tables and search them, add, get, delete, replace records, and much more. The complete documentation is available under the NetricsServerInterface class description.

Tips to get started:

1. The matching engine host and port are given in the constructor of the NetricsServerInterface object.

2. Make sure the IP address of the client is on the authentication list of the matching engine (see the TIBCO Patterns Engine User's Guide).

Other Classes

The other classes included in the interface are used by the NetricsServerInterface.

The NetricsRecord and NetricsTable objects are the interface's representation of the TIBCO Patterns Engine fielded record and table of records. NetricsRecSrc is an interface that is used for retrieving records from some source. NetricsArrayRecSrc and NetricsCSVRecSrc are two implementations of that interface. A NetricsRecFile object is used to define the format of a file containing records that is to be read by the TIBCO Patterns Engine. A NetricsLock represents a user set lock on a table. It is both returned by and sent to the server.

The NetricsException, NetricsFileFormatException, NetricsMappedRecord, NetricsSearchResponse, NetricsSearchResult, NetricsIdxStats, NetricsModelStats, NetricsTableStats, NetricsThesStats and NetricsVersionInfo objects are used to return information to the user.

The NetricsQuery, NetricsSearchOpts, NetricsPredicate and NetricsSearchCfg objects are used to configure searches of the data in the matching engine. As searching is the very reason the TIBCO Patterns Engine exists, the search is very flexible in its operation and can be easily configured by use of these objects.

The NetricsCombinedThesaurs, NetricsThesaurus and NetricsWeightedDictionary objects represent the three types of thesauri that can be used when searching and are used to create them. A NetricsCharmap object is used to define and create custom character maps associated with the fields of a table and thesauri. Other classes in the interface represent deprecated versions of the interface or internal objects that should not be used directly.

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

 Copy Code 
             String query = "thecityoflakesalt";
             String dbName = "city_names";
             String []fieldNames = new String [] { "full name", "common name" } ;
            
             LikeItServerInterface si = new LikeItServerInterface("localhost", 5051);
            
             // accept the default options
             NetricsSearchOpts opts = new NetricsSearchOpts();
             NetricsSearchCfg dbCfg = new NetricsSearchCfg(dbName);
             // add the query itself
             dbCfg.setNetricsQuery(NetricsQuery.Simple(query,fieldNames,null));
             NetricsSearchResponse response = si.dbsearch(dbCfg, opts);
            
             // get the matching record array
             NetricsSearchResult []results = response.getSearchResults();
             for( int i = 0 ; i < results.Length ; i++ ) {
                 Console.WriteLine(result[i].getMatchScore() + ". "
                + result[i].getKey());
             }

COM Inter-operability - This interface is also accessible nearly identically from COM. Instead of calling parameterized constructors, create the object, then call the appropriate Initialize function.

To register NetricsServerInterface.dll for COM interoperability on a development machine, change directory to the location of the dll, then run:

%SystemRoot%\Microsoft.NET\Framework\v2.0.50727\regasm NetricsServerInterface.dll /tlb /codebase

For production systems, NetricsServerInterface.dll will operate under any of the standard methods of registering .NET dll for COM access. The two most common methods are:

Register the dll for the entire machine: change directory to dll location, then run:

%SystemRoot%\Microsoft.NET\Framework\v2.0.50727\regasm NetricsServerInterface.dll /codebase

Register just for one application: Copy the DLL to the same directory as the client application, then, from that directory, run:

%SystemRoot%\Microsoft.NET\Framework\v2.0.50727\regasm NetricsServerInterface.dll


Classes

  Class Description
Public class NetricsArrayRecSrc Array based record source for loading data.
Public class NetricsBaseThesaurus This is the base class for all of the thesaurus types. It should never be used directly.
Public class NetricsCharmap This class contains the definition of a character map that can be used while searching.
Public class NetricsCmdStats This class contains summary statistics from the server on usage of a particular command.
Public class NetricsCombinedThesaurus This class is used to define a Netrics Combined Thesaurus.
Public class NetricsCSVReader Implement NetricsFieldedReader for CSV files.
Public class NetricsCSVRecSrc NetricsRecSrc implementation for CSV file records.
Public class NetricsException All errors returned by the Netrics server are thrown as a NetricsException.
Public class NetricsFileFormatException Exceptions thrown by File Readers.
Public class NetricsIdxStats This class contains statistics about a partitioned index in the Netrics server.
Public class NetricsLock Holds the key for a locked table.
Public class NetricsMappedRecord A NetricsMappedRecord inherits from a NetricsRecord, and has additional functionality which allows the user to access the fields of the record by field name or number.
Public class NetricsModelStats This class contains stats about a Decision Engine Model loaded into the Netrics server.
Public class NetricsPredicate Search predicates are used to select or score records based on exact matching tests.
Public class NetricsQuery NetricsQuery objects are used to implement the complex query structures introduced with release 4.1.
Public class NetricsRecFile Define name and format of a server side record source file.
Public class NetricsRecord This class is used to hold all the data which will be loaded into a Netrics Server.
Public class NetricsSearchCfg This class is used by the search method of the NetricsServerInterface class to configure those parameters which can be specified per table.
Public class NetricsSearchOpts This class is used to configure search options which apply for the overall search (for all tables being searched).
Public class NetricsSearchResponse This class represents the Netrics Server's response to a search command.
Public class NetricsSearchResult This class inherits from a NetricsMappedRecord and contains additional information relevant to a search result (match score, etc.).
Public class NetricsServerInterface This is the main class of the TIBCO Patterns Server Interface.
Public class NetricsServerStats This class contains status information on the server process.
Public class NetricsTable Used to load data into the Netrics server.
Public class NetricsTableStats This class contains stats about a table in the Netrics server.
Public class NetricsTextFileRecSrc Text file record source for loading data.
Public class NetricsThesaurus This class contains a list of synonyms that can be used while searching.
Public class NetricsThesStats This class contains information about a thesaurus on the Netrics server.
Public class NetricsVarAttr Manage a set of Variable Attribute values.
Public class NetricsWeightedDictionary Objects of this class represent a weighted dictionary, used to define terms with lesser or greater importance.

Interfaces

  Interface Description
Public interface INetricsArrayRecSrc Obsolete. Only for COM interoperability.
Public interface INetricsBaseThesaurus Obsolete. Only for COM interoperability. See NetricsBaseThesaurus.
Public interface INetricsCharmap Obsolete. Only for COM interoperability.
Public interface INetricsCmdStats Obsolete. Only for COM interoperability. See NetricsCmdStats
Public interface INetricsCombinedThesaurus Obsolete. Only for COM interoperability. See NetricsCombinedThesaurus.
Public interface INetricsCSVReader Obsolete. Only for COM interoperability.
Public interface INetricsCSVRecSrc Obsolete. Only for COM interoperability.
Public interface INetricsIdxStats Obsolete. Only for COM interoperability. See NetricsIdxStats.
Public interface INetricsLock Obsolete. Only for COM interoperability.
Public interface INetricsMappedRecord Obsolete. Only for COM interoperability.
Public interface INetricsModelStats Obsolete. Only for COM interoperability. See NetricsModelStats.
Public interface INetricsPredicate Obsolete. Only for COM interoperability.
Public interface INetricsQuery Obsolete. Only for COM interoperability.
Public interface INetricsRecFile Obsolete. Only for COM interoperability.
Public interface INetricsRecord Obsolete. Only for COM interoperability.
Public interface INetricsSearchCfg Obsolete. Only for COM interoperability.
Public interface INetricsSearchOpts Obsolete. Only for COM interoperability.
Public interface INetricsSearchResponse Obsolete. Only for COM interoperability.
Public interface INetricsSearchResult Obsolete. Only for COM interoperability.
Public interface INetricsServerInterface Obsolete. Only for COM interoperability.
Public interface INetricsServerStats Obsolete. Only for COM interoperability. See NetricsServerStats
Public interface INetricsTable Obsolete. Only for COM interoperability. See NetricsTable.
Public interface INetricsTableStats Obsolete. Only for COM interoperability. See NetricsTableStats.
Public interface INetricsTextFileRecSrc Obsolete. Only for COM interoperability. See NetricsTextFileRecSrc.
Public interface INetricsThesaurus Obsolete. Only for COM interoperability. See NetricsThesaurus.
Public interface INetricsThesStats Obsolete. Only for COM interoperability. See NetricsThesStats.
Public interface INetricsWeightedDictionary Obsolete. Only for COM interoperability. See NetricsWeightedDictionary.
Public interface NetricsFieldedReader This interface is used to provide sets of fields to other Netrics classes.
Public interface NetricsTableRecSrc Generic interface for loading records into a Netrics table.

Enumerations

  Enumeration Description
NestedPublic enumeration NetricsException.error_codes An enumeration of all error codes returned as part of the NetricsException object.
NestedPublic enumeration NetricsPredicate.pred_ops An enumeration of all the predicate operators.
NestedPublic enumeration NetricsSearchOpts.score_types An enumeration of all possible score types.
NestedPublic enumeration NetricsSearchOpts.tiebreak_types An enumeration of all possible tiebreak types.
NestedPublic enumeration NetricsServerInterface.ConnectionPoolingPolicy Possible connection pooling policies.
NestedPublic enumeration NetricsTable.field_typs An enumeration of all the field types.

Syntax based on .NET Framework version 2.0.
Documentation version 1.0.0.0.