Package com.netrics.likeit

Class 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 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 Engine. 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.

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