com.netrics.likeit

Class NetricsEmbedded

java.lang.Object

com.netrics.likeit.NetricsEmbedded

public class NetricsEmbedded
extends java.lang.Object

Control the Patterns embedded server.

A copy of the TIBCO Patterns server can be run within the Java VM, avoiding the need for a separate external process. This is called the "embedded" server. (This is not available on all platforms, see the release notes for the list of platforms on which the embedded server is available.) The exact same Java API is used to communicate with the embedded server as with an external server. However, just like an external server, the embedded server must be started before it is used and should be shutdown after all use is completed. There is only ONE embedded server within a single JVM. This class provides static methods for starting and stopping the embedded server.

The standard procedure for using the embedded server is as follows:

 NetricsEmbeddedSettings embedded_settings = new NetricsEmbeddedSettings() ;
 // set your options here.  E.g.
 embedded_settings.consoleLogFilename = "embedded_server.log" ;
 // to avoid crashing the JVM it is recommended a memory limit be set.
 embedded_settings.maxTableMemory = 100000 ; // ~100M
 // other settings as desired...

 // set the directory where the embedded server library resides.
 // (The embedded server library is found in the same bin directory
 //  as the TIBCO Patterns server executable.)
 File embedded_lib = new File("/home/tibco/Patterns/versionserver/bin") ;

 // start the embedded server.
 try {
     NetricsEmbedded.initialize(embedded_settings, embedded_lib) ;
 } catch (NetricsException ne) {
     // Handle exception
 }

 // Create a connection to the embedded server.
 NetricsConMgr con_mgr = new NetricsConMgr() ;
 con_mgr.setEmbeddedMode(true) ;
 NetricsServerInterface nsi = con_mgr.newConnection() ;

 // Now use the interface as you would any interface to a server...

 

A few things to note about the embedded server:

• The embedded server does NOT accept incoming connections. It is not a full fledged TCP/IP server, it is only accessible from within the JVM.
• The embedded server can NOT be run as a gateway server.
• Remote descriptors should NOT be used with the embedded server. Although this is not explicitly blocked it may lead to unstable behavior and should not be used.
• The embedded server does not support GPU harnessing.
• Data loaded into the embedded server consumes memory within the JVM. As this memory is not allocated through the JVM it does not count towards the memory limits enforced by the JVM. However it does count towards the memory limits imposed by the OS and could lead to crashing the entire JVM. It is recommended that the the maxTableMemory option be used. Set it such that the JVM limit plus this limit is less than the OS process limit. (Remember the maxTableMemory option is in K-bytes, not bytes.)
• To free memory allocated by the embedded server the shutdown method should be used.
• Some server commands use multiple threads to speed operations (e.g. the "fast load" commands). This could lead to a single JVM thread using considerably more than one core of CPU resources when it issues such a command to the embedded server.
• Access to the embedded server is single-threaded. Only one command at a time will execute. Any command issued on another Java thread will block until the embedded server is available.

Constructor Summary

Constructors

Constructor and Description
NetricsEmbedded()

Method Summary

Modifier and Type	Method and Description
static boolean	initialize(NetricsEmbeddedSettings settings, java.io.File libDir) Initialize and start the TIBCO Patterns Embedded server.
static int	shutdown() Shut down the TIBCO Patterns Embedded Server.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NetricsEmbedded

public NetricsEmbedded()

Method Detail

initialize

public static boolean initialize(NetricsEmbeddedSettings settings,
                                 java.io.File libDir)
                          throws NetricsException

Initialize and start the TIBCO Patterns Embedded server.

This call is used to initialize and start the embedded TIBCO Patterns server. This must be called before attempting to use the embedded server. If the embedded server is not initialized by this command all attempts to communicate with the embedded server will throw a NetricsException.

If the embedded server is already initialized and running this command does nothing except increment the initialization count. This implies the initialization settings can't be changed dynamically after the server is started. To change the settings the server must be shutdown (destroying all tables and saved data), and restarted.

An equal number of shutdown methods as initialize methods must be called to shut down the server. This behavior is similar to that of recursive locks.

Parameters:

settings - the initialization settings for the Embedded server. These are analogous to the command line options of the standard server. If null is passed in the default options are used. The default options are the same as for the standard server except the use of parallel loads is turned off.

libDir - this is the full path name for the directory where the embedded server library resides. Note this is the directory and not the library file. The library name is "TIB_tps_embedded". The library file name is determined by the run time platform. On Linux it would be "libTIB_tps_embedded.so", on Windows it would be "TIB_tps_embedded.dll". The library is searched for in this directory. If this is null the standard system library path is searched.

Returns:

true if the library was already initialized, false if this was the first initialization.

Throws:

NetricsException - if the library cannot be loaded, or if the Embedded server initialization failed.

shutdown

public static int shutdown()
                    throws NetricsException

Shut down the TIBCO Patterns Embedded Server.

This shuts down the TIBCO Patterns embedded server. Shutting down the embedded server destroys all loaded data such as: tables, thesauri, Learn models and character maps. All memory used by the server is freed. (Note: this may not shrink the JVM process size as memory is only returned to the heap, the heap manager may or may not return it to the OS.)

An equal number of shutdown calls as initialize calls must be made before the embedded server is actually shut down.

Returns:

1 if the embedded server was actually shut down, 0 if this only decremented the internal initialization counter, and -1 if the library is not initialized.

Throws:

NetricsException - if shutdown encountered an internal error.