javax.jdo.spi.StateInterrogation Maven / Gradle / Ivy
Show all versions of jdo-api Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You 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.
*
* 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.
*
For JDOHelper isXXX methods, which return boolean, the
* corresponding method in StateInterrogation returns Boolean. If the
* return value is null 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.
*
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.
*
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 Boolean.TRUE.
*
*
Instances known by the implementation to be non-persistent
* return Boolean.FALSE.
*
*
Instances not recognized by the implementation return
* null.
*
* @see PersistenceManager#makePersistent(Object pc)
* @see PersistenceCapable#jdoIsPersistent()
* @param pc the instance.
* @return Boolean.TRUE 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 Boolean.TRUE.
*
*
Instances known by the implementation to be non-transactional
* return Boolean.FALSE.
*
*
Instances not recognized by the implementation return
* null.
*
* @see PersistenceCapable#jdoIsTransactional()
* @param pc the instance.
* @return Boolean.TRUE 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 Boolean.TRUE.
*
*
Instances known by the implementation to be non-dirty
* return Boolean.FALSE.
*
*
Instances not recognized by the implementation return
* null.
*
* @see StateManager#makeDirty(PersistenceCapable pc, String fieldName)
* @see PersistenceCapable#jdoIsDirty()
* @param pc the instance.
* @return Boolean.TRUE 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 Boolean.TRUE.
*
*
Instances known by the implementation to be non-new
* return Boolean.FALSE.
*
*
Instances not recognized by the implementation return
* null.
*
* @see PersistenceManager#makePersistent(Object pc)
* @see PersistenceCapable#jdoIsNew()
* @param pc the instance.
* @return Boolean.TRUE 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 Boolean.TRUE.
*
*
Instances known by the implementation to be non-deleted
* return Boolean.FALSE.
*
*
Instances not recognized by the implementation return
* null.
*
* @see PersistenceManager#deletePersistent(Object pc)
* @see PersistenceCapable#jdoIsDeleted()
* @param pc the instance.
* @return Boolean.TRUE 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 Boolean.TRUE.
*
*
Instances known by the implementation to be non-detached
* return Boolean.FALSE.
*
*
Instances not recognized by the implementation return
* null.
*
* @see PersistenceManager#detachCopy(Object pc)
* @see PersistenceCapable#jdoIsDeleted()
* @param pc the instance.
* @return Boolean.TRUE if the parameter instance is detached.
*/
Boolean isDetached (Object pc);
/** Return the associated PersistenceManager if there is one.
* Transactional and persistent instances return the associated
* PersistenceManager.
*
*
Transient non-transactional instances return null.
*
Instances unknown by the implementation return null.
* @see PersistenceCapable#jdoGetPersistenceManager()
* @param pc the instance.
* @return the PersistenceManager associated with the
* parameter instance.
*/
PersistenceManager getPersistenceManager (Object pc);
/** Return a copy of the JDO identity associated with the parameter
* instance.
*
*
Persistent instances of PersistenceCapable classes
* have a JDO identity
* managed by the PersistenceManager. This method returns
* a copy of the
* ObjectId that represents the JDO identity.
*
*
Instances unknown by the implementation return null.
*
The ObjectId may be serialized
* and later restored, and used with a PersistenceManager
* from the same JDO
* implementation to locate a persistent instance with the same data store
* identity.
*
*
If the JDO identity is managed by the application, then the ObjectId
* may be used with a PersistenceManager from any JDO
* implementation that supports
* the PersistenceCapable class.
*
*
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.
*
* @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.
*
*
Instances unknown by the implementation return null.
* @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.
*
*
Instances unknown by the implementation return null.
* @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, PersistenceCapable 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.
*
*
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.
* @return Whether it was made dirty
*/
boolean makeDirty (Object pc, String fieldName);
}