org.datanucleus.store.types

Class SCOUtils

java.lang.Object

org.datanucleus.store.types.SCOUtils

public class SCOUtils
extends Object

Collection of utilities for second class wrappers and objects.

Constructor Summary

Constructors

Constructor and Description
SCOUtils()

Method Summary

Modifier and Type	Method and Description
static boolean	allowNullsInContainer(boolean defaultValue, AbstractMemberMetaData mmd) Utility to return whether or not to allow nulls in the container for the specified field.
static boolean	arrayIsStoredInSingleColumn(AbstractMemberMetaData fmd, MetaDataManager mmgr) Convenience method to return if an array field has the elements stored into the table of the field as a single (BLOB) column.
static boolean	attachCopyElements(ObjectProvider ownerOP, Collection scoColl, Collection detachedElements, boolean elementsWithoutId) Convenience method for use by Collection/Set/HashSet attachCopy methods to add any new elements (added whilst detached) to the collection.
static void	attachCopyForCollection(ObjectProvider ownerOP, Object[] detachedElements, Collection attached, boolean elementsWithoutIdentity) Method to return an attached copy of the passed (detached) value.
static void	attachCopyForMap(ObjectProvider ownerOP, Set detachedEntries, Map attached, boolean keysWithoutIdentity, boolean valuesWithoutIdentity) Method to return an attached copy of the passed (detached) value.
static void	attachForCollection(ObjectProvider ownerOP, Object[] elements, boolean elementsWithoutIdentity) Convenience method to attach (recursively) all elements for a collection field.
static void	attachForMap(ObjectProvider ownerOP, Set entries, boolean keysWithoutIdentity, boolean valuesWithoutIdentity) Convenience method to attach (recursively) all keys/values for a map field.
static boolean	collectionHasElementsWithoutIdentity(AbstractMemberMetaData mmd) Convenience method to return if a collection field has elements without their own identity.
static boolean	collectionHasSerialisedElements(AbstractMemberMetaData fmd) Convenience method to return if a collection field has the elements serialised into the table of the field as a single BLOB.
static boolean	collectionsAreEqual(ApiAdapter api, Collection oldColl, Collection newColl) Convenience method to return if two collections of persistent elements are equal.
static Object	copyValue(Object scoValue) Copy a value if it's an *known* SCO type.
static boolean	detachAsWrapped(ObjectProvider ownerOP) Convenience accessor for whether to detach SCO objects as wrapped.
static void	detachCopyForCollection(ObjectProvider ownerOP, Object[] elements, FetchPlanState state, Collection detached) Convenience method to detach copies (recursively) of all elements for a collection field.
static void	detachCopyForMap(ObjectProvider ownerOP, Set entries, FetchPlanState state, Map detached) Convenience method to detach copies (recursively) of all elements for a map field.
static void	detachForCollection(ObjectProvider ownerOP, Object[] elements, FetchPlanState state) Convenience method to detach (recursively) all elements for a collection field.
static void	detachForMap(ObjectProvider ownerOP, Set entries, FetchPlanState state) Convenience method to detach (recursively) all elements for a map field.
static Comparator	getComparator(AbstractMemberMetaData mmd, ClassLoaderResolver clr) Convenience method for creating a Comparator using extension metadata tags for the specified field.
static String	getContainerInfoMessage(ObjectProvider ownerOP, String fieldName, SCOContainer cont, boolean useCache, boolean allowNulls, boolean lazyLoading) Utility to generate a message representing the SCO container wrapper and its capabilities.
static Class	getContainerInstanceType(Class declaredType, Boolean ordered) Method to return the type to instantiate a container as.
static String	getSCOWrapperOptionsMessage(boolean useCache, boolean queued, boolean allowNulls, boolean lazyLoading) Convenience method to generate a message containing the options of this SCO wrapper.
static boolean	hasDependentElement(AbstractMemberMetaData mmd) Method to return if the member is a collection/array with dependent element.
static boolean	hasDependentKey(AbstractMemberMetaData mmd) Method to return if the member is a map with dependent key.
static boolean	hasDependentValue(AbstractMemberMetaData mmd) Method to return if the member is a map with dependent value.
static boolean	isListBased(Class type) Return whether the supplied type (collection) is list based.
static boolean	mapHasKeysWithoutIdentity(AbstractMemberMetaData fmd) Convenience method to return if a map field has keys without their own identity.
static boolean	mapHasSerialisedKeysAndValues(AbstractMemberMetaData fmd) Convenience method to return if a map field has the keys/values serialised.
static boolean	mapHasValuesWithoutIdentity(AbstractMemberMetaData fmd) Convenience method to return if a map field has values without their own identity.
static SCO	newSCOInstance(ObjectProvider ownerOP, AbstractMemberMetaData mmd, Class instantiatedType, Object value, boolean replaceField) Method to create a new SCO wrapper for a SCO type.
static void	populateMapDelegateWithStoreData(Map delegate, MapStore store, ObjectProvider ownerOP) Convenience method to populate the passed delegate Map with the keys/values from the associated Store.
static Object	singleCollectionValue(TypeManager typeManager, Object pc)
static Object[]	toArray(CollectionStore backingStore, ObjectProvider op) Returns true if this collection contains the specified element.
static Object[]	toArray(CollectionStore backingStore, ObjectProvider op, Object[] a) Returns an array containing all of the elements in this collection;
static Object	unwrapSCOField(ObjectProvider ownerOP, int memberNumber, SCO sco) Method to unwrap a SCO field/property (if it is wrapped currently).
static boolean	updateCollectionWithCollection(ApiAdapter api, Collection coll, Collection elements) Convenience method to update a Collection to match the provided elements.
static boolean	updateListWithListElements(List list, List elements) Convenience method for use by List attachCopy methods to update the passed (attached) list using the (attached) list elements passed.
static boolean	updateMapWithMapKeysValues(ApiAdapter api, Map map, Map keysValues) Convenience method for use by Map attachCopy methods to update the passed (attached) map using the (attached) map keys/values passed.
static boolean	useCachedLazyLoading(ObjectProvider ownerOP, AbstractMemberMetaData mmd) Accessor for whether the use lazy loading when caching the collection.
static boolean	useContainerCache(ObjectProvider ownerOP, AbstractMemberMetaData mmd) Utility to return whether or not to use the container cache for the collection/map for the passed ObjectProvider SCO.
static boolean	useQueuedUpdate(ObjectProvider op) Convenience method to return if we should use a queued update for the current operation.
static boolean	validateObjectForWriting(ExecutionContext ec, Object object, FieldValues fieldValues) Method to check if an object to be stored in a SCO container is already persistent, or is managed by a different ExecutionContext.
static Object	wrapAndReplaceSCOField(ObjectProvider ownerOP, int memberNumber, Object newValue, Object oldValue, boolean replaceFieldIfChanged) Method to create a new SCO wrapper for the specified field replacing the old value with the new value.
static Object	wrapSCOField(ObjectProvider ownerOP, int memberNumber, Object value, boolean replaceFieldIfChanged) Method to create a new SCO wrapper for the specified field/property.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SCOUtils

public SCOUtils()

Method Detail

unwrapSCOField

public static Object unwrapSCOField(ObjectProvider ownerOP,
                                    int memberNumber,
                                    SCO sco)

Method to unwrap a SCO field/property (if it is wrapped currently). If the member value is not a SCO will just return the value.

Parameters:

ownerOP - The ObjectProvider of the owner

memberNumber - The member number in the owner

sco - The SCO value for the member

Returns:

The unwrapped member value

wrapSCOField

public static Object wrapSCOField(ObjectProvider ownerOP,
                                  int memberNumber,
                                  Object value,
                                  boolean replaceFieldIfChanged)

Method to create a new SCO wrapper for the specified field/property. If the member value is a SCO already will just return the value.

Parameters:

ownerOP - The ObjectProvider of the owner

memberNumber - The member number in the owner

value - The value to initialise the wrapper with (if any)

replaceFieldIfChanged - Whether to replace the member in the object if wrapping the value

Returns:

The wrapper (or original value if not wrappable)

wrapAndReplaceSCOField

public static Object wrapAndReplaceSCOField(ObjectProvider ownerOP,
                                            int memberNumber,
                                            Object newValue,
                                            Object oldValue,
                                            boolean replaceFieldIfChanged)

Method to create a new SCO wrapper for the specified field replacing the old value with the new value. If the member value is a SCO already will just return the (new) value.

Parameters:

ownerOP - The ObjectProvider of the owner object

memberNumber - The member number in the owner

newValue - The value to initialise the wrapper with (if any) for this member

oldValue - The previous value that we are replacing with this value

replaceFieldIfChanged - Whether to replace the member in the object if wrapping the value

Returns:

The wrapper (or original value if not wrappable)

newSCOInstance

public static SCO newSCOInstance(ObjectProvider ownerOP,
                                 AbstractMemberMetaData mmd,
                                 Class instantiatedType,
                                 Object value,
                                 boolean replaceField)

Method to create a new SCO wrapper for a SCO type. The SCO wrapper will be appropriate for the passed value (which represents the instantiated type of the field) unless it is null when the wrapper will be appropriate for the declared type of the field. While the "instantiated type" and the type of "value" should be the same when value is non-null, there are situations where we need to create a List based collection yet have no value so pass in the declaredType as Collection, instantiatedType as ArrayList, and value as null.

Parameters:

ownerOP - ObjectProvider for the owning object

mmd - The MetaData for the related member.

instantiatedType - Instantiated type for the member (if known)

value - The value we are wrapping if known

replaceField - Whether to replace the member with this value

Returns:

The Second-Class Object

Throws:

NucleusUserException - if an error occurred when creating the SCO instance

getContainerInfoMessage

public static String getContainerInfoMessage(ObjectProvider ownerOP,
                                             String fieldName,
                                             SCOContainer cont,
                                             boolean useCache,
                                             boolean allowNulls,
                                             boolean lazyLoading)

Utility to generate a message representing the SCO container wrapper and its capabilities.

Parameters:

ownerOP - ObjectProvider for the owner

fieldName - Field with the container

cont - The SCOContainer

useCache - Whether to use caching of values in the container

allowNulls - Whether to allow nulls

lazyLoading - Whether to use lazy loading in the wrapper

Returns:

The String

getSCOWrapperOptionsMessage

public static String getSCOWrapperOptionsMessage(boolean useCache,
                                                 boolean queued,
                                                 boolean allowNulls,
                                                 boolean lazyLoading)

Convenience method to generate a message containing the options of this SCO wrapper.

Parameters:

useCache - Whether to cache the value in the wrapper (and not go to the datastore)

queued - Whether it supports queueing of updates

allowNulls - Whether it allows null entries

lazyLoading - Whether it is lazy loaded

Returns:

the message

allowNullsInContainer

public static boolean allowNullsInContainer(boolean defaultValue,
                                            AbstractMemberMetaData mmd)

Utility to return whether or not to allow nulls in the container for the specified field.

Parameters:

defaultValue - Default value for the container

mmd - MetaData for the field/property

Returns:

Whether to allow nulls

useContainerCache

public static boolean useContainerCache(ObjectProvider ownerOP,
                                        AbstractMemberMetaData mmd)

Utility to return whether or not to use the container cache for the collection/map for the passed ObjectProvider SCO.

Parameters:

ownerOP - The ObjectProvider for the SCO field

mmd - Metadata for the member that we are considering

Returns:

Whether to use the cache.

useCachedLazyLoading

public static boolean useCachedLazyLoading(ObjectProvider ownerOP,
                                           AbstractMemberMetaData mmd)

Accessor for whether the use lazy loading when caching the collection.

Parameters:

ownerOP - ObjectProvider of the owning object

mmd - Meta-data of the collection/map field

Returns:

Whether to use lazy loading when caching the collection

collectionHasElementsWithoutIdentity

public static boolean collectionHasElementsWithoutIdentity(AbstractMemberMetaData mmd)

Convenience method to return if a collection field has elements without their own identity. Checks if the elements are embedded in a join table, or in the main table, or serialised.

Parameters:

mmd - MetaData for the field

Returns:

Whether the elements have their own identity or not

mapHasKeysWithoutIdentity

public static boolean mapHasKeysWithoutIdentity(AbstractMemberMetaData fmd)

Convenience method to return if a map field has keys without their own identity. Checks if the keys are embedded in a join table, or in the main table, or serialised.

Parameters:

fmd - MetaData for the field

Returns:

Whether the keys have their own identity or not

mapHasValuesWithoutIdentity

public static boolean mapHasValuesWithoutIdentity(AbstractMemberMetaData fmd)

Convenience method to return if a map field has values without their own identity. Checks if the values are embedded in a join table, or in the main table, or serialised.

Parameters:

fmd - MetaData for the field

Returns:

Whether the values have their own identity or not

collectionHasSerialisedElements

public static boolean collectionHasSerialisedElements(AbstractMemberMetaData fmd)

Convenience method to return if a collection field has the elements serialised into the table of the field as a single BLOB. This is really for use within an RDBMS context.

Parameters:

fmd - MetaData for the field

Returns:

Whether the elements are serialised (either explicitly or implicitly)

arrayIsStoredInSingleColumn

public static boolean arrayIsStoredInSingleColumn(AbstractMemberMetaData fmd,
                                                  MetaDataManager mmgr)

Convenience method to return if an array field has the elements stored into the table of the field as a single (BLOB) column.

Parameters:

fmd - MetaData for the field

mmgr - MetaData manager

Returns:

Whether the elements are stored in a single column

mapHasSerialisedKeysAndValues

public static boolean mapHasSerialisedKeysAndValues(AbstractMemberMetaData fmd)

Convenience method to return if a map field has the keys/values serialised. This is really for use within an RDBMS context.

Parameters:

fmd - MetaData for the field

Returns:

Whether the keys and values are serialised (either explicitly or implicitly)

attachCopyElements

public static boolean attachCopyElements(ObjectProvider ownerOP,
                                         Collection scoColl,
                                         Collection detachedElements,
                                         boolean elementsWithoutId)

Convenience method for use by Collection/Set/HashSet attachCopy methods to add any new elements (added whilst detached) to the collection.

Parameters:

ownerOP - Owner ObjectProvider

scoColl - The current (attached) SCO collection

detachedElements - The collection of (detached) elements that we're merging

elementsWithoutId - Whether the elements have no identity

Returns:

If the Collection was updated

attachCopyForCollection

public static void attachCopyForCollection(ObjectProvider ownerOP,
                                           Object[] detachedElements,
                                           Collection attached,
                                           boolean elementsWithoutIdentity)

Method to return an attached copy of the passed (detached) value. The returned attached copy is a SCO wrapper. Goes through the existing elements in the store for this owner field and removes ones no longer present, and adds new elements. All elements in the (detached) value are attached.

Parameters:

ownerOP - ObjectProvider for the owning object with the collection

detachedElements - The detached elements in the collection

attached - Collection to add the attached copies to

elementsWithoutIdentity - Whether the elements have their own identity

attachCopyForMap

public static void attachCopyForMap(ObjectProvider ownerOP,
                                    Set detachedEntries,
                                    Map attached,
                                    boolean keysWithoutIdentity,
                                    boolean valuesWithoutIdentity)

Method to return an attached copy of the passed (detached) value. The returned attached copy is a SCO wrapper. Goes through the existing elements in the store for this owner field and removes ones no longer present, and adds new elements. All elements in the (detached) value are attached.

Parameters:

ownerOP - ObjectProvider for the owning object with the map

detachedEntries - The detached entries in the map

attached - Map to add the attached copies to

keysWithoutIdentity - Whether the keys have their own identity

valuesWithoutIdentity - Whether the values have their own identity

updateCollectionWithCollection

public static boolean updateCollectionWithCollection(ApiAdapter api,
                                                     Collection coll,
                                                     Collection elements)

Convenience method to update a Collection to match the provided elements.

Parameters:

api - Api adapter

coll - The collection to update

elements - The new collection of elements that we need to match

Returns:

Whether the collection was updated

updateListWithListElements

public static boolean updateListWithListElements(List list,
                                                 List elements)

Convenience method for use by List attachCopy methods to update the passed (attached) list using the (attached) list elements passed.

Parameters:

list - The current (attached) list

elements - The list of (attached) elements needed.

Returns:

If the List was updated

updateMapWithMapKeysValues

public static boolean updateMapWithMapKeysValues(ApiAdapter api,
                                                 Map map,
                                                 Map keysValues)

Convenience method for use by Map attachCopy methods to update the passed (attached) map using the (attached) map keys/values passed.

Parameters:

api - Api adapter

map - The current (attached) map

keysValues - The keys/values required

Returns:

If the map was updated

populateMapDelegateWithStoreData

public static void populateMapDelegateWithStoreData(Map delegate,
                                                    MapStore store,
                                                    ObjectProvider ownerOP)

Convenience method to populate the passed delegate Map with the keys/values from the associated Store.

The issue here is that we need to load the keys and values in as few calls as possible. The method employed here reads in the keys (if persistable), then the values (if persistable), and then the "entries" (ids of keys and values) so we can associate the keys to the values.

Parameters:

delegate - The delegate

store - The Store

ownerOP - ObjectProvider of the owner of the map.

toArray

public static Object[] toArray(CollectionStore backingStore,
                               ObjectProvider op)

Returns true if this collection contains the specified element. More formally, returns true if and only if this collection contains at least one element it such that (o==null ? it==null : o.equals(it)).

This implementation iterates over the elements in the collection, checking each element in turn for equality with the specified element.

Parameters:

backingStore - the Store

op - the ObjectProvider

Returns:

true if this collection contains the specified element.

toArray

public static Object[] toArray(CollectionStore backingStore,
                               ObjectProvider op,
                               Object[] a)

Returns an array containing all of the elements in this collection;

Parameters:

backingStore - the Store

op - the ObjectProvider

a - the array into which the elements of the collection are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.

Returns:

an array containing the elements of the collection.

Throws:

NullPointerException - if the specified array is null.

ArrayStoreException - if the runtime type of the specified array is not a supertype of the runtime type of every element in this collection.

getComparator

public static Comparator getComparator(AbstractMemberMetaData mmd,
                                       ClassLoaderResolver clr)

Convenience method for creating a Comparator using extension metadata tags for the specified field. Uses the extension key "comparator-name".

Parameters:

mmd - The field that needs the comparator

clr - ClassLoader resolver

Returns:

The Comparator

detachForCollection

public static void detachForCollection(ObjectProvider ownerOP,
                                       Object[] elements,
                                       FetchPlanState state)

Convenience method to detach (recursively) all elements for a collection field. All elements that are persistable will be detached.

Parameters:

ownerOP - ObjectProvider for the owning object with the collection

elements - The elements in the collection

state - FetchPlan state

detachCopyForCollection

public static void detachCopyForCollection(ObjectProvider ownerOP,
                                           Object[] elements,
                                           FetchPlanState state,
                                           Collection detached)

Convenience method to detach copies (recursively) of all elements for a collection field. All elements that are persistable will be detached.

Parameters:

ownerOP - ObjectProvider for the owning object with the collection

elements - The elements in the collection

state - FetchPlan state

detached - Collection to add the detached copies to

attachForCollection

public static void attachForCollection(ObjectProvider ownerOP,
                                       Object[] elements,
                                       boolean elementsWithoutIdentity)

Convenience method to attach (recursively) all elements for a collection field. All elements that are persistable and not yet having an attached object will be attached.

Parameters:

ownerOP - ObjectProvider for the owning object with the collection

elements - The elements to process

elementsWithoutIdentity - Whether the elements have their own identity

detachForMap

public static void detachForMap(ObjectProvider ownerOP,
                                Set entries,
                                FetchPlanState state)

Convenience method to detach (recursively) all elements for a map field. All elements that are persistable will be detached.

Parameters:

ownerOP - ObjectProvider for the owning object with the map

entries - The entries in the map

state - FetchPlan state

detachCopyForMap

public static void detachCopyForMap(ObjectProvider ownerOP,
                                    Set entries,
                                    FetchPlanState state,
                                    Map detached)

Convenience method to detach copies (recursively) of all elements for a map field. All elements that are persistable will be detached.

Parameters:

ownerOP - ObjectProvider for the owning object with the map

entries - The entries in the map

state - FetchPlan state

detached - Map to add the detached copies to

attachForMap

public static void attachForMap(ObjectProvider ownerOP,
                                Set entries,
                                boolean keysWithoutIdentity,
                                boolean valuesWithoutIdentity)

Convenience method to attach (recursively) all keys/values for a map field. All keys/values that are persistable and don't already have an attached object will be attached.

Parameters:

ownerOP - ObjectProvider for the owning object with the map

entries - The entries in the map to process

keysWithoutIdentity - Whether the keys have their own identity

valuesWithoutIdentity - Whether the values have their own identity

validateObjectForWriting

public static boolean validateObjectForWriting(ExecutionContext ec,
                                               Object object,
                                               FieldValues fieldValues)

Method to check if an object to be stored in a SCO container is already persistent, or is managed by a different ExecutionContext. If not persistent, this call will persist it. If not yet flushed to the datastore this call will flush it.

Parameters:

ec - ExecutionContext

object - The object

fieldValues - Values for any fields when persisting (if the object needs persisting)

Returns:

Whether the object was persisted during this call

isListBased

public static boolean isListBased(Class type)

Return whether the supplied type (collection) is list based.

Parameters:

type - Type to check

Returns:

Whether it needs list ordering

getContainerInstanceType

public static Class getContainerInstanceType(Class declaredType,
                                             Boolean ordered)

Method to return the type to instantiate a container as. Returns the declared type unless it is not a concrete type, in which case returns ArrayList, HashSet, or HashMap.

Parameters:

declaredType - The declared type

ordered - Hint whether it needs ordering or not (null implies not)

Returns:

The type to instantiate as

detachAsWrapped

public static boolean detachAsWrapped(ObjectProvider ownerOP)

Convenience accessor for whether to detach SCO objects as wrapped.

Parameters:

ownerOP - ObjectProvider

Returns:

Whether to detach SCOs in wrapped form

useQueuedUpdate

public static boolean useQueuedUpdate(ObjectProvider op)

Convenience method to return if we should use a queued update for the current operation.

Parameters:

op - ObjectProvider

Returns:

Whether to use queued for this operation

hasDependentElement

public static boolean hasDependentElement(AbstractMemberMetaData mmd)

Method to return if the member is a collection/array with dependent element.

Parameters:

mmd - member metadata

Returns:

whether it has dependent element

hasDependentKey

public static boolean hasDependentKey(AbstractMemberMetaData mmd)

Method to return if the member is a map with dependent key.

Parameters:

mmd - member metadata

Returns:

whether it has dependent key

hasDependentValue

public static boolean hasDependentValue(AbstractMemberMetaData mmd)

Method to return if the member is a map with dependent value.

Parameters:

mmd - member metadata

Returns:

whether it has dependent value

collectionsAreEqual

public static boolean collectionsAreEqual(ApiAdapter api,
                                          Collection oldColl,
                                          Collection newColl)

Convenience method to return if two collections of persistent elements are equal.

Parameters:

api - ApiAdapter

oldColl - Old collection

newColl - New collection

Returns:

Whether they are equal

copyValue

public static Object copyValue(Object scoValue)

Copy a value if it's an *known* SCO type.

Parameters:

scoValue - An object that might be or not an SCO value

Returns:

Return a copy of the value if it's a know SCO type otherwise just return the value itself.

singleCollectionValue

public static Object singleCollectionValue(TypeManager typeManager,
                                           Object pc)