/*
 * Copyright 2005 The Apache Software Foundation.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at 
 * 
 *     http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software 
 * distributed under the License is distributed on an "AS IS" BASIS, 
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
 * See the License for the specific language governing permissions and 
 * limitations under the License.
 */

/*
 * StateInterrogation.java
 *
 */
 
package javax.jdo.spi;

import javax.jdo.PersistenceManager;

/**
 * This interface is implemented by a non-binary-compatible JDO implementation
 * to provide state interrogation for non-enhanced persistent classes.
 *
 * <P>A call to JDOHelper to get the status of an instance is handled
 * internally if the parameter instance implements PersistenceCapable. 
 * For non-binary-compatible implementations, there is no requirement
 * that persistent instances implement PersistenceCapable. Therefore,
 * if the parameter does not implement PersistenceCapable, JDOHelper
 * delegates to all registered instances of StateInterrogation until
 * an instance can handle the request.
 * <P>For JDOHelper isXXX methods, which return boolean, the 
 * corresponding method in StateInterrogation returns Boolean. If the
 * return value is <code>null</code> then the StateInterrogation does
 * not recognize the parameter as being handled by it. A non-null return
 * value indicates that the implementation has determined the answer.
 * <P>For JDOHelper getXXX methods, which return an Object, each
 * registered StateInterrogation is given the parameter until one of 
 * them returns a non-null value, which is passed to the caller.
 * <P>For JDOHelper makeDirty, each
 * registered StateInterrogation is given the parameter until one of 
 * them returns true, indicating that it has handled the call.
 * An instance that implements this interface must be registered with the
 * {@link JDOImplHelper}.
 * @version 2.0
 * @since 2.0
 */
public interface StateInterrogation {


    /** Tests whether the parameter instance is persistent.
     *
     * Instances that represent persistent objects in the data store 
     * return <code>Boolean.TRUE</code>. 
     *
     * <P>Instances known by the implementation to be non-persistent
     * return <code>Boolean.FALSE</code>.
     *
     * <P>Instances not recognized by the implementation return
     * <code>null</code>.
     *
     * @see PersistenceManager#makePersistent(Object pc)
     * @see PersistenceCapable#jdoIsPersistent()
     * @param pc the instance.
     * @return <code>Boolean.TRUE</code> if the parameter instance is persistent.
     */
    Boolean isPersistent (Object pc);

    /** Tests whether the parameter instance is transactional.
     *
     * Instances whose state is associated with the current transaction 
     * return <code>Boolean.TRUE</code>. 
     *
     * <P>Instances known by the implementation to be non-transactional
     * return <code>Boolean.FALSE</code>.
     *
     * <P>Instances not recognized by the implementation return
     * <code>null</code>.
     *
     * @see PersistenceCapable#jdoIsTransactional()
     * @param pc the instance.
     * @return <code>Boolean.TRUE</code> if the parameter instance is transactional.
     */
    Boolean isTransactional (Object pc);
    
    /** Tests whether the parameter instance is dirty.
     *
     * Instances that have been modified, deleted, newly 
     * made persistent in the current transaction,
     * or modified while detached return <code>Boolean.TRUE</code>.
     *
     * <P>Instances known by the implementation to be non-dirty
     * return <code>Boolean.FALSE</code>.
     *
     * <P>Instances not recognized by the implementation return
     * <code>null</code>.
     *
     * @see StateManager#makeDirty(PersistenceCapable pc, String fieldName)
     * @see PersistenceCapable#jdoIsDirty()
     * @param pc the instance.
     * @return <code>Boolean.TRUE</code> if the parameter instance has been modified
     * in the current transaction, or while detached.
     */
    Boolean isDirty (Object pc);

    /** Tests whether the parameter instance has been newly made persistent.
     *
     * Instances that have been made persistent in the current transaction 
     * return <code>Boolean.TRUE</code>.
     *
     * <P>Instances known by the implementation to be non-new
     * return <code>Boolean.FALSE</code>.
     *
     * <P>Instances not recognized by the implementation return
     * <code>null</code>.
     *
     * @see PersistenceManager#makePersistent(Object pc)
     * @see PersistenceCapable#jdoIsNew()
     * @param pc the instance.
     * @return <code>Boolean.TRUE</code> if the parameter instance was made persistent
     * in the current transaction.
     */
    Boolean isNew (Object pc);

    /** Tests whether the parameter instance has been deleted.
     *
     * Instances that have been deleted in the current transaction 
     * return <code>Boolean.TRUE</code>.
     *
     * <P>Instances known by the implementation to be non-deleted
     * return <code>Boolean.FALSE</code>.
     *
     * <P>Instances not recognized by the implementation return
     * <code>null</code>.
     *
     * @see PersistenceManager#deletePersistent(Object pc)
     * @see PersistenceCapable#jdoIsDeleted()
     * @param pc the instance.
     * @return <code>Boolean.TRUE</code> if the parameter instance was deleted
     * in the current transaction.
     */
    Boolean isDeleted (Object pc);

    /** Tests whether the parameter instance is detached.
     *
     * Instances that are detached return <code>Boolean.TRUE</code>.
     *
     * <P>Instances known by the implementation to be non-detached
     * return <code>Boolean.FALSE</code>.
     *
     * <P>Instances not recognized by the implementation return
     * <code>null</code>.
     *
     * @see PersistenceManager#detachCopy(Object pc)
     * @see PersistenceCapable#jdoIsDeleted()
     * @param pc the instance.
     * @return <code>Boolean.TRUE</code> if the parameter instance is detached.
     */
    Boolean isDetached (Object pc);

    /** Return the associated <code>PersistenceManager</code> if there is one.
     * Transactional and persistent instances return the associated
     * <code>PersistenceManager</code>.  
     *
     * <P>Transient non-transactional instances return <code>null</code>.
     * <P>Instances unknown by the implementation return <code>null</code>.
     * @see PersistenceCapable#jdoGetPersistenceManager()
     * @param pc the instance.
     * @return the <code>PersistenceManager</code> associated with the 
     * parameter instance.
     */
    PersistenceManager getPersistenceManager (Object pc);
    
    /** Return a copy of the JDO identity associated with the parameter 
     * instance.
     *
     * <P>Persistent instances of <code>PersistenceCapable</code> classes 
     * have a JDO identity
     * managed by the <code>PersistenceManager</code>.  This method returns 
     * a copy of the
     * ObjectId that represents the JDO identity.  
     * 
     * <P>Instances unknown by the implementation return <code>null</code>.
     * <P>The ObjectId may be serialized
     * and later restored, and used with a <code>PersistenceManager</code> 
     * from the same JDO
     * implementation to locate a persistent instance with the same data store
     * identity.
     *
     * <P>If the JDO identity is managed by the application, then the ObjectId
     * may be used with a <code>PersistenceManager</code> from any JDO 
     * implementation that supports
     * the <code>PersistenceCapable</code> class.
     *
     * <P>If the JDO identity is not managed by the application or the data 
     * store, then the ObjectId returned is only valid within the current 
     * transaction.
     *<P>
     * @see PersistenceManager#getObjectId(Object pc)
     * @see PersistenceCapable#jdoGetObjectId()
     * @see PersistenceManager#getObjectById(Object oid, boolean validate)
     * @param pc the instance.
     * @return a copy of the ObjectId of the parameter instance as of the 
     * beginning of the transaction.
     */
    Object getObjectId (Object pc);

    /** Return a copy of the JDO identity associated with the parameter 
     * instance.
     *
     * <P>Instances unknown by the implementation return <code>null</code>.
     * @see PersistenceCapable#jdoGetTransactionalObjectId()
     * @see PersistenceManager#getObjectById(Object oid, boolean validate)
     * @param pc the instance.
     * @return a copy of the ObjectId of the parameter instance as modified 
     * in this transaction.
     */
    Object getTransactionalObjectId (Object pc);
    
    /** Return the version of the parameter instance.
     *
     * <P>Instances unknown by the implementation return <code>null</code>.
     * @see PersistenceCapable#jdoGetVersion()
     * @param pc the instance.
     * @return a copy of the ObjectId of the parameter instance as modified 
     * in this transaction.
     */
    Object getVersion (Object pc);
    
    /** Explicitly mark the parameter instance and field dirty.
     * Normally, <code>PersistenceCapable</code> classes are able to detect 
     * changes made
     * to their fields.  However, if a reference to an array is given to a
     * method outside the class, and the array is modified, then the
     * persistent instance is not aware of the change.  This API allows the
     * application to notify the instance that a change was made to a field.
     *
     * <P>Instances unknown by the implementation are unaffected.
     * @see PersistenceCapable#jdoMakeDirty(String fieldName)
     * @param pc the instance.
     * @param fieldName the name of the field to be marked dirty.
     */
    boolean makeDirty (Object pc, String fieldName);

}