com.ibm.commerce.base.helpers

Class OptCounterInfo

  • java.lang.Object
    • com.ibm.commerce.base.helpers.OptCounterInfo
  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable


    public final class OptCounterInfo
    extends java.lang.Object
    implements java.lang.Cloneable, java.io.Serializable

    This class contains information about the value of the OPTCOUNTER column for a row in a database table.

    The OptCounterInfo class defines four properties:

    Known
    Is set to "true" if the CurrentValue matches the value in the database, and so it can be included in a WHERE clause. A value that has been incremented or randomized does not need to be included in the WHERE clause. It is assumed that an increment or randomize operation is only performed when a database write lock has been obtained.
    Null
    Is set to "true" if the CurrentValue to be included in the WHERE clause is null.
    CurrentValue
    Represents the value to be included in the WHERE clause if the Null property is "false".
    EJBLoaded
    Is set to "true" if the value gets loaded using ejbLoad().

    The new CurrentValue represents the value to be set when inserting or updating a row.

    Use this class in the following cases:

    Note: Some operations are not supported. For example, JDBC cannot be used to update a row after it has been loaded into an EJB bean and before the bean has been stored. It is better to avoid mixing EJB beans and JDBC for the same database information. If necessary, use the BaseJDBCHelper.getSavedOptCounterInfoForUpdate(Object) method to cause dirty EJB objects to be flushed to the database before executing a JDBC update operation.

    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static java.lang.String OPTCOUNTER_COLUMN_NAME
      The name of the OPTCOUNTER column.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method and Description
      java.lang.Object clone()
      Returns a copy of this OptCounterInfo object.
      static OptCounterInfo getAndForgetForNextInsert()
      Gets and increments the object most recently set by the setForNextInsert method, or creates and randomizes a new one created from the default constructor.
      short getCurrentValue()
      Get the current OPTCOUNTER value.
      static java.lang.String getDecrementOptCounterFragment()
      Returns an SQL fragment that can be used to decrement the current OPTCOUNTER value.
      static java.lang.String getDecrementSQL(java.lang.String astrUpdateFragment, java.lang.String astrWhereClauseFragment)
      Returns a simple UPDATE statement with appropriate phrase to decrement the OPTCOUNTER column.
      static java.lang.String getIncrementOptCounterFragment()
      Returns an SQL fragment that can be used to increment the current OPTCOUNTER value.
      static java.lang.String getIncrementSQL(java.lang.String astrUpdateFragment, java.lang.String astrWhereClauseFragment)
      Returns a simple UPDATE statement with appropriate phrase to increment the OPTCOUNTER column.
      static short getNextValue(short aCurrentOptCounterValue)
      Gets the next value of the OPTCOUNTER column (incremented with wrap to 1).
      java.lang.String getOptimisticDecrementSQL(java.lang.String astrTableName, java.lang.String astrWhereClause)
      Returns an SQL statement that can be used to decrement the OPTCOUNTER column of a specific row.
      java.lang.String getOptimisticIncrementSQL(java.lang.String astrTableName, java.lang.String astrWhereClause)
      Returns an SQL statement that can be used to increment the OPTCOUNTER column of a specific row.
      java.lang.String getOptimisticSelectForUpdateSQL(java.lang.String astrSelectFragment)
      Returns a simple SELECT statement with the appropriate phrases to include a previously read opt counter (if any) in the WHERE clause, and to obtain a FOR UPDATE lock.
      java.lang.String getOptimisticSelectForUpdateSQL(java.lang.String astrSelectFragment, java.lang.String astrWhereClauseFragment)
      Returns a simple SELECT statement with the appropriate phrases to obtain the opt counter value from the database, to include a previously read opt counter (if any) in the WHERE clause, and to obtain a FOR UPDATE lock.
      java.lang.String getOptimisticSelectSQL(java.lang.String astrSelectFragment, java.lang.String astrWhereClauseFragment)
      Returns a simple SELECT statement with the appropriate phrases to obtain the opt counter and include it in the WHERE clause.
      static OptCounterInfo getSavedOptCounterInfo(java.lang.Object aKey)
      Gets the OPTCOUNTER information for a row of a table from the TransactionCache.
      static OptCounterInfo getSavedOptCounterInfoForInsert(java.lang.Object aKey)
      Gets OPTCOUNTER information to be used in an INSERT operation.
      static java.lang.String getSelectForUpdateFragment()
      Returns an SQL fragment that can be used to obtain a FOR UPDATE lock.
      static java.lang.String getSelectForUpdateSQL(java.lang.String astrSelectFragment)
      Returns a simple SELECT statement with an appropriate phrase to obtain a FOR UPDATE lock.
      static java.lang.String getSelectOptCounterSQL(java.lang.String astrTableName, java.lang.String astrWhereClause)
      This method gets an SQL statement that can be used to obtain the current values of the OPTCOUNTER column.
      static java.lang.String getSelectOptCounterSQL(java.lang.String astrTableName, java.lang.String astrColumnName, java.lang.String astrWhereClause)
      This method gets an SQL statement that can be used to obtain the current values of a specified column and of the OPTCOUNTER column.
      java.lang.String getUpdateSQL(java.lang.String astrUpdateFragment, java.lang.String astrWhereClauseFragment)
      Returns a simple UPDATE SQL statement with appropriate optimistic locking phrases.
      java.lang.String getUpdateSQL(java.lang.String astrUpdateFragment, java.lang.String astrWhereClausePrefixFragment, java.lang.String astrWhereClausePostfixFragment)
      Returns a simple UPDATE SQL statement with appropriate optimistic locking phrases.
      java.lang.String getWhereClauseFragment()
      Returns either "" (if the value is not known or has been incremented or randomized), or " AND OPTCOUNTER IS NULL" (if the value is null), or " AND OPTCOUNTER=?" (if the value is not null).
      OptCounterInfo increment()
      Increment the current value (with wrap to 1).
      boolean isEJBLoaded()
      Gets whether the current OPTCOUNTER value is loaded using ejbLoad().
      boolean isKnown()
      Gets whether the current OPTCOUNTER value is known.
      boolean isNull()
      Gets whether the current OPTCOUNTER value is null.
      OptCounterInfo randomize()
      Sets the current value to a randomly assigned value.
      OptCounterInfo setCurrentValue(boolean abRowExists, java.sql.ResultSet aResultSet)
      Sets the current OPTCOUNTER information from a ResultSet.
      OptCounterInfo setCurrentValue(boolean abRowExists, java.sql.ResultSet aResultSet, int aIndex)
      Sets the current OPTCOUNTER information from a ResultSet.
      OptCounterInfo setCurrentValue(java.lang.Number anCurrentOptCounterValue)
      Sets the current known OPTCOUNTER value, which may be null.
      OptCounterInfo setCurrentValue(short aCurrentOptCounterValue)
      Sets the current known, not null, OPTCOUNTER value.
      OptCounterInfo setCurrentValue(java.lang.Short anCurrentOptCounterValue)
      Sets the current known OPTCOUNTER value, which may be null.
      OptCounterInfo setEJBLoaded()
      Sets the property that indicates that the current OPTCOUNTER value was loaded using ejbLoad().
      OptCounterInfo setEJBLoaded(boolean abEJBLoaded)
      Sets whether the current OPTCOUNTER value was loaded using ejbLoad().
      static OptCounterInfo setForNextInsert(OptCounterInfo aOptCounterInfo)
      Sets an OptCounterInfo object that will be recalled by the next execution of the getAndForgetForNextInsert method.
      OptCounterInfo setKnown(boolean abKnown)
      Sets whether the current OPTCOUNTER value is known.
      OptCounterInfo setNull(boolean abNull)
      Sets whether the current known OPTCOUNTER value is null.
      OptCounterInfo setParameter(java.sql.PreparedStatement aPreparedStatement, int aIndex)
      Sets the OPTCOUNTER value into the specified PreparedStatement at the specified position, if it is known and not null, has not been incremented, and has not been randomized.
      java.lang.String toString()
      Returns a String representation of this object suitable for printing in trace information.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • OPTCOUNTER_COLUMN_NAME

        public static final java.lang.String OPTCOUNTER_COLUMN_NAME
        The name of the OPTCOUNTER column.
        See Also:
        Constant Field Values
    • Method Detail

      • getSelectOptCounterSQL

        public static java.lang.String getSelectOptCounterSQL(java.lang.String astrTableName,
                                                              java.lang.String astrWhereClause)
        This method gets an SQL statement that can be used to obtain the current values of the OPTCOUNTER column. It retrieves them from the specified table for the rows indicated by the specified WHERE clause. The WHERE clause should not start with "WHERE".
        Parameters:
        astrTableName - The table name
        astrWhereClause - The WHERE clause
        Returns:
        the SQL statement.
      • getSelectOptCounterSQL

        public static java.lang.String getSelectOptCounterSQL(java.lang.String astrTableName,
                                                              java.lang.String astrColumnName,
                                                              java.lang.String astrWhereClause)
        This method gets an SQL statement that can be used to obtain the current values of a specified column and of the OPTCOUNTER column. It retrieves them from the specified table for the rows indicated by the specified WHERE clause. The WHERE clause should not start with "WHERE". The SQL statement returned is: "SELECT " + OPTCOUNTER_COLUMN_NAME + "," + astrColumnName + ","+ OPTCOUNTER_COLUMN_NAME + " FROM " + astrTableName + " WHERE " + astrWhereClause
        Parameters:
        astrTableName - The table name.
        astrColumnName - The column name.
        astrWhereClause - The where clause.
        Returns:
        The SQL statement.
      • getSelectForUpdateFragment

        public static java.lang.String getSelectForUpdateFragment()
        Returns an SQL fragment that can be used to obtain a FOR UPDATE lock. It can be used in an SQL SELECT statement such as: "SELECT acolumn FROM tablename WHERE conditions" + OptCounterInfo.getForUpdateFragment()

        Do not call this method during static initialization.

        Returns:
        the SQL fragment.
      • getSelectForUpdateSQL

        public static java.lang.String getSelectForUpdateSQL(java.lang.String astrSelectFragment)

        Returns a simple SELECT statement with an appropriate phrase to obtain a FOR UPDATE lock.

        The string returned is:

        Do not call this method during static initialization.

        Parameters:
        astrSelectFragment - the update SQL fragment.
        Returns:
        the SQL statement.
      • getIncrementOptCounterFragment

        public static java.lang.String getIncrementOptCounterFragment()
        Returns an SQL fragment that can be used to increment the current OPTCOUNTER value. It can be used in an SQL UPDATE statement such as:
        • "UPDATE tablename SET " + OptCounterInfo.getIncrementOptCounterFragment() + " WHERE column2Name=column2Value"

        Do not call this method during static initialization.

        Returns:
        the SQL fragment.
      • getIncrementSQL

        public static java.lang.String getIncrementSQL(java.lang.String astrUpdateFragment,
                                                       java.lang.String astrWhereClauseFragment)

        Returns a simple UPDATE statement with appropriate phrase to increment the OPTCOUNTER column.

        The string returned is:

        Do not call this method during static initialization.

        Parameters:
        astrUpdateFragment - the update SQL fragment.
        astrWhereClauseFragment - the WHERE clause fragment.
        Returns:
        the SQL statement.
      • getDecrementOptCounterFragment

        public static java.lang.String getDecrementOptCounterFragment()
        Returns an SQL fragment that can be used to decrement the current OPTCOUNTER value. It can be used in an SQL "UPDATE" statement such as:
        • "UPDATE tablename SET " + OptCounterInfo.getDecrementOptCounterFragment() +" WHERE column2Name=column2Value"

        Do not call this method during static initialization.

        Returns:
        the SQL fragment.
      • getDecrementSQL

        public static java.lang.String getDecrementSQL(java.lang.String astrUpdateFragment,
                                                       java.lang.String astrWhereClauseFragment)

        Returns a simple UPDATE statement with appropriate phrase to decrement the OPTCOUNTER column.

        The string returned is:

        Do not call this method during static initialization.

        Parameters:
        astrUpdateFragment - the update SQL fragment.
        astrWhereClauseFragment - the WHERE clause fragment.
        Returns:
        the SQL statement.
      • getNextValue

        public static short getNextValue(short aCurrentOptCounterValue)
        Gets the next value of the OPTCOUNTER column (incremented with wrap to 1).
        Parameters:
        aCurrentOptCounterValue - the current value to be incremented.
        Returns:
        the new incremented value of the OPTCOUNTER column.
      • getSavedOptCounterInfo

        public static OptCounterInfo getSavedOptCounterInfo(java.lang.Object aKey)
        Gets the OPTCOUNTER information for a row of a table from the TransactionCache.
        Parameters:
        aKey - uniquely identifies the table and row of the OPTCOUNTER. For objects with EJB beans, use its primary key object. For example, for a UserBean, use new MemberKey(member_id) For JDBC helper classes when there is no corresponding EJB bean, use a unique row identifier. For example, new SerializableTuple("STOREREL", storeId, relatedStoreId, relationshipTypeName)
        Returns:
        the OPTCOUNTER information for the specified row, or a new OptCounterInfo constructed from the default constructor if there was none in the Transaction cache.
      • getSavedOptCounterInfoForInsert

        public static OptCounterInfo getSavedOptCounterInfoForInsert(java.lang.Object aKey)
        Gets OPTCOUNTER information to be used in an INSERT operation. The object returned can be the current saved OptCounterInfo object with its value incremented, if it is known. Or, it can be a new OptCounterInfo object created with the default constructor, that is randomly assigned a value. In either case, the value returned is saved and marked as known. Do not call this method if there is a possibility that the INSERT operation will not be performed.
        Parameters:
        aKey - uniquely identifies the table and row of the OPTCOUNTER. For objects with EJB beans, use its primary key object. For example, for a UserBean, use new MemberKey(member_id) For JDBC helper classes when there is no corresponding EJB, use a unique row identifier. For example, new SerializableTuple("STOREREL", storeId, relatedStoreId, relationshipTypeName)
        Returns:
        the OPTCOUNTER information for the specified row, to be used in a subsequent insert operation.
      • setForNextInsert

        public static OptCounterInfo setForNextInsert(OptCounterInfo aOptCounterInfo)
        Sets an OptCounterInfo object that will be recalled by the next execution of the getAndForgetForNextInsert method.
        Parameters:
        aOptCounterInfo - the object to be set. Can be null.
        Returns:
        the input parameter.
      • getAndForgetForNextInsert

        public static OptCounterInfo getAndForgetForNextInsert()
        Gets and increments the object most recently set by the setForNextInsert method, or creates and randomizes a new one created from the default constructor. Then forgets it until the setForNextInsert method is called again.
        Returns:
        the OPTCOUNTER information.
      • setCurrentValue

        public OptCounterInfo setCurrentValue(short aCurrentOptCounterValue)
        Sets the current known, not null, OPTCOUNTER value. Side effects: Null is set false, Known is set true.
        Parameters:
        aCurrentOptCounterValue - the value to be set.
        Returns:
        this.
      • setCurrentValue

        public OptCounterInfo setCurrentValue(java.lang.Short anCurrentOptCounterValue)
        Sets the current known OPTCOUNTER value, which may be null. Side effects: Known is set true.
        Parameters:
        anCurrentOptCounterValue - the value to be set.
        Returns:
        this.
      • setCurrentValue

        public OptCounterInfo setCurrentValue(java.lang.Number anCurrentOptCounterValue)
        Sets the current known OPTCOUNTER value, which may be null. Side effects: Known is set true.
        Parameters:
        anCurrentOptCounterValue - the value to be set.
        Returns:
        this.
      • setCurrentValue

        public OptCounterInfo setCurrentValue(boolean abRowExists,
                                              java.sql.ResultSet aResultSet)
                                       throws java.sql.SQLException
        Sets the current OPTCOUNTER information from a ResultSet. Known is set to abRowExists.
        Parameters:
        abRowExists - true if aResultSet has been set to the correct row.
        aResultSet - not used if abRowExists is false.
        Returns:
        this.
        Throws:
        java.sql.SQLException
      • setCurrentValue

        public OptCounterInfo setCurrentValue(boolean abRowExists,
                                              java.sql.ResultSet aResultSet,
                                              int aIndex)
                                       throws java.sql.SQLException
        Sets the current OPTCOUNTER information from a ResultSet. Known is set to abRowExists.
        Parameters:
        abRowExists - true if aResultSet has been set to the correct row.
        aResultSet - not used if abRowExists is false.
        aIndex - the index of the OPTCOUNTER column in the result set. Not used if abRowExists is false.
        Returns:
        this.
        Throws:
        java.sql.SQLException
      • setNull

        public OptCounterInfo setNull(boolean abNull)
        Sets whether the current known OPTCOUNTER value is null. Side effect: Known is set true.
        Parameters:
        abNull - true if the value is null.
        Returns:
        this.
      • setKnown

        public OptCounterInfo setKnown(boolean abKnown)
        Sets whether the current OPTCOUNTER value is known.
        Parameters:
        abKnown - true if the value is known.
        Returns:
        this.
      • setEJBLoaded

        public OptCounterInfo setEJBLoaded(boolean abEJBLoaded)
        Sets whether the current OPTCOUNTER value was loaded using ejbLoad().
        Parameters:
        abEJBLoaded - true if the value was loaded using ejbLoad().
        Returns:
        this.
      • setEJBLoaded

        public OptCounterInfo setEJBLoaded()
        Sets the property that indicates that the current OPTCOUNTER value was loaded using ejbLoad().
        Returns:
        this.
      • getCurrentValue

        public short getCurrentValue()
        Get the current OPTCOUNTER value.
        Returns:
        the current OPTCOUNTER value.
      • increment

        public OptCounterInfo increment()

        Increment the current value (with wrap to 1).

        Side effect: Null is set false.

        Side effect: The WHERE clause fragment for an incremented OPTCOUNTER is always empty, since incrementing the value implies that the row has been updated. This means that a write lock has been obtained, hence no other transaction can modify the row until this transaction commits, and so the WHERE clause fragment that detects changes is not required.

        Returns:
        this.
      • randomize

        public OptCounterInfo randomize()

        Sets the current value to a randomly assigned value.

        Side effect: Null is set false.

        Side effect: The WHERE clause fragment for a randomized OPTCOUNTER is always empty, since randomizing the value implies that the row has been created. This means that a write lock has been obtained, hence no other transaction can modify the row until this transaction commits, and so the WHERE clause fragment that detects changes is not required.

        Returns:
        this.
      • isNull

        public boolean isNull()
        Gets whether the current OPTCOUNTER value is null.
        Returns:
        true if the current OPTCOUNTER value is null.
      • isKnown

        public boolean isKnown()
        Gets whether the current OPTCOUNTER value is known.
        Returns:
        true if the current OPTCOUNTER value is known.
      • isEJBLoaded

        public boolean isEJBLoaded()
        Gets whether the current OPTCOUNTER value is loaded using ejbLoad().
        Returns:
        true if the current OPTCOUNTER value is loaded using ejbLoad().
      • clone

        public java.lang.Object clone()
                               throws java.lang.CloneNotSupportedException
        Returns a copy of this OptCounterInfo object.
        Overrides:
        clone in class java.lang.Object
        Returns:
        a copy of this OptCounterInfo object.
        Throws:
        java.lang.CloneNotSupportedException
      • toString

        public java.lang.String toString()
        Returns a String representation of this object suitable for printing in trace information.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a String representation of this object suitable for printing in trace information.
      • getWhereClauseFragment

        public java.lang.String getWhereClauseFragment()
        Returns either "" (if the value is not known or has been incremented or randomized), or " AND OPTCOUNTER IS NULL" (if the value is null), or " AND OPTCOUNTER=?" (if the value is not null).
        Returns:
        the WHERE clause fragment.
      • getUpdateSQL

        public java.lang.String getUpdateSQL(java.lang.String astrUpdateFragment,
                                             java.lang.String astrWhereClauseFragment)

        Returns a simple UPDATE SQL statement with appropriate optimistic locking phrases.

        The string returned is:

        Do not call this method during static initialization.

        Parameters:
        astrUpdateFragment - the UPDATE SQL fragment.
        astrWhereClauseFragment - the WHERE clause fragment.
        Returns:
        the SQL statement.
      • getUpdateSQL

        public java.lang.String getUpdateSQL(java.lang.String astrUpdateFragment,
                                             java.lang.String astrWhereClausePrefixFragment,
                                             java.lang.String astrWhereClausePostfixFragment)

        Returns a simple UPDATE SQL statement with appropriate optimistic locking phrases.

        The string returned is:

        Do not call this method during static initialization.

        Parameters:
        astrUpdateFragment - the UPDATE SQL fragment.
        astrWhereClausePrefixFragment - the WHERE clause prefix fragment.
        astrWhereClausePostfixFragment - the WHERE clause postfix fragment.
        Returns:
        the SQL statement.
      • getOptimisticSelectSQL

        public java.lang.String getOptimisticSelectSQL(java.lang.String astrSelectFragment,
                                                       java.lang.String astrWhereClauseFragment)

        Returns a simple SELECT statement with the appropriate phrases to obtain the opt counter and include it in the WHERE clause.

        The string returned is:

        Do not call this method during static initialization.

        Parameters:
        astrSelectFragment - the select SQL fragment.
        astrWhereClauseFragment - the WHERE clause fragment.
        Returns:
        the SQL statement.
      • getOptimisticIncrementSQL

        public java.lang.String getOptimisticIncrementSQL(java.lang.String astrTableName,
                                                          java.lang.String astrWhereClause)

        Returns an SQL statement that can be used to increment the OPTCOUNTER column of a specific row.

        Parameters:
        astrTableName - the table name.
        astrWhereClause - a WHERE clause (should NOT start with "WHERE") that uniquely identifies the row.
        Returns:
        the SQL statement.
      • getOptimisticDecrementSQL

        public java.lang.String getOptimisticDecrementSQL(java.lang.String astrTableName,
                                                          java.lang.String astrWhereClause)

        Returns an SQL statement that can be used to decrement the OPTCOUNTER column of a specific row.

        Parameters:
        astrTableName - the table name.
        astrWhereClause - a WHERE clause (should NOT start with "WHERE") that uniquely identifies the row.
        Returns:
        the SQL statement.
      • getOptimisticSelectForUpdateSQL

        public java.lang.String getOptimisticSelectForUpdateSQL(java.lang.String astrSelectFragment,
                                                                java.lang.String astrWhereClauseFragment)

        Returns a simple SELECT statement with the appropriate phrases to obtain the opt counter value from the database, to include a previously read opt counter (if any) in the WHERE clause, and to obtain a FOR UPDATE lock.

        The string returned is:

        Do not call this method during static initialization.

        Parameters:
        astrSelectFragment - the select SQL fragment.
        astrWhereClauseFragment - the WHERE clause fragment.
        Returns:
        the SQL statement.
      • getOptimisticSelectForUpdateSQL

        public java.lang.String getOptimisticSelectForUpdateSQL(java.lang.String astrSelectFragment)

        Returns a simple SELECT statement with the appropriate phrases to include a previously read opt counter (if any) in the WHERE clause, and to obtain a FOR UPDATE lock.

        The string returned is:

        Do not call this method during static initialization.

        Parameters:
        astrSelectFragment - the select SQL fragment.
        Returns:
        the SQL statement.
      • setParameter

        public OptCounterInfo setParameter(java.sql.PreparedStatement aPreparedStatement,
                                           int aIndex)
                                    throws java.sql.SQLException
        Sets the OPTCOUNTER value into the specified PreparedStatement at the specified position, if it is known and not null, has not been incremented, and has not been randomized.
        Parameters:
        aPreparedStatement - the PreparedStatement.
        aIndex - the position of the parameter to be set in the PreparedStatement.
        Returns:
        this.
        Throws:
        java.sql.SQLException