com.netrics.likeit

Class NetricsConMgr

java.lang.Object

com.netrics.likeit.NetricsConMgr

public class NetricsConMgr
extends java.lang.Object

Create connections to the TIBCO Patterns Engine.

This is a factory class used to create a connection to the TIBCO Patterns Engine. Each object of this class is associated with a particular TIBCO Patterns Engine and contains all of the information necessary to connect to the engine. All of this information has default values, and an associated environment variable. Methods are provided to override these settings. If a value is set via a method call that value takes precedence, otherwise the value of the associated environment variable is used, if the environment variable does not exist in the environment the default value is used. The values are listed below.

Host Machine. An IP address or name resolvable to an IP address of the machine the TIBCO Patterns Engine is on.
Environment Variable: TIBCOPatternsServerHost
Default value: localhost

Host Port. The port number the TIBCO Patterns Engine is listening on. If the environment variable does not contain an integer string value it is ignored.
Environment Variable: TIBCOPatternsServerPort
Default value: 5051

Connection Pooling. The type of connection pooling to be used. The environment variable must have a value of: "common", "local" or "none". Other values are ignored.
Environment Variable: TIBCOPatternsConnectionPooling
Default value: common

Protocol Selection. Whether communications should use IPv4, IPv6, or defer the choice to network configuration. standard error. The environment variable must have a value of: "ipv4" or "ipv6" or "mixed". Other values are ignored.
Environment Variable: TIBCOPatternsConnectionProtocols
Default value: mixed, except on Windows Server 2003 (and Windows XP), where the default is ipv4.

Debug Logging. Whether all communications should be logged to standard error. These logs will be very large and verbose, they are only used for debugging. The environment variable must have a value of: "on" or "off". Other values are ignored.
Environment Variable: TIBCOPatternsConnectionDebug
Default value: off

None of the following methods should be called on an object that is being shared across multiple threads:

• setHost
• setPort
• setDebugOn
• setDebugOff
• setConnectionPoolingOff
• setConnectionPoolingCommon
• setConnectionPoolingLocal

The recommended procedure is to create and initialize a NetricsConMgr object in the main thread, it may then be passed to other threads, which may use it to create NetricsServerInterface or NetricsTransaction objects, but once shared between threads the NetricsConMgr object should never be updated by calling any of the methods listed above.

Field Summary

Fields

Modifier and Type	Field and Description
static int	PROTOCOL_DEFAULT Use the default protocols
static int	PROTOCOL_IPV4_ONLY Use only the IPv4 protocol.
static int	PROTOCOL_IPV6_ONLY Use only the IPv6 protocol.
static int	PROTOCOL_MIXED Defer choice between IPv4 and IPv6 to network configuration.

Constructor Summary

Constructors

Constructor and Description
NetricsConMgr() Create a connection manager.

Method Summary

Modifier and Type	Method and Description
NetricsTransaction	beginWork() Create a new transaction connection.
NetricsTransaction	continueWork(int tran_id) Continue work on an existing explicit transaction.
java.lang.String	getHost() Return the current TIBCO Patterns host machine.
int	getPort() This returns the current TIBCO Patterns listen port.
boolean	isConnectionPoolingCommon() Return true if the current connection pooling setting is common mode.
boolean	isConnectionPoolingLocal() Return true if the current connection pooling setting is local mode.
boolean	isDebugOn() Return true if the debug setting is turned on.
NetricsServerInterface	newConnection() Create a new connection.
void	setConnectionPoolingCommon() Set connection pooling to common mode.
void	setConnectionPoolingLocal() Set connection pooling to local mode.
void	setConnectionPoolingOff() Turn off connection pooling.
void	setDebugOff() Set debug logging off.
void	setDebugOn() Set debug logging on.
void	setEmbeddedMode(boolean enabled) Enable or disable embedded mode.
void	setHost(java.lang.String host) Set the TIBCO Patterns host machine.
void	setNetProtocols(int protocols) Set the network protocols that will be used to connect to the TIBCO Patterns Engine.
void	setPort(int port) Set the TIBCO Patterns listen port.

Methods inherited from class java.lang.Object

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

Field Detail

PROTOCOL_DEFAULT

public static final int PROTOCOL_DEFAULT

Use the default protocols

See Also:

Constant Field Values

PROTOCOL_IPV4_ONLY

public static final int PROTOCOL_IPV4_ONLY

Use only the IPv4 protocol.

See Also:

Constant Field Values

PROTOCOL_IPV6_ONLY

public static final int PROTOCOL_IPV6_ONLY

Use only the IPv6 protocol.

See Also:

Constant Field Values

PROTOCOL_MIXED

public static final int PROTOCOL_MIXED

Defer choice between IPv4 and IPv6 to network configuration. Not supported on Windows Server2003 (and Windows XP).

See Also:

Constant Field Values

Constructor Detail

NetricsConMgr

public NetricsConMgr()

Create a connection manager. The settings are taken from the environment variables or default values as described above.

Method Detail

getHost

public java.lang.String getHost()

Return the current TIBCO Patterns host machine.

Returns:

the current TIBCO Patterns host machine.

setHost

public void setHost(java.lang.String host)

Set the TIBCO Patterns host machine. This changes the host machine for this connection manager. This doesn't affect NetricsServerInterface or NetricsTransactions objects already created via this object.

Parameters:

host - the new host machine for this connection manager.

getPort

public int getPort()

This returns the current TIBCO Patterns listen port.

Returns:

the current TIBCO Patterns listen port.

setPort

public void setPort(int port)

Set the TIBCO Patterns listen port. This set the port to use when connecting to the TIBCO Patterns Engine. This doesn't affect NetricsServerInterface or NetricsTransactions objects already created via this object.

Parameters:

port - the port number to use when connecting.

setDebugOn

public void setDebugOn()

Set debug logging on.

This causes any new NetricsServerInterface or NetricsTransaction objects created to have their connection debug logging turned on. This doesn't affect NetricsServerInterface or NetricsTransactions objects already created.

Debug logging is generated to the standard error and is very verbose. It should only be used for debugging specific problems.

setDebugOff

public void setDebugOff()

Set debug logging off. This causes any new NetricsServerInterface or NetricsTransaction object created to have their connection debug logging turned off. This doesn't affect NetricsServerInterface or NetricsTransactions objects already created.

isDebugOn

public boolean isDebugOn()

Return true if the debug setting is turned on.

Returns:

true if the debug setting is turned on, false otehrwise.

setConnectionPoolingOff

public void setConnectionPoolingOff()

Turn off connection pooling.

This causes any new NetricsServerInterface or NetricsTransaction objects created to not use connection pooling. This doesn't affect NetricsServerInterface or NetricsTransactions objects already created.

With connection pooling off every command will establish a new connection to the server. The connection will be dropped when the command completes.

setConnectionPoolingCommon

public void setConnectionPoolingCommon()

Set connection pooling to common mode.

This causes any new NetricsServerInterface or NetricsTransaction objects created to use common connection pooling. This doesn't affect NetricsServerInterface or NetricsTransactions objects already created.

When common connection pooling is used the interface object will use a pool of connections that is shared with other interface objects using common connection pooling. This mode minimizes the number of new connections that are made to the server.

setConnectionPoolingLocal

public void setConnectionPoolingLocal()

Set connection pooling to local mode.

This causes any new NetricsServerInterface or NetricsTransaction objects created to use local connection pooling. This doesn't affect NetricsServerInterface or NetricsTransactions objects already created.

When local connection pooling is used the interface object keeps its own pool of connections. It will not share connections with other objects.

isConnectionPoolingCommon

public boolean isConnectionPoolingCommon()

Return true if the current connection pooling setting is common mode.

Returns:

true if the current connection pooling setting is common mode.

isConnectionPoolingLocal

public boolean isConnectionPoolingLocal()

Return true if the current connection pooling setting is local mode.

Returns:

true if the current connection pooling setting is local mode.

setEmbeddedMode

public void setEmbeddedMode(boolean enabled)

Enable or disable embedded mode. If embedded mode is enabled, all NetricsServerInterface and NetricsTransactions objects created communicate with the embedded TIBCO Patterns server instead of an external server. The embedded server must be initialized before an interface object for the embedded server can be created. setHost(java.lang.String), setPort(int), setNetProtocols(int) , setConnectionPoolingCommon(), setConnectionPoolingLocal(), and setConnectionPoolingOff(), may not be called while in embedded mode. Embedded mode is off by default.

Parameters:

enabled - true to enable embedded mode, false to disable it.

See Also:

NetricsEmbedded

setNetProtocols

public void setNetProtocols(int protocols)

Set the network protocols that will be used to connect to the TIBCO Patterns Engine.

Parameters:

protocols - Which protocols to use. One of PROTOCOL_DEFAULT, PROTOCOL_IPV4_ONLY, PROTOCOL_IPV6_ONLY, or PROTOCOL_MIXED.

newConnection

public NetricsServerInterface newConnection()
                                     throws NetricsException,
                                            java.io.IOException

Create a new connection.

This creates a new connection to the TIBCO Patterns Engine. All operations made through the returned interface object that modify data on the TIBCO Pattern Engine are associated with separate implicit transactions that are automatically committed or aborted when each operation returns.

An exception is thrown if a connection can't be established.

The interface object uses the connection settings of the connection manager object at the time it is created. Once created the interface object is separate from the connection manager object that created it. Changing settings in the connection manager object will not affect the settings in the interface object and vice versa.

Returns:

a new connection to the TIBCO Patterns Engine.

Throws:

java.io.IOException - if there was a communications error.

NetricsException - if there was an error setting up the connection.

See Also:

NetricsServerInterface

beginWork

public NetricsTransaction beginWork()
                             throws NetricsException,
                                    java.io.IOException

Create a new transaction connection.

This creates a new connection to the TIBCO Patterns Engine and associates it with a new explicit transaction. All operations made through the returned interface object that modify data on the TIBCO Pattern Engine are associated with the transaction. This is the only means of creating explicit transactions through the Java API.

An exception is thrown if a connection can't be established or a new transaction can't be created.

The interface object uses the connection settings of the connection manager object at the time it is created. Once created the interface object is separate from the connection manager object that created it. Changing settings in the connection manager object will not affect the settings in the interface object and vice versa.

Returns:

a new transaction

Throws:

java.io.IOException - if there was a communications error

NetricsException - if the transaction could not be created.

See Also:

NetricsTransaction

continueWork

public NetricsTransaction continueWork(int tran_id)
                                throws NetricsException

Continue work on an existing explicit transaction.

This creates a new connection to the TIBCO Patterns Engine and associates it with an existing explicit transaction. All operations made through the returned interface object that modify data on the TIBCO Pattern Engine are associated with the transaction.

The interface object uses the connection settings of the connection manager object at the time it is created. Once created the interface object is separate from the connection manager object that created it. Changing settings in the connection manager object will not affect the settings in the interface object and vice versa.

Parameters:

tran_id - id of the transaction to continue.

Returns:

the continued transaction

Throws:

NetricsException - if the transaction could not be continued.

See Also:

NetricsTransaction