See: Description
| Package | Description |
|---|---|
| com.netrics.likeit |
The TIBCO Patterns Java interface is designed to interact with the TIBCO Patterns Server. A TIBCO Patterns 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:
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.7 or higher. Your Java run time environment and compiler must support release 1.7 or higher in order to use this interface.
Each release of the TIBCO Patterns Server includes a new release of the Java API. The Java API release and the TIBCO Patterns Server release should always be the same, the compatibility of a Java API with a newer or older TIBCO Patterns 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 TIBCO Patterns 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.
Interface Overview
The Java interface is organized into the following types of objects:
Connection Manager Objects
There is only one class of this type: NetricsConMgr.
Server Control Objects
The NetricsEmbedded class is used to control the TIBCO Patterns 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 and NetricsTransaction are identical with one important distinction: all operations performed through a NetricsTransaction object are grouped together within a single transaction on the TIBCO Patterns 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 TIBCO Patterns Concept 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 TIBCO Patterns 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 TIBCO Patterns Server. Exceptions to this are: the necessary information needed to connect to the TIBCO Patterns 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
File Handlers
Exception Objects
Input Argument Objects
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
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 ;
}
}