Glassfish example source code file (StateManager.java)

This example Glassfish source code file (StateManager.java) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - Glassfish tags/keywords

load_required, object, object, persistenceconfig, read_ok, read_ok, read_write_ok, read_write_ok, scocollection, statemanager, string, string

The Glassfish StateManager.java source code

/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 1997-2010 Oracle and/or its affiliates. All rights reserved.
 *
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common Development
 * and Distribution License("CDDL") (collectively, the "License").  You
 * may not use this file except in compliance with the License.  You can
 * obtain a copy of the License at
 * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
 * or packager/legal/LICENSE.txt.  See the License for the specific
 * language governing permissions and limitations under the License.
 *
 * When distributing the software, include this License Header Notice in each
 * file and include the License file at packager/legal/LICENSE.txt.
 *
 * GPL Classpath Exception:
 * Oracle designates this particular file as subject to the "Classpath"
 * exception as provided by Oracle in the GPL Version 2 section of the License
 * file that accompanied this code.
 *
 * Modifications:
 * If applicable, add the following below the License Header, with the fields
 * enclosed by brackets [] replaced by your own identifying information:
 * "Portions Copyright [year] [name of copyright owner]"
 *
 * Contributor(s):
 * If you wish your version of this file to be governed by only the CDDL or
 * only the GPL Version 2, indicate your decision by adding "[Contributor]
 * elects to include this software in this distribution under the [CDDL or GPL
 * Version 2] license."  If you don't indicate a single choice of license, a
 * recipient has the option to distribute your version of this file under
 * either the CDDL, the GPL Version 2 or to extend the choice of license to
 * its licensees as provided above.  However, if you add GPL Version 2 code
 * and therefore, elected the GPL Version 2 license, then the option applies
 * only if the new code is made subject to such option by the copyright
 * holder.
 */

package com.sun.jdo.spi.persistence.support.sqlstore;

/**
 * An object that manages the state transitions and the contents of the
 * fields of a JDO Instance.
 *
 * If a JDO Instance is persistent or transactional, it contains a
 * non-null reference to a JDO <code>StateManager instance which is
 * responsible for managing the JDO Instance state changes and for
 * interfacing with the JDO PersistenceManager.
 *
 * Additionally, Persistent JDO Instances refers to an instance of the
 * JDO <code>StateManager instance responsible for the state
 * transitions of the instance as well as managing the contents of the
 * fields of the instance.
 *
 * The JDO <code>StateManager interface is the primary interface used
 * by the JDO Instance to mediate life cycle changes.  Non-transient JDO
 * Instances always contain a non-null reference to an associated JDO
 * <code>StateManager instance.
 *
 * When a First Class Object is instantiated in the JVM, the JDO
 * implementation assigns to fields with a Tracked Second Class Object
 * type a new instance that tracks changes made to itself, and
 * notifies the <code>StateManager of the owning First Class Object
 * of the change.
 */
public interface StateManager
{
    static final byte LOAD_REQUIRED  = (byte)1;

    static final byte READ_OK        = (byte)-1;

    static final byte READ_WRITE_OK  = (byte)0;


    /**
     * The <code>PersistenceManager needs to call this method
     * in order to make an instance persistent.
     */
    void makePersistent(PersistenceManager pm, Object pc);

    /**
     * ...
     *
     * The <code>PersistenceManager calls this method to delete
     * a persistent instance.
     */
    void deletePersistent();

    /**
     * ...
     *
     * The <code>PersistenceManager calls this method to flush
     * changes made to the <code>StateManager to the database.
     * The specified StateManager argument is used to determine whether the
     * actual instance should be flushed immediately or whether batch update
     * is possible.
     */
    void updatePersistent(StateManager next);

    /**
     * ...
     *
     * The <code>PersistenceManager calls this method to refresh
     * the state of the <code>StateManager from the database.
     */
    void refreshPersistent();

    /**
     *  ...
     *
     * The <code>PersistenceManager calls this method to inform
     * the <code>StateManager that the transaction has been committed.
     */
    void commit(boolean retainValues);


    /**
     *  ...
     *
     * The <code>PersistenceManager calls this method to inform
     * the <code>StateManager that the transaction has been rolled back.
     */
    void rollback(boolean retainValues);

    /**
     *  ...
     *
     * The <code>PersistenceManager calls this method to inform
     * the <code>StateManager that the flush processing is completed.
     */
    void flushed();

    /**
     * ...
     * The <code>PersistenceManager calls this method to verify
     * that corresponding object has been flushed to the database
     */
    boolean isProcessed();

    /**
     * ...
     */
    void setPersistenceManager(com.sun.jdo.api.persistence.support.PersistenceManager pm);

    /**
     * ...
     */
    com.sun.jdo.api.persistence.support.PersistenceManager getPersistenceManager();

    /**
     * ...
     */
    com.sun.jdo.api.persistence.support.PersistenceManager getPersistenceManagerInternal();

    /**
     * set actualImage associated with this <code>StateManager
     */
    void setPersistent(Object obj);

    /**
     * get actualImage associated with this <code>StateManager
     */
    Object getPersistent();

    /**
     * ...
     */
    void setObjectId(Object objectId);

    /**
     * ...
     */
    Object getObjectId();

    /**
     * ...
     */
    PersistenceConfig getPersistenceConfig();

    /**
     * State initialization
     * @param persistentInDB  true if object is persistent in DB
     */
    void initialize(boolean persistentInDB);

    /**
     * ...
     */
    void makePresent(String fieldName, Object value);

    /**
     * ...
     */
    void makeDirty(String fieldName);

    /**
     * ...
     */
    void applyUpdates(String fieldName, SCOCollection c);

    /**
     * ...
     */
    void replaceObjectField(String fieldName, Object o);

    /* The <code>PersistenceManager calls this method to prepare
     * a persistent object for update. This is required for
     * foreign fields only as they could reference "regular" jdk
     * Collections vs. SCO Collections. Such process has the side-effect of
     * causing more objects to be registered with the transaction cache.
     */
    void prepareToUpdatePhaseI();

    /**
     * This is the second phase of the commit processing. It populates phase3sms with all
     * the autopersistence instances that are no longer reachable from a persistent instance.
     */
    void prepareToUpdatePhaseII(java.util.HashSet phase3sms);

    /**
     * This is the third phase of commit processing. It sets up the delete dependencies among
     * all the autopersistent instances that have been flushed to the database.
     */
    void prepareToUpdatePhaseIII();

    /**
     * ...
     */
    //@olsen: changed to return byte instead of void (->PC.jdoSetFlags())
    byte setFlags(byte flags);

    /**
     * ...
     */
    void loadForRead();

    /**
     * ...
     */
    void loadForUpdate();

    //
    // Status interrogation methods
    //
    // For each one of these methods, there is a corresponding version
    // of it prefixed with jdo on the PersistenceCapable class. These
    // methods are used to query the state o an instance. For example,
    // when jdoIsReadReady is called on the PersistenceCapable
    // instance, the generated <code>jdoIsReadReady will delegate the
    // status interrogation to the <code>StateManager by call
    // <code>isReadReady().
    //

    /*
     * ...
     */
    boolean isDirty();

    /**
     * ...
     */
    boolean isTransactional();

    /**
     * ...
     */
    boolean isNew();

    /**
     * ...
     */
    boolean isDeleted();

    /**
     * ...
     */
    boolean isPersistent();

    /**
     * @return True, if this instance is persistent, transactional, not new,
     * not dirty, and not deleted; false otherwise.
     */
    boolean needsRegisterWithVersionConsistencyCache();

    /**
     * @return True, if this instance should be synchronized with
     * the version consistency cache; false otherwise.
     */
    boolean needsUpdateInVersionConsistencyCache();

    //
    // Getter and setter methods
    //
    // These are methods for accessing the persistent field values
    // from the <code>StateManager. The getter method can also serve
    // as the hook for triggering dynamic navigation for fields that have not
    // been fetched. The setter methods can also serve as the hook for
    // keeping track of changes made to the <code>StateManager.
    //

    //@olsen: changed to use 'int' instead of 'short' as field number type
    //@olsen: changed setter methods to return value instead of void
    //@olsen: added method prepareGetField()

    void prepareGetField(int fieldID);

    boolean setBooleanField(int fieldNumber, boolean value);

    boolean[] setBooleanArrayField(int fieldNumber, boolean[] value);

    byte setByteField(int fieldNumber, byte value);

    byte[] setByteArrayField(int fieldNumber, byte[] value);

    short setShortField(int fieldNumber, short value);

    short[] setShortArrayField(int fieldNumber, short[] value);

    int setIntField(int fieldNumber, int value);

    int[] setIntArrayField(int fieldNumber, int[] value);

    long setLongField(int fieldNumber, long value);

    long[] setLongArrayField(int fieldNumber, long[] value);

    char setCharField(int fieldNumber, char value);

    char setCharArrayField(int fieldNumber, char value);

    float setFloatField(int fieldNumber, float value);

    float[] setFloatArrayField(int fieldNumber, float[] value);

    double setDoubleField(int fieldNumber, double value);

    double[] setDoubleArrayField(int fieldNumber, double[] value);

    String setStringField(int fieldNumber, String value);

    String[] setStringArrayField(int fieldNumber, String[] value);

    Object setObjectField(int fieldNumber, Object value);

    Object[] setObjectArrayField(int fieldNumber, Object[] value);

    /**
     * Lock this instance. This method must be called the same
     * number of times as #releaseLock().
     */
    void getLock();

    /**
     * Release this instance. This method must be called the same
     * number of times as #getLock().
     */
    void releaseLock();

    /**
     * Returns value for a hidden field. This method expects index
     * to be negative for hidden fields.
     * @param index  - the hidden field index.
     */
    Object getHiddenValue(int index);

    /**
     * Sets value for a hidden field. This method expects index
     * to be negative for hidden fields.
     * @param index  - the hidden field index.
     * @param value - new value.
     */
    void setHiddenValue(int index, Object value);

    /**
     * Marks field with this index as present.
     * @param index - the field number.
     */
     void setPresenceMaskBit(int index) ;

    /**
     * Returns true if field with this index is present in the instance.
     */
    boolean getPresenceMaskBit(int index);

    /**
     * Notifies the StateManager that this instance needs to be registered
     * with the global (weak) cache at rollback if it transitions to persistent
     * state.
     * Used for replacing a deleted instance with the newly persistent with
     * the same object id.
     */
    void markNotRegistered();

    /**
     * Notifies the StateManager that this instance needs to be verified at
     * the time it is removed from the global (weak) cache at rollback if it
     * transitions to transient state.
     */
    void markVerifyAtDeregister();

    /**
     * Adds another StateManager to this StateManager dependencies list.
     * @param sm the StateManager to add.
     */
    void addDependency(StateManager sm);

    /**
     * Tries to resolve the dependencies for all instances waiting for the
     * current state manager to be flushed to the store.
     */
    void resolveDependencies();

    /**
     * Notifies the StateManager that this instance is a replacement for a
     * deleted instance with the same ObjectId.
     */
    void markReplacement();

    /**
     * Release references in the StateManager to the persistent instance,
     * ObjectId, and PersistenceManager.
     */
    void release();

    /** Returns true if this StateManager is valid for use.
     * The <code>valid flag is initially set to false and changed to true
     * when the first operation (e.g. makePersistent(), loadForRead(), or
     * PersistenceManager.getObjectById()) succeeds.
     */
    boolean isValid();

    /** Mark this StateManager as valid. Called before returning from
     * getObjectById. Flag is set to true internally in the StateManager
     * at makePersistent(), or initialize(true) (to be used for storing
     * query or navigation results.
     */
    void setValid();

    /** Reload the instance associated with this StateManager. Called by
     * {@link PersistenceManager#getObjectById(Object, boolean)
     * PersistenceManager.getObjectById(Object, boolean)} with validate
     * flag set to <code>true
     */
    void reload();

    /**
     * Returns true, if the managed instance has Version Consistency.
     * @return  True, if the managed object has Version Consistency.
     */
    boolean hasVersionConsistency();

    /**
     * Copies field values from <code>source to this
     * StateManager's fields.
     * @param source StateManager from which field values are
     * copied into this instance.
     */
    void copyFields(StateManager source);

    /**
     * Verify that an instance set up with Version consistency is not modified
     * in a parallel transaction.
     * @return false if the instance is persistent clean and modified by a
     * parallel transaction, true otherwise.
     */
    boolean verifyPersistent();

    /**
     * Marks that this state manager has failed version consistency
     * validation.
     */
    void setVerificationFailed();

    /**
     * Returns, if this state manager has failed version consistency
     * validation.
     *
     * @return True, if this state manager is marked as failed.
     */
    boolean isVerificationFailed();
}