oracle.javatools.db
Class DBUtil

java.lang.Object
  oracle.javatools.db.DBUtil

All Implemented Interfaces:

java.util.Comparator<DBObject>

public class DBUtil
extends java.lang.Object
implements java.util.Comparator<DBObject>

Utility class associated with the DB package.

Since:

9.0.5

Nested Class Summary

static class

DBUtil.IDQuery When querying for reference IDs of an object this enum is used to define whether to query for different kinds of reference.

Constructor Summary

protected

DBUtil()

Method Summary

static boolean	areEqualIgnoreNullValues(java.util.Map map1, java.util.Map map2) Compares the given maps and assumes that a key with null value is the same as that key not being present.
int	compare(DBObject o1, DBObject o2) Compares the two objects, if they are both DBObjects.
static void	ensureDerivedPropertiesBuilt(SystemObject object, DBObjectProvider pro) INTERNAL ONLY - this is not a finished API yet.
static void	ensureObjectBuilt(SystemObject object) Ensures that the given object is loaded from its DBObjectProvider.
boolean	equals(java.lang.Object obj)
static DBObject	findChildInCopy(DBObject orig, DBObject copy, DBObject origChild) Given a child of an original object, finds the matching child of the copy using the TemporaryObjectIDs in the copy.
static <T extends DBObject> java.util.Collection<T>	findChildren(DBObject obj, java.lang.Class<T>... clz) Finds owned objects of the given class under the given object.
static java.util.Collection<DBObject>	findUsagesIn(DBObject used, DBObject searchRoot) Looks for usages of the given "used" object within the owned object heirachy of the given search object.
static java.lang.String	getDBObjectName(DBObjectID id) Gets the name of a DBObject from the DBObjectID, or the empty string if the DBObjectID can't be resolved.
static java.lang.String	getFullyQualifiedName(DBObject obj) Returns the fully qualified name of the given object by prepending the parent's name (if one exists) followed by a dot.
static java.lang.String	getFullyQualifiedName(DBObject obj, boolean incSchema) Returns the fully qualified name of the given object, optionally with the schema prepended.
static java.util.Comparator<DBObject>	getNameComparator() Returns a Comparator that will compare DBObjects by name first, and then by type.
static java.lang.Object	getOriginalID(DBObject dbo) Returns the Original Id of a copied DBObject.
static DBObject	getProviderDefinition(DBObject obj, DBObjectProvider pro, java.lang.String schemaName) Gets the definition for the given object from the provider by querying name and type in the given schema on the top (schema) level parent and then recursing the heirachy to find a match by name and type of the object given.
static DBObject	getProviderDefinition(ReferenceID refID, DBObjectProvider pro) Attempts to locate the referenced object in the given provider.
static <T extends DBObject> T	getProviderDefinition(T obj, DBObjectProvider pro) Gets the definition for the given object from the provider by querying name, schema and type.
static <T extends SchemaObject> T	getProviderDefinition(T obj, DBObjectProvider pro, java.lang.String schemaName) Gets the definition for the given object from the provider by querying name and type in the given schema.
static <T extends SystemObject> T[]	getProviderDefinitions(T[] objs, DBObjectProvider pro) Gets the definitions for the given objects from the database by querying name, schema and type.
static java.util.Collection<DBObjectID>	getReferenceIDs(DBObject obj, boolean recurse, DBUtil.IDQuery query, java.lang.String... types) Collects all the reference ID properties for the given object and its children and returns them after filtering as required.
static FKConstraint[]	getReferences(Constraint ucon, DBObjectProvider prov) Get the Foreign Keys which reference a unique constraint Given a contraint and an Offline provider, this method uses the constraint manager registered with the provider to build an array of the foreign keys which reference this contraint.
static Schema	getSchema(DBObject obj) Recurses up the tree of parents for this DBObject until it finds a SchemaObject and if found returns that SchemaObject's Schema.
static java.lang.String	getSchemaName(DBObjectID dbObjectID) Returns the name of the schema from a DBObjectID, or the empty string if the DBObjectID can't be resolved.
static SchemaObject	getSchemaObject(DBObject obj) Recurses up the tree of parents for this DBObject, and if the top object in the chain is a SchemaObject, it is returned.
static SystemObject	getSystemObject(DBObject obj) Recurses up the tree of parents for this DBObject, and if the top object in the chain is a SystemObject, it is returned.
static java.util.Map<DBObjectID,DBObjectID>	getTemporaryIDMap(DBObject[] objs)
static java.util.Comparator<DBObject>	getTypeComparator() Returns a Comparator that will compare DBObjects by type first, and then by name.
static java.lang.String	getUniqueName(java.util.Collection existing, java.lang.String base) Returns a unique name given the Collection of existing names from the base name given.
static java.lang.String	getUniqueName(java.util.Collection existing, java.lang.String base, boolean increment) Returns a unique name given the Collection of existing names from the base name given.
static DBObject	getUppermostParent(DBObject obj) Gets the top most object in the parent chain for the given object.
static DBObjectID	getUppermostParent(DBObjectID id) Gets the top most object in the parent chain for the given id.
int	hashCode()
static boolean	isCompoundName(java.lang.String name, java.lang.String quote) Return true if the name contains an unquoted '.'
static boolean	isDangling(DBObjectID refID) Returns true if it is passed a dangling reference.
static boolean	isInternalRef(DBObjectID ref, DBObject obj) Returns true if the given DBObjectID is referencing an object that is under the same parent heirachy as the given DBObject.
static <D extends DBObject> D	makeTemporaryCopy(D object) Makes a copy of the original object, with temporary reference ids.
static boolean	needsBuilding(SystemObject obj) Tests whether the given object needs building - i.e.
static boolean	needsDerivedPropertiesBuilding(SystemObject obj) INTERNAL ONLY - this is not a finished API yet.
static java.lang.String	quoteName(java.lang.String name, java.lang.String quote) Returns name quoted with the given quote.
static boolean	replaceReferenceIDs(DBObject obj, java.util.Map<DBObjectID,DBObjectID> idMap) Replaces the referencing IDs in the given object and all child objects with the given key/value mapping.
static DBObject	resolveInOtherProvider(BaseObjectID id, DBObjectProvider pro) Attempts to resolve the given ID in a provider that is not the id's own.
static void	resumeTimestampChecking(DBObjectProvider pro, java.lang.String timestampKey) Indicates to the given provider that the timestamp suspension for the given key has finished.
static java.util.Map<Schema,java.util.Collection<SystemObject>>	sortIntoSchemas(SystemObject... objs) Sorts the given list of objects into a map of Schema to objects.
static <T> T[]	stripNulls(T[] objs) Returns an array containing all the non-null elements from the given array.
static void	suspendTimestampChecking(DBObjectProvider pro, java.lang.String timestampKey) Usage must be proceeded immediatly by a try block, for which the finally contains a call to resumeTimestamps.
static void	updateObjectAndIDs(DBObject oldVersion, DBObject newVersion) Copys the newVersion to the old version and updates the oldVersion with the IDs from the newVersion.

Methods inherited from class java.lang.Object

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

Constructor Detail

DBUtil

protected DBUtil()

Method Detail

compare

public int compare(DBObject o1,
                   DBObject o2)

Compares the two objects, if they are both DBObjects.

Specified by:

compare in interface java.util.Comparator<DBObject>

See Also:

getNameComparator(), getTypeComparator()

equals

public boolean equals(java.lang.Object obj)

Specified by:

equals in interface java.util.Comparator<DBObject>

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

getTypeComparator

public static java.util.Comparator<DBObject> getTypeComparator()

Returns a Comparator that will compare DBObjects by type first, and then by name. (both alphabetically).

getNameComparator

public static java.util.Comparator<DBObject> getNameComparator()

Returns a Comparator that will compare DBObjects by name first, and then by type. (both alphabetically).

getTemporaryIDMap

public static java.util.Map<DBObjectID,DBObjectID> getTemporaryIDMap(DBObject[] objs)

makeTemporaryCopy

public static <D extends DBObject> D makeTemporaryCopy(D object)

Makes a copy of the original object, with temporary reference ids.

Parameters:

object - The original DBObject

Returns:

The copy of the object, with the same data, but using temporary object ids.

See Also:

DBObject#copyTo(java.lang.Object, boolean)

needsBuilding

public static boolean needsBuilding(SystemObject obj)

Tests whether the given object needs building - i.e. it supports lazy loading and is not fully loaded yet. Use in conjunction with ensureObjectBuilt(oracle.javatools.db.SystemObject) to build objects that need it and process any errors.

ensureObjectBuilt

public static void ensureObjectBuilt(SystemObject object)
                              throws DBException

Ensures that the given object is loaded from its DBObjectProvider. A UI operation for editing a SchemaObject should call this to ensure that any errors in loading the object are properly processed. Lazy loading generally swallows any DBException associated with object building so this method also allows utilities to properly display that error to the user.

Parameters:

object - the object to build

Throws:

DBException - thrown if an error is encountered building the object.

needsDerivedPropertiesBuilding

public static boolean needsDerivedPropertiesBuilding(SystemObject obj)

INTERNAL ONLY - this is not a finished API yet.

See Also:

ensureDerivedPropertiesBuilt(oracle.javatools.db.SystemObject, oracle.javatools.db.DBObjectProvider)

ensureDerivedPropertiesBuilt

public static void ensureDerivedPropertiesBuilt(SystemObject object,
                                                DBObjectProvider pro)
                                         throws DBException

INTERNAL ONLY - this is not a finished API yet.

Performs a "declarative build" which fills in any derived properties on the given object. Certain objects have a secondary build which builds derived information not directly associated with the dictionary (or persistence). For example this will attempt to build a View's SQLQuery (which will result in the building of any referenced Tables).

Parameters:

object - the object to ensure that all the derived properties are built on.

Throws:

DBException - if there is any error performing the build.

For internal use only. Application developers should not use this

this is not a finished API.

getReferenceIDs

public static java.util.Collection<DBObjectID> getReferenceIDs(DBObject obj,
                                                               boolean recurse,
                                                               DBUtil.IDQuery query,
                                                               java.lang.String... types)

Collects all the reference ID properties for the given object and its children and returns them after filtering as required.

Parameters:

obj - the object to query

recurse - whether to recurse to any child (owned) objects

query - the kind of reference to include

types - the types of object being referenced reqired (is used to filter by checking each id's type).

Returns:

all reference ID property values from the object and its children (may contain duplicates if the same object is referenced more than once).

isInternalRef

public static boolean isInternalRef(DBObjectID ref,
                                    DBObject obj)

Returns true if the given DBObjectID is referencing an object that is under the same parent heirachy as the given DBObject. The "parent heirachy" includes all objects under the uppermost DBObject.

Parameters:

ref - the reference to check

obj - the object to inspect the parent heirachy of

Returns:

true if the ref is referencing an object under the uppermost parent of the given object.

Since:

11

See Also:

getUppermostParent(DBObject), getUppermostParent(DBObjectID)

replaceReferenceIDs

public static boolean replaceReferenceIDs(DBObject obj,
                                          java.util.Map<DBObjectID,DBObjectID> idMap)

Replaces the referencing IDs in the given object and all child objects with the given key/value mapping.

Parameters:

obj - the object whose reference IDs (and children) are to be processed

idMap - the mappings of old to new IDs.

Returns:

true if anything was changed.

updateObjectAndIDs

public static void updateObjectAndIDs(DBObject oldVersion,
                                      DBObject newVersion)

Copys the newVersion to the old version and updates the oldVersion with the IDs from the newVersion. The result of which is that newVersion will be identical to oldVersion, including the IDs.

findChildren

public static <T extends DBObject> java.util.Collection<T> findChildren(DBObject obj,
                                                                        java.lang.Class<T>... clz)

Finds owned objects of the given class under the given object.

Type Parameters:

T - the object type we're looking for

Parameters:

obj - the object to look under for objects of the given type (including obj itself)

clz - the class(es) of object to find

Returns:

all found objects (order is not guarenteed or significant )

findChildInCopy

public static DBObject findChildInCopy(DBObject orig,
                                       DBObject copy,
                                       DBObject origChild)

Given a child of an original object, finds the matching child of the copy using the TemporaryObjectIDs in the copy. The copy is assumed to have been created using DBUtil.makeTemporaryCopy().

Parameters:

orig - The original object containing the child

copy - The copy of the parent

origChild - The child of the original

Returns:

the matchin child of the copy

getUniqueName

public static java.lang.String getUniqueName(java.util.Collection existing,
                                             java.lang.String base)

Returns a unique name given the Collection of existing names from the base name given. Assumes that any numbers on the end of the base are incrementable to create a unique name.

getUniqueName

public static java.lang.String getUniqueName(java.util.Collection existing,
                                             java.lang.String base,
                                             boolean increment)

Returns a unique name given the Collection of existing names from the base name given. The boolean parameter sets whether to increment any numbers at the end of base, or keep them as part of the name.

i.e.
if NAME1 exists and increment is true - base NAME1 -> NAME2
if NAME1 exists and increment is false - base NAME1 -> NAME1_1

getFullyQualifiedName

public static java.lang.String getFullyQualifiedName(DBObject obj)

Returns the fully qualified name of the given object by prepending the parent's name (if one exists) followed by a dot. Recurses up the heirachy. Does not include the schema.

getFullyQualifiedName

public static java.lang.String getFullyQualifiedName(DBObject obj,
                                                     boolean incSchema)

Returns the fully qualified name of the given object, optionally with the schema prepended.

getSchema

public static Schema getSchema(DBObject obj)

Recurses up the tree of parents for this DBObject until it finds a SchemaObject and if found returns that SchemaObject's Schema. This will return null for a Schema object itself as a Schema isn't owned by a Schema.

getSchemaObject

public static SchemaObject getSchemaObject(DBObject obj)

Recurses up the tree of parents for this DBObject, and if the top object in the chain is a SchemaObject, it is returned.

getSystemObject

public static SystemObject getSystemObject(DBObject obj)

Recurses up the tree of parents for this DBObject, and if the top object in the chain is a SystemObject, it is returned.

getUppermostParent

public static DBObject getUppermostParent(DBObject obj)

Gets the top most object in the parent chain for the given object. If the given object has no parent it is returned (as it is already at the top of the chain, even if that chain only has a length of one).

Parameters:

obj - the object to query

Returns:

the uppermost object in the parent heirachy for the given object

Since:

11

getUppermostParent

public static DBObjectID getUppermostParent(DBObjectID id)

Gets the top most object in the parent chain for the given id. If the given id has no parent it is returned (as it is already at the top of the chain, even if that chain only has a length of one).

Parameters:

id - the DBObjectID to query

Returns:

the uppermost id in the parent heirachy for the given id

Since:

11

sortIntoSchemas

public static java.util.Map<Schema,java.util.Collection<SystemObject>> sortIntoSchemas(SystemObject... objs)

Sorts the given list of objects into a map of Schema to objects.

getProviderDefinition

public static <T extends DBObject> T getProviderDefinition(T obj,
                                                           DBObjectProvider pro)
                                                throws DBException

Gets the definition for the given object from the provider by querying name, schema and type.

Parameters:

obj - the object to query in the provider by type, schema and name.

pro - the provider to get the definition from

Returns:

the definition, if any, the provider had that matches the object's name, type and schema.

Throws:

DBException

getProviderDefinition

public static DBObject getProviderDefinition(DBObject obj,
                                             DBObjectProvider pro,
                                             java.lang.String schemaName)
                                      throws DBException

Gets the definition for the given object from the provider by querying name and type in the given schema on the top (schema) level parent and then recursing the heirachy to find a match by name and type of the object given.

Parameters:

obj - the object to find in the provider

pro - the provider to get the definition from

schemName - the schema to search

Returns:

the definition, if any, the provider had that matches the object's name, type and schema.

Throws:

DBException

getProviderDefinition

public static <T extends SchemaObject> T getProviderDefinition(T obj,
                                                               DBObjectProvider pro,
                                                               java.lang.String schemaName)
                                                    throws DBException

Gets the definition for the given object from the provider by querying name and type in the given schema.

Parameters:

obj - the object to query in the provider by type, schema and name.

pro - the provider to get the definition from

schemaName - the name of the schema to be searched

Returns:

the definition, if any, the provider had that matches the object's name, type and schema.

Throws:

DBException

getProviderDefinitions

public static <T extends SystemObject> T[] getProviderDefinitions(T[] objs,
                                                                  DBObjectProvider pro)
                                                       throws DBException

Gets the definitions for the given objects from the database by querying name, schema and type.

Parameters:

objs - the objects whose definitions are to be retrieved from the provider

pro - the provider to get the definitions from

Returns:

the definitions that the provider has, if any. The array can have null elements in if the provider has no matching definition or if the corresponding element in the objs array was null.

Throws:

DBException

getProviderDefinition

public static DBObject getProviderDefinition(ReferenceID refID,
                                             DBObjectProvider pro)
                                      throws DBException

Attempts to locate the referenced object in the given provider.

Throws:

DBException

stripNulls

public static <T> T[] stripNulls(T[] objs)

Returns an array containing all the non-null elements from the given array.

quoteName

public static java.lang.String quoteName(java.lang.String name,
                                         java.lang.String quote)

Returns name quoted with the given quote. Need to escape any quote found in name. Assumes that doubling up works as an escape.

isCompoundName

public static boolean isCompoundName(java.lang.String name,
                                     java.lang.String quote)

Return true if the name contains an unquoted '.'

Parameters:

name -

Returns:

isDangling

public static boolean isDangling(DBObjectID refID)

Returns true if it is passed a dangling reference.

Parameters:

refID -

Returns:

true if param is a dangling reference

getOriginalID

public static java.lang.Object getOriginalID(DBObject dbo)

Returns the Original Id of a copied DBObject. Drill down throught the temporary Object Ids to the original ID. If this is null, return the object name.

Parameters:

a - DBObject

Returns:

either a DBObjectID or a String

findUsagesIn

public static java.util.Collection<DBObject> findUsagesIn(DBObject used,
                                                          DBObject searchRoot)

Looks for usages of the given "used" object within the owned object heirachy of the given search object.

Parameters:

used - the object to look for usages of

searchRoot - the object to search within

Returns:

a collection of all the DBObjects in the "searchRoot" owned objects heirachy that reference "used" by ID.

getReferences

public static FKConstraint[] getReferences(Constraint ucon,
                                           DBObjectProvider prov)

Get the Foreign Keys which reference a unique constraint Given a contraint and an Offline provider, this method uses the constraint manager registered with the provider to build an array of the foreign keys which reference this contraint.

getDBObjectName

public static java.lang.String getDBObjectName(DBObjectID id)

Gets the name of a DBObject from the DBObjectID, or the empty string if the DBObjectID can't be resolved.

Parameters:

id - the ID to inspect/resolve

Returns:

the name of the object the ID references

getSchemaName

public static java.lang.String getSchemaName(DBObjectID dbObjectID)

Returns the name of the schema from a DBObjectID, or the empty string if the DBObjectID can't be resolved. If the referenced object is not a SchemaObject this will not traverse the parent heirachy. It is designed as a test that the ID is infact referencing a SchemaObject.

Parameters:

dbObjectID - the ID to inspect/resolve

Returns:

the name of the schema for the object the ID references

resolveInOtherProvider

public static DBObject resolveInOtherProvider(BaseObjectID id,
                                              DBObjectProvider pro)
                                       throws DBException

Attempts to resolve the given ID in a provider that is not the id's own. This is useful when retaining references to objects post transfer. If some objects had been transfered to a different provider, and the ID of the original object stored, it is then useful to try and resolve the ID back in the original object's provider.

Importantly this attempts to resolve the ID. If the ID is a reference ID then you might really want to call getProviderDefinition(ReferenceID,DBObjectProvider) to look for a provider definition matching the given reference.

Parameters:

id - the id to attempt to resolve

pro - the provider (other than the id's own provider) to try and find a matching object in

Returns:

an object to match the given id in the other provider

Throws:

DBException

areEqualIgnoreNullValues

public static boolean areEqualIgnoreNullValues(java.util.Map map1,
                                               java.util.Map map2)

Compares the given maps and assumes that a key with null value is the same as that key not being present.

Returns:

whether the maps are equal assuming a null value = no key.

suspendTimestampChecking

public static void suspendTimestampChecking(DBObjectProvider pro,
                                            java.lang.String timestampKey)

Usage must be proceeded immediatly by a try block, for which the finally contains a call to resumeTimestamps.

e.g.

  final String key = "MyTimeConsumingOperation" + System.nanoTime();
  try
  {
    DBUtil.suspendTimestamps( pro, key );
    // perform my time consuming operation
  }
  finally
  {
    DBUtil.resumeTimestamps( pro, key );
  }
 

Parameters:

pro - the provider to suspend timestamping for

timestampKey - the key to suspect timestamping with (MUST be unique, and preferably meaningful).

resumeTimestampChecking

public static void resumeTimestampChecking(DBObjectProvider pro,
                                           java.lang.String timestampKey)

Indicates to the given provider that the timestamp suspension for the given key has finished.

Parameters:

pro - the provider timestamping was originally suspended on

timestampKey - the key for the suspension that is now over

See Also:

suspendTimestampChecking(oracle.javatools.db.DBObjectProvider, java.lang.String)