org.datanucleus.enhancement.StateManager Maven / Gradle / Ivy
Show all versions of datanucleus-core Show documentation
/**********************************************************************
Copyright (c) 2014 Andy Jefferson and others. All rights reserved.
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.
Contributors:
...
**********************************************************************/
package org.datanucleus.enhancement;
import org.datanucleus.exceptions.NucleusException;
import org.datanucleus.util.Localiser;
/**
* This interface is the point of contact between managed instances of Persistable classes and DataNucleus.
* It contains the methods used by Persistable instances to delegate behavior to DataNucleus.
*
* Each managed Persistable instance contains a reference to a StateManager.
* In principle, a StateManager might manage one or multiple instances of Persistable instances.
* In reality we only ever manage a single Persistable instance here, see StateManagerImpl.
*/
public interface StateManager
{
/**
* Return the ExecutionContext that owns this instance.
* @return the ExecutionContext that owns this instance
*/
ExecutionContextReference getExecutionContextReference();
/**
* The owning StateManager uses this method to supply the value of the flags to the
* Persistable instance.
* @param pc the calling Persistable instance
* @return the value of dnFlags to be stored in the Persistable instance
*/
byte replacingFlags(Persistable pc);
/**
* Replace the current value of dnStateManager.
*
* This method is called by the Persistable whenever dnReplaceStateManager is
* called and there is already an owning StateManager. This is a security precaution to
* ensure that the owning StateManager is the only source of any change to its reference in
* the Persistable.
* @return the new value for the dnStateManager
* @param pc the calling Persistable instance
* @param sm the proposed new value for the dnStateManager
*/
StateManager replacingStateManager(Persistable pc, StateManager sm);
/**
* Tests whether this object is dirty.
* Instances that have been modified, deleted, or newly made persistent in the current transaction return true.
*
* Transient nontransactional instances return false.
*
* @see Persistable#dnMakeDirty(String fieldName)
* @param pc the calling Persistable instance
* @return true if this instance has been modified in the current transaction.
*/
boolean isDirty(Persistable pc);
/**
* Tests whether this object is transactional.
* Instances that respect transaction boundaries return true.
* These instances include transient instances made transactional as a result of being the target of a makeTransactional method call;
* newly made persistent or deleted persistent instances; persistent instances read in data store transactions; and persistent instances modified
* in optimistic transactions.
*
* Transient nontransactional instances return false.
*
* @param pc the calling Persistable instance
* @return true if this instance is transactional.
*/
boolean isTransactional(Persistable pc);
/**
* Tests whether this object is persistent.
* Instances whose state is stored in the data store return true.
*
* Transient instances return false.
*
* @param pc the calling Persistable instance
* @return true if this instance is persistent.
*/
boolean isPersistent(Persistable pc);
/**
* Tests whether this object has been newly made persistent.
* Instances that have been made persistent in the current transaction return true.
*
* Transient instances return false.
*
* @param pc the calling Persistable instance
* @return true if this instance was made persistent in the current transaction.
*/
boolean isNew(Persistable pc);
/**
* Tests whether this object has been deleted.
* Instances that have been deleted in the current transaction return true.
*
* Transient instances return false.
*
* @param pc the calling Persistable instance
* @return true if this instance was deleted in the current transaction.
*/
boolean isDeleted(Persistable pc);
/**
* Mark the associated Persistable field dirty.
*
* The StateManager will make a copy of the field so it can be restored if needed later, and
* then mark the field as modified in the current transaction.
* @param pc the calling Persistable instance
* @param fieldName the name of the field
*/
void makeDirty(Persistable pc, String fieldName);
/**
* Return the object representing the identity of the calling instance.
* If the identity is being changed in the current transaction, this method returns the identity as of the beginning of the transaction.
* @param pc the calling Persistable instance
* @return the object representing the identity of the calling instance
*/
Object getObjectId(Persistable pc);
/**
* Return the object representing the identity of the calling instance.
* If the identity is being changed in the current transaction, this method returns the current identity as changed in the transaction.
* @param pc the calling Persistable instance
* @return the object representing the identity of the calling instance
*/
Object getTransactionalObjectId(Persistable pc);
/**
* Return the object representing the version of the calling instance.
* @param pc the calling Persistable instance
* @return the object representing the version of the calling instance
*/
Object getVersion(Persistable pc);
/**
* Return true if the field is cached in the calling instance.
* @param pc the calling Persistable instance
* @param field the field number
* @return whether the field is cached in the calling instance
*/
boolean isLoaded(Persistable pc, int field);
/**
* Guarantee that the serializable transactional and persistent fields are loaded into the instance. This
* method is called by the generated dnPreSerialize method prior to serialization of the
* instance.
* @param pc the calling Persistable instance
*/
void preSerialize(Persistable pc);
/**
* Return the value for the field.
* Never called since isLoaded always returns null.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @return the new value for the field
*/
default boolean getBooleanField(Persistable pc, int field, boolean currentValue)
{
throw new NucleusException(Localiser.msg("026006"));
}
/**
* Return the value for the field.
* Never called since isLoaded always returns null.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @return the new value for the field
*/
default char getCharField(Persistable pc, int field, char currentValue)
{
throw new NucleusException(Localiser.msg("026006"));
}
/**
* Return the value for the field.
* Never called since isLoaded always returns null.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @return the new value for the field
*/
default byte getByteField(Persistable pc, int field, byte currentValue)
{
throw new NucleusException(Localiser.msg("026006"));
}
/**
* Return the value for the field.
* Never called since isLoaded always returns null.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @return the new value for the field
*/
default short getShortField(Persistable pc, int field, short currentValue)
{
throw new NucleusException(Localiser.msg("026006"));
}
/**
* Return the value for the field.
* Never called since isLoaded always returns null.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @return the new value for the field
*/
default int getIntField(Persistable pc, int field, int currentValue)
{
throw new NucleusException(Localiser.msg("026006"));
}
/**
* Return the value for the field.
* Never called since isLoaded always returns null.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @return the new value for the field
*/
default long getLongField(Persistable pc, int field, long currentValue)
{
throw new NucleusException(Localiser.msg("026006"));
}
/**
* Return the value for the field.
* Never called since isLoaded always returns null.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @return the new value for the field
*/
default float getFloatField(Persistable pc, int field, float currentValue)
{
throw new NucleusException(Localiser.msg("026006"));
}
/**
* Return the value for the field.
* Never called since isLoaded always returns null.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @return the new value for the field
*/
default double getDoubleField(Persistable pc, int field, double currentValue)
{
throw new NucleusException(Localiser.msg("026006"));
}
/**
* Return the value for the field.
* Never called since isLoaded always returns null.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @return the new value for the field
*/
default String getStringField(Persistable pc, int field, String currentValue)
{
throw new NucleusException(Localiser.msg("026006"));
}
/**
* Return the value for the field.
* Never called since isLoaded always returns null.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @return the new value for the field
*/
default Object getObjectField(Persistable pc, int field, Object currentValue)
{
throw new NucleusException(Localiser.msg("026006"));
}
/**
* Mark the field as modified by the user.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @param newValue the proposed new value of the field
*/
void setBooleanField(Persistable pc, int field, boolean currentValue, boolean newValue);
/**
* Mark the field as modified by the user.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @param newValue the proposed new value of the field
*/
void setCharField(Persistable pc, int field, char currentValue, char newValue);
/**
* Mark the field as modified by the user.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @param newValue the proposed new value of the field
*/
void setByteField(Persistable pc, int field, byte currentValue, byte newValue);
/**
* Mark the field as modified by the user.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @param newValue the proposed new value of the field
*/
void setShortField(Persistable pc, int field, short currentValue, short newValue);
/**
* Mark the field as modified by the user.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @param newValue the proposed new value of the field
*/
void setIntField(Persistable pc, int field, int currentValue, int newValue);
/**
* Mark the field as modified by the user.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @param newValue the proposed new value of the field
*/
void setLongField(Persistable pc, int field, long currentValue, long newValue);
/**
* Mark the field as modified by the user.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @param newValue the proposed new value of the field
*/
void setFloatField(Persistable pc, int field, float currentValue, float newValue);
/**
* Mark the field as modified by the user.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @param newValue the proposed new value of the field
*/
void setDoubleField(Persistable pc, int field, double currentValue, double newValue);
/**
* Mark the field as modified by the user.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @param newValue the proposed new value of the field
*/
void setStringField(Persistable pc, int field, String currentValue, String newValue);
/**
* Mark the field as modified by the user.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
* @param newValue the proposed new value of the field
*/
void setObjectField(Persistable pc, int field, Object currentValue, Object newValue);
/**
* The value of the field requested to be provided to the StateManager.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
*/
void providedBooleanField(Persistable pc, int field, boolean currentValue);
/**
* The value of the field requested to be provided to the StateManager.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
*/
void providedCharField(Persistable pc, int field, char currentValue);
/**
* The value of the field requested to be provided to the StateManager.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
*/
void providedByteField(Persistable pc, int field, byte currentValue);
/**
* The value of the field requested to be provided to the StateManager.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
*/
void providedShortField(Persistable pc, int field, short currentValue);
/**
* The value of the field requested to be provided to the StateManager.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
*/
void providedIntField(Persistable pc, int field, int currentValue);
/**
* The value of the field requested to be provided to the StateManager.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
*/
void providedLongField(Persistable pc, int field, long currentValue);
/**
* The value of the field requested to be provided to the StateManager.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
*/
void providedFloatField(Persistable pc, int field, float currentValue);
/**
* The value of the field requested to be provided to the StateManager.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
*/
void providedDoubleField(Persistable pc, int field, double currentValue);
/**
* The value of the field requested to be provided to the StateManager.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
*/
void providedStringField(Persistable pc, int field, String currentValue);
/**
* The value of the field requested to be provided to the StateManager.
* @param pc the calling Persistable instance
* @param field the field number
* @param currentValue the current value of the field
*/
void providedObjectField(Persistable pc, int field, Object currentValue);
/**
* The replacement value of the field in the calling instance.
* @param pc the calling Persistable instance
* @param field the field number
* @return the new value for the field
*/
boolean replacingBooleanField(Persistable pc, int field);
/**
* The replacement value of the field in the calling instance.
* @param pc the calling Persistable instance
* @param field the field number
* @return the new value for the field
*/
char replacingCharField(Persistable pc, int field);
/**
* The replacement value of the field in the calling instance.
* @param pc the calling Persistable instance
* @param field the field number
* @return the new value for the field
*/
byte replacingByteField(Persistable pc, int field);
/**
* The replacement value of the field in the calling instance.
* @param pc the calling Persistable instance
* @param field the field number
* @return the new value for the field
*/
short replacingShortField(Persistable pc, int field);
/**
* The replacement value of the field in the calling instance.
* @param pc the calling Persistable instance
* @param field the field number
* @return the new value for the field
*/
int replacingIntField(Persistable pc, int field);
/**
* The replacement value of the field in the calling instance.
* @param pc the calling Persistable instance
* @param field the field number
* @return the new value for the field
*/
long replacingLongField(Persistable pc, int field);
/**
* The replacement value of the field in the calling instance.
* @param pc the calling Persistable instance
* @param field the field number
* @return the new value for the field
*/
float replacingFloatField(Persistable pc, int field);
/**
* The replacement value of the field in the calling instance.
* @param pc the calling Persistable instance
* @param field the field number
* @return the new value for the field
*/
double replacingDoubleField(Persistable pc, int field);
/**
* The replacement value of the field in the calling instance.
* @param pc the calling Persistable instance
* @param field the field number
* @return the new value for the field
*/
String replacingStringField(Persistable pc, int field);
/**
* The replacement value of the field in the calling instance.
* @param pc the calling Persistable instance
* @param field the field number
* @return the new value for the field
*/
Object replacingObjectField(Persistable pc, int field);
/**
* The replacement value of the detached state in the calling instance.
* @param pc the calling Detachable instance
* @param state the current value of the detached state
* @return the replacement value for the detached state
*/
Object[] replacingDetachedState(Detachable pc, Object[] state);
}