org.datanucleus.sco
Class SCOUtils

java.lang.Object
  extended by org.datanucleus.sco.SCOUtils

public class SCOUtils
extends java.lang.Object

Collection of utilities for second class wrappers and objects.


Constructor Summary
SCOUtils()
           
 
Method Summary
static boolean allowNullsInContainer(boolean defaultValue, AbstractMemberMetaData fmd)
          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 attachAddNewElements(ApiAdapter api, java.util.Collection coll, java.util.Collection elements, 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(StateManager ownerSM, java.lang.Object[] detachedElements, java.util.Collection attached, boolean elementsWithoutIdentity)
          Method to return an attached copy of the passed (detached) value.
static void attachCopyForMap(StateManager ownerSM, java.util.Set detachedEntries, java.util.Map attached, boolean keysWithoutIdentity, boolean valuesWithoutIdentity)
          Method to return an attached copy of the passed (detached) value.
static void attachForCollection(StateManager ownerSM, java.lang.Object[] elements, boolean elementsWithoutIdentity)
          Convenience method to attach (recursively) all elements for a collection field.
static void attachForMap(StateManager ownerSM, java.util.Set entries, boolean keysWithoutIdentity, boolean valuesWithoutIdentity)
          Convenience method to attach (recursively) all keys/values for a map field.
static boolean attachRemoveDeletedElements(ApiAdapter api, java.util.Collection coll, java.util.Collection elements, boolean elementsWithoutId)
          Convenience method for use by Collection/Set/HashSet attachCopy methods to remove any no-longer-needed elements from the collection (for when elements are removed when detached).
static boolean collectionHasElementsWithoutIdentity(AbstractMemberMetaData fmd)
          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 detachAsWrapped(StateManager ownerSM)
          Convenience accessor for whether to detach SCO objects as wrapped.
static void detachCopyForCollection(StateManager ownerSM, java.lang.Object[] elements, FetchPlanState state, java.util.Collection detached)
          Convenience method to detach copies (recursively) of all elements for a collection field.
static void detachCopyForMap(StateManager ownerSM, java.util.Set entries, FetchPlanState state, java.util.Map detached)
          Convenience method to detach copies (recursively) of all elements for a map field.
static void detachForCollection(StateManager ownerSM, java.lang.Object[] elements, FetchPlanState state)
          Convenience method to detach (recursively) all elements for a collection field.
static void detachForMap(StateManager ownerSM, java.util.Set entries, FetchPlanState state)
          Convenience method to detach (recursively) all elements for a map field.
static java.util.Comparator getComparator(AbstractMemberMetaData fmd, ClassLoaderResolver clr)
          Convenience method for creating a Comparator using extension metadata tags for the specified field.
static java.lang.String getContainerInfoMessage(StateManager ownerSM, java.lang.String fieldName, SCOContainer cont, boolean useCache, boolean queued, boolean allowNulls, boolean lazyLoading)
          Utility to generate a message representing the SCO container wrapper and its capabilities.
static java.lang.Class getContainerInstanceType(java.lang.Class declaredType, java.lang.Boolean ordered)
          Method to return the type to instantiate a container as.
static java.lang.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 isListBased(java.lang.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(StateManager ownerSM, AbstractMemberMetaData fmd, java.lang.Class declaredType, java.lang.Class instantiatedType, java.lang.Object value, boolean forInsert, boolean forUpdate, boolean replaceField)
          Method to create a new SCO wrapper for a SCO type.
static void populateMapDelegateWithStoreData(java.util.Map delegate, MapStore store, StateManager ownerSM)
          Convenience method to populate the passed delegate Map with the keys/values from the associated Store.
static void refreshFetchPlanFieldsForCollection(StateManager ownerSM, java.lang.Object[] elements)
          Convenience method to refresh fetch plan fields for all elements for a collection field.
static void refreshFetchPlanFieldsForMap(StateManager ownerSM, java.util.Set entries)
          Convenience method to refresh fetch plan fields for all elements for a map field.
static java.lang.Object[] toArray(CollectionStore backingStore, StateManager sm)
          Returns true if this collection contains the specified element.
static java.lang.Object[] toArray(CollectionStore backingStore, StateManager sm, java.lang.Object[] a)
          Returns an array containing all of the elements in this collection;
static void updateCollectionWithCollection(ApiAdapter api, java.util.Collection coll, java.util.Collection newColl)
          Convenience method to update a collection to contain the elements in another collection.
static boolean updateCollectionWithCollectionElements(java.util.Collection coll, java.util.Collection elements)
          Convenience method for use by Collection/Set/HashSet attachCopy methods to update the passed (attached) collection using the (attached) elements passed.
static boolean updateListWithListElements(java.util.List list, java.util.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, java.util.Map map, java.util.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(StateManager ownerSM, java.lang.String fieldName)
          Accessor for whether the use lazy loading when caching the collection.
static boolean useContainerCache(StateManager ownerSM, java.lang.String fieldName)
          Utility to return whether or not to use the container cache for the collection/map for the passed StateManager SCO.
static boolean useContainerQueueing(StateManager ownerSM)
          Utility to return whether to use queueing of operations in the SCO container.
static boolean useQueuedUpdate(boolean queued, StateManager sm)
          Convenience method to return if we should use a queued update for the current operation.
static boolean validateObjectForWriting(ObjectManager om, java.lang.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 ObjectManager.
static void validateObjectsForWriting(ObjectManager om, java.lang.Object objects)
          Method to check if objects to be stored in a SCO container are already persistent, or are managed by a different ObjectManager.
 
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

newSCOInstance

public static SCO newSCOInstance(StateManager ownerSM,
                                 AbstractMemberMetaData fmd,
                                 java.lang.Class declaredType,
                                 java.lang.Class instantiatedType,
                                 java.lang.Object value,
                                 boolean forInsert,
                                 boolean forUpdate,
                                 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:
ownerSM - State Manager for the owning object
fmd - The Field MetaData for the related field.
declaredType - The class of the object
instantiatedType - Instantiated type for the field if known
value - The value we are wrapping if known
forInsert - Whether the SCO needs inserting in the datastore with this value
forUpdate - Whether the SCO needs updating in the datastore with this value
replaceField - Whether to replace the field with this value
Returns:
The Second-Class Object
Throws:
NucleusUserException - if an error occurred when creating the SCO instance

getContainerInfoMessage

public static java.lang.String getContainerInfoMessage(StateManager ownerSM,
                                                       java.lang.String fieldName,
                                                       SCOContainer cont,
                                                       boolean useCache,
                                                       boolean queued,
                                                       boolean allowNulls,
                                                       boolean lazyLoading)
Utility to generate a message representing the SCO container wrapper and its capabilities.

Parameters:
ownerSM - StateManager for the owner
fieldName - Field with the container
cont - The SCOContainer
useCache - Whether to use caching of values in the container
queued - Whether operations are queued in the wrapper
allowNulls - Whether to allow nulls
lazyLoading - Whether to use lazy loading in the wrapper
Returns:
The String

getSCOWrapperOptionsMessage

public static java.lang.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 fmd)
Utility to return whether or not to allow nulls in the container for the specified field. Uses the metadata extension "allow-nulls".

Parameters:
defaultValue - Default value for the container
fmd - MetaData for the field/property
Returns:
Whether to allow nulls

useContainerQueueing

public static boolean useContainerQueueing(StateManager ownerSM)
Utility to return whether to use queueing of operations in the SCO container.

Parameters:
ownerSM - The StateManager for the SCO field
Returns:
Whether to use queueing

useContainerCache

public static boolean useContainerCache(StateManager ownerSM,
                                        java.lang.String fieldName)
Utility to return whether or not to use the container cache for the collection/map for the passed StateManager SCO.

Parameters:
ownerSM - The StateManager for the SCO field
fieldName - Name of the field.
Returns:
Whether to use the cache.

useCachedLazyLoading

public static boolean useCachedLazyLoading(StateManager ownerSM,
                                           java.lang.String fieldName)
Accessor for whether the use lazy loading when caching the collection.

Parameters:
ownerSM - StateManager of the owning object
fieldName - Name of the collection/map field
Returns:
Whether to use lazy loading when caching the collection

collectionHasElementsWithoutIdentity

public static boolean collectionHasElementsWithoutIdentity(AbstractMemberMetaData fmd)
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:
fmd - 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)

updateCollectionWithCollection

public static void updateCollectionWithCollection(ApiAdapter api,
                                                  java.util.Collection coll,
                                                  java.util.Collection newColl)
Convenience method to update a collection to contain the elements in another collection. Performs the updates by calling the necessary add(), remove() methods just for the elements that have changed. Allows for some elements in one collection being attached and some being detached (so having same id, but different state)

Parameters:
api - API Adapter
coll - The collection to update
newColl - The new collection whose elements we need in "coll"

attachRemoveDeletedElements

public static boolean attachRemoveDeletedElements(ApiAdapter api,
                                                  java.util.Collection coll,
                                                  java.util.Collection elements,
                                                  boolean elementsWithoutId)
Convenience method for use by Collection/Set/HashSet attachCopy methods to remove any no-longer-needed elements from the collection (for when elements are removed when detached).

Parameters:
coll - The current (attached) collection
elements - The collection of (attached) elements needed.
elementsWithoutId - Whether the elements have no identity
Returns:
If the Collection was updated

attachAddNewElements

public static boolean attachAddNewElements(ApiAdapter api,
                                           java.util.Collection coll,
                                           java.util.Collection elements,
                                           boolean elementsWithoutId)
Convenience method for use by Collection/Set/HashSet attachCopy methods to add any new elements (added whilst detached) to the collection.

Parameters:
coll - The current (attached) collection
elements - The collection of (attached) elements needed.
elementsWithoutId - Whether the elements have no identity
Returns:
If the Collection was updated

updateCollectionWithCollectionElements

public static boolean updateCollectionWithCollectionElements(java.util.Collection coll,
                                                             java.util.Collection elements)
Convenience method for use by Collection/Set/HashSet attachCopy methods to update the passed (attached) collection using the (attached) elements passed.

Parameters:
coll - The current (attached) collection
elements - The collection of (attached) elements needed.
Returns:
If the Collection was updated

updateListWithListElements

public static boolean updateListWithListElements(java.util.List list,
                                                 java.util.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,
                                                 java.util.Map map,
                                                 java.util.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(java.util.Map delegate,
                                                    MapStore store,
                                                    StateManager ownerSM)
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 PersistenceCapable), then the values (if PersistenceCapable), 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
ownerSM - State Manager of the owner of the map.

toArray

public static java.lang.Object[] toArray(CollectionStore backingStore,
                                         StateManager sm)
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
sm - the StateManager
Returns:
true if this collection contains the specified element.

toArray

public static java.lang.Object[] toArray(CollectionStore backingStore,
                                         StateManager sm,
                                         java.lang.Object[] a)
Returns an array containing all of the elements in this collection;

Parameters:
backingStore - the Store
sm - the StateManager
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:
java.lang.NullPointerException - if the specified array is null.
java.lang.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 java.util.Comparator getComparator(AbstractMemberMetaData fmd,
                                                 ClassLoaderResolver clr)
Convenience method for creating a Comparator using extension metadata tags for the specified field. Uses the extension key "comparator-name".

Parameters:
fmd - The field that needs the comparator
clr - ClassLoader resolver
Returns:
The Comparator

refreshFetchPlanFieldsForCollection

public static void refreshFetchPlanFieldsForCollection(StateManager ownerSM,
                                                       java.lang.Object[] elements)
Convenience method to refresh fetch plan fields for all elements for a collection field. All elements that are PersistenceCapable will be made transient.

Parameters:
ownerSM - StateManager for the owning object with the collection
elements - The elements in the collection

refreshFetchPlanFieldsForMap

public static void refreshFetchPlanFieldsForMap(StateManager ownerSM,
                                                java.util.Set entries)
Convenience method to refresh fetch plan fields for all elements for a map field. All elements that are PersistenceCapable will be made transient.

Parameters:
ownerSM - StateManager for the owning object with the map
entries - The entries in the map

detachForCollection

public static void detachForCollection(StateManager ownerSM,
                                       java.lang.Object[] elements,
                                       FetchPlanState state)
Convenience method to detach (recursively) all elements for a collection field. All elements that are PersistenceCapable will be detached.

Parameters:
ownerSM - StateManager for the owning object with the collection
elements - The elements in the collection
state - FetchPlan state

detachCopyForCollection

public static void detachCopyForCollection(StateManager ownerSM,
                                           java.lang.Object[] elements,
                                           FetchPlanState state,
                                           java.util.Collection detached)
Convenience method to detach copies (recursively) of all elements for a collection field. All elements that are PersistenceCapable will be detached.

Parameters:
ownerSM - StateManager 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(StateManager ownerSM,
                                       java.lang.Object[] elements,
                                       boolean elementsWithoutIdentity)
Convenience method to attach (recursively) all elements for a collection field. All elements that are PersistenceCapable and not yet having an attached object will be attached.

Parameters:
ownerSM - StateManager for the owning object with the collection
elements - The elements to process
elementsWithoutIdentity - Whether the elements have their own identity

attachCopyForCollection

public static void attachCopyForCollection(StateManager ownerSM,
                                           java.lang.Object[] detachedElements,
                                           java.util.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:
ownerSM - StateManager 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

detachForMap

public static void detachForMap(StateManager ownerSM,
                                java.util.Set entries,
                                FetchPlanState state)
Convenience method to detach (recursively) all elements for a map field. All elements that are PersistenceCapable will be detached.

Parameters:
ownerSM - StateManager for the owning object with the map
entries - The entries in the map
state - FetchPlan state

detachCopyForMap

public static void detachCopyForMap(StateManager ownerSM,
                                    java.util.Set entries,
                                    FetchPlanState state,
                                    java.util.Map detached)
Convenience method to detach copies (recursively) of all elements for a map field. All elements that are PersistenceCapable will be detached.

Parameters:
ownerSM - StateManager 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(StateManager ownerSM,
                                java.util.Set entries,
                                boolean keysWithoutIdentity,
                                boolean valuesWithoutIdentity)
Convenience method to attach (recursively) all keys/values for a map field. All keys/values that are PersistenceCapable and don't already have an attached object will be attached.

Parameters:
ownerSM - StateManager 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

attachCopyForMap

public static void attachCopyForMap(StateManager ownerSM,
                                    java.util.Set detachedEntries,
                                    java.util.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:
ownerSM - StateManager 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

validateObjectForWriting

public static boolean validateObjectForWriting(ObjectManager om,
                                               java.lang.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 ObjectManager. If not persistent, this call will persist it. If not yet flushed to the datastore this call will flush it.

Parameters:
om - ObjectManager that we are using
object - The object
fieldValues - Values for any fields when persisting (if the object needs persisting)
Returns:
Whether the object was persisted during this call

validateObjectsForWriting

public static void validateObjectsForWriting(ObjectManager om,
                                             java.lang.Object objects)
Method to check if objects to be stored in a SCO container are already persistent, or are managed by a different ObjectManager. If not persistent, this call will persist them.

Parameters:
om - ObjectManager being used
objects - The objects (array, or Collection)

isListBased

public static boolean isListBased(java.lang.Class type)
Return whether the supplied type (collection) is list based.

Returns:
Whether it needs list ordering

getContainerInstanceType

public static java.lang.Class getContainerInstanceType(java.lang.Class declaredType,
                                                       java.lang.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(StateManager ownerSM)
Convenience accessor for whether to detach SCO objects as wrapped.

Parameters:
ownerSM - StateManager
Returns:
Whether to detach SCOs in wrapped form

useQueuedUpdate

public static boolean useQueuedUpdate(boolean queued,
                                      StateManager sm)
Convenience method to return if we should use a queued update for the current operation. If within a transaction, and using queueing in general, and not flushing then returns true.

Parameters:
queued - Whether supporting queued operations
sm - StateManager
Returns:
Whether to use queued for this operation


Copyright © 2010. All Rights Reserved.