Package com.netrics.likeit

## Class NetricsConMgr

- java.lang.Object
- - com.netrics.likeit.NetricsConMgr

-     public class NetricsConMgr
      extends java.lang.Object

  Create connections to the ibi™ Patterns - Search.

  This is a factory class used to create a connection to ibi™ Patterns - Search. Each object of this class is associated with a particular ibi™ Patterns - Search Server 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 ibi™ Patterns - Search Server is on.
  Environment Variable: TIBCOPatternsServerHost
  Default value: localhost

  Host Port. The port number the ibi™ Patterns - Search Server 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
  - setSSLEnabled
  - setSSLSocketFactory
  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 | 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 | Description
    --- | ---
    `NetricsConMgr()` | Create a connection manager.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `NetricsTransaction` | `beginWork()` | Create a new transaction connection.
    `NetricsTransaction` | `continueWork​(long tran_id)` | Continue work on an existing explicit transaction.
    `java.lang.String` | `getHost()` | Return the current ibi™ Patterns - Search host machine.
    `int` | `getPort()` | This returns the current ibi™ Patterns - Search listen port.
    `javax.net.ssl.SSLSocketFactory` | `getSSLSocketFactory()` | Returns the current SSL socket factory.
    `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.
    `boolean` | `isSSLEnabled()` | Returns the SSL enable flag.
    `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 ibi™ Patterns - Search host machine.
    `void` | `setNetProtocols​(int protocols)` | Set the network protocols that will be used to connect to the ibi Patterns Server.
    `void` | `setPort​(int port)` | Set the ibi™ Patterns - Search listen port.
    `void` | `setSSLEnabled​(boolean enable)` | Sets the SSL enable flag.
    `void` | `setSSLSocketFactory​(javax.net.ssl.SSLSocketFactory factory)` | Sets the current SSL socket factory.

    - ### 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 ibi™ Patterns - Search host machine.
      Returns:
        the current ibi™ Patterns - Search host machine.

    - #### setHost

          public void setHost​(java.lang.String host)

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

      It is invalid to call this when embedded mode is enabled.

      Parameters:
        `host` - the new host machine for this connection manager.

    - #### getPort

          public int getPort()

      This returns the current ibi™ Patterns - Search listen port.
      Returns:
        the current ibi™ Patterns - Search listen port.

    - #### setPort

          public void setPort​(int port)

      Set the ibi™ Patterns - Search listen port. This set the port to use when connecting to the ibi™ Patterns - Search Server. This doesn't affect NetricsServerInterface or NetricsTransactions objects already created via this object.

      It is invalid to call this when embedded mode is enabled.

      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 otherwise.

    - #### 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.

      It is invalid to call this when embedded mode is enabled.

    - #### 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.

      It is invalid to call this when embedded mode is enabled.

    - #### 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.

      It is invalid to call this when embedded mode is enabled.

    - #### 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 ibi™ Patterns - Search 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 ibi Patterns Server.

      It is invalid to call this when embedded mode is enabled.

      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 ibi™ Patterns - Search Server. All operations made through the returned interface object that modify data on the ibi Patterns Server 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 ibi™ Patterns - Search Server.
      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 ibi™ Patterns - Search Server and associates it with a new explicit transaction. All operations made through the returned interface object that modify data on the ibi Patterns Server 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​(long tran_id)
                                          throws NetricsException

      Continue work on an existing explicit transaction.

      This creates a new connection to the ibi™ Patterns - Search Server and associates it with an existing explicit transaction. All operations made through the returned interface object that modify data on the ibi Patterns Server 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`

    - #### isSSLEnabled

          public boolean isSSLEnabled()

      Returns the SSL enable flag.
      SSL is disabled by default.
      Returns:
        the SSL enable flag

    - #### setSSLEnabled

          public void setSSLEnabled​(boolean enable)

      Sets the SSL enable flag.
      SSL is disabled by default.

      It is invalid to call this when embedded mode is enabled.

      Parameters:
        `enable` - true to enable SSL, false to disable.
      Throws:
        `java.lang.IllegalStateException` - if embedded mode is enabled.

    - #### getSSLSocketFactory

          public javax.net.ssl.SSLSocketFactory getSSLSocketFactory()

      Returns the current SSL socket factory.
      The factory is ignored if SSL is disabled.
      Returns:
        the current SSL socket factory, or null if the default factory will be used.

    - #### setSSLSocketFactory

          public void setSSLSocketFactory​(javax.net.ssl.SSLSocketFactory factory)

      Sets the current SSL socket factory.
      There are two ways to control the SSL socket factory:
      1. Create one in application code and set it using `setSSLSocketFactory(SSLSocketFactory)`
      2. Modify the default factory by changing the `javax.net.ssl.trustStore` property
      The factory is ignored if SSL is disabled.

      It is invalid to call this when embedded mode is enabled.

      For details on SSL socket factories, refer to the Java Security Developer's Guide in Oracle documentation

      Parameters:
        `factory` - A socket factory, or null to use the default factory.
      Throws:
        `java.lang.IllegalStateException` - if embedded mode is enabled.