Package com.netrics.likeit

Class NetricsTransaction

  • public final class NetricsTransaction
extends NetricsServerInterface
    This is an interface object associated with an explicit transaction.

    NetricsTransaction is an extension of the NetricsServerInterface class. It provides all of the functionality of the NetricsServerInterface class, the difference being a NetricsTransaction object is coupled to a particular explicit transaction on the ibi™ Patterns - Search Engine. NetricsTransaction is the only means provided in the Java API for creating explicit transactions and associating operations with an explicit transaction.

    For an explanation of transactions in ibi™ Patterns - Search please read the "ibi™ Patterns - Search Concepts Guide". This explains the difference between explicit and implicit transactions along with other items that should be understood before using transactions.

    When a NetricsTransaction object is created a new explicit transaction is created on the ibi™ Patterns - Search Engine. All operations performed through the NetricsTransaction object are associated with this explicit transaction. Once all work to be associated with the transaction is complete the NetricsTransaction object provides methods for terminating the transaction by either committing it, or aborting it, which rolls back all changes made under the transaction. Once a transaction has been closed through one of these calls all attempts to perform further update operations through the NetricsTransaction object will throw an exception.

    Operations that do not update data on the ibi™ Patterns - Search Engine, such as queries, status reports and fetching of records, are not associated with transactions. Such operations can be performed using a NetricsTransaction object, but if no updates are to be performed a NetricsServerInterface object should be used, not a NetricsTransaction object.

    Transactions should never be left open. Once a NetricsTransaction object is created it MUST be closed by calling one of commitWork, forceCommitWork or abortWork, even if no operations were performed. The ibi™ Patterns - Search Engine can be configured to automatically close transactions that are left open and idle longer than a designated period of time. Applications that open transactions by creating a NetricsTransaction object, and then let that object sit idle for long periods of time, may find that operations fail when the NetricsTransaction object is finally used because the transaction was automatically closed. Read only operations are not associated with a transaction, so even if such operations are performed through a NetricsTransaction object, the associated transaction is still left idle and may get automatically closed.

    Objects of this class are NOT thread safe and should never be shared across threads.

    Objects of this class are created using a NetricsConMgr object. There are no public constructors for this class.

    For an example of how to use this class see the overview. More extensive examples are included in the java samples directory.

    See Also:
    NetricsServerInterface, NetricsConMgr

    • Method Detail

      • getTranId

        @Deprecated
public int getTranId()
        Deprecated.
        Use getTransactionId() to obtain the full transaction id.
        Returns the partial 32-bit transaction id of the associated transaction.
        Returns:
        the partial 32-bit transaction id of the associated transaction.

      • getTransactionId

        public long getTransactionId()
        Returns the transaction id of the associated transaction.
        Returns:
        the transaction id of the associated transaction.

      • commitWork

        public void commitWork()
                throws NetricsException,
                       java.io.IOException
        Commit the associated transaction.

        This performs a non-forced commit. If there were errors under this transaction the commit will fail with a DVK_ERR_HASERRORS error code.

        After this call completes successfully any attempt to perform further update operations through this object will throw an exception.

        Throws:
        NetricsException - If the server indicates that an error has occurred
        java.io.IOException - If an I/O error occurs

      • forceCommitWork

        public void forceCommitWork()
                     throws NetricsException,
                            java.io.IOException
        Forcibly commit the associated transaction.

        This performs a forced commit. Even if there were errors under this transaction the commit will occur. This should be used with extreme care. Committing errors can result in invalid and unusable data.

        After this call completes successfully any attempt to perform further update operations through this object will throw an exception.

        Throws:
        NetricsException - If the server indicates that an error has occurred
        java.io.IOException - If an I/O error occurs

      • abortWork

        public void abortWork()
               throws NetricsException,
                      java.io.IOException
        Abort the associated transaction.

        All changes made under this transaction are rolled back.

        After this call completes successfully any attempt to perform further update operations through this object will throw an exception.

        Throws:
        NetricsException - If the server indicates that an error has occurred
        java.io.IOException - If an I/O error occurs