oracle.javatools.db

Class AbstractDBObjectBuilder<T extends AbstractBuildableObject>

java.lang.Object

oracle.javatools.db.AbstractDBObjectBuilder<T>

All Implemented Interfaces:

DBObjectBuilder<T>

Direct Known Subclasses:

DerivedPropertyBuilder, DictionaryDBObjectBuilder

public abstract class AbstractDBObjectBuilder<T extends AbstractBuildableObject>
extends java.lang.Object
implements DBObjectBuilder<T>

Abstract implementation of DBObjectbuilder that provides core support for component building of objects.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	AbstractDBObjectBuilder.PropertyBuilder Annotation to mark methods that build components (properties) of a given object within this builder.

Field Summary

Fields inherited from interface oracle.javatools.db.DBObjectBuilder

BASE_COMPONENT_KEY

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractDBObjectBuilder(AbstractDBObjectProvider pro, java.lang.String type)

Method Summary

Methods

Modifier and Type	Method and Description
void	buildObject(T object) Requests that the specified object be completed.
void	buildObjectComponent(T object, java.lang.String key) Uses canBuildComponents() to work out whether this builder can build just the given (key) subcomponent.
protected boolean	canBuildComponents() Returns false by default.
boolean	canBuildEditableObject() Tests whether this builder does a complete build of the given object, or whether it is only used to create stub objects.
void	cancelCurrentBuild(T object) The default implementation sets an internal flagged that can be checked using #isCurrentBuildCancelled().
protected void	checkInterruptOrCancel(T object) Checks whether the current thread has been interrupted, or whether the current build has been explictly cancelled.
T	createObject(java.lang.String name, Schema schema, DBObjectID id) Requests the creation of a new SchemaObject of the type built by this DBObjectBuilder instance.
protected void	ensureComponent(T obj, java.lang.String key) Ensures that the given component has been built.
protected void	fillInObject(T object) Fills in the entire object definition - i.e.
protected boolean	fillInObjectComponent(T object, java.lang.String key) Builds the whole object by default.
protected boolean	fillInObjectComponentImpl(T object, java.lang.String prop) Actually fills in the given component on an object.
protected SystemObject	findObjectInProviderCache(DBObjectID id) Finds an existing object in the provider's object cache by id.
protected SystemObject	findObjectInProviderCache(java.lang.String type, Schema schema, java.lang.String name) Finds an existing object in the provider's object cache by name.
protected java.lang.String[]	getBuiltProperties(java.lang.String key) Gets the list of properties that will be built by the given component key.
java.util.Collection<java.lang.String>	getDerivedProperties(java.lang.String property) Gets the properties that are derived from the given property.
protected java.lang.String	getDerivedPropertySource(java.lang.String property) Gets the source property name for a derived property.
protected java.util.logging.Logger	getLogger()
protected java.lang.String	getObjectType()
protected AbstractDBObjectProvider	getProvider()
protected Schema	getSchema(java.lang.String name) Gets the schema with the given name from the underlying provider.
protected boolean	isBuildableProperty(java.lang.String key) If this returns false, it means that the given property should not trigger any kind of build on the object.
protected boolean	isBuiltOnFailure(T object, java.lang.String[] props, DBException dbe) Tests whether the given properties should be considered "built" by the object even though the build threw an exception.
protected boolean	isCurrentBuildCancelled(T object) Tests whether #cancelCurrentBuild() has been called during the current build.
protected void	markAsBuilt(T obj)
protected void	markAsBuilt(T object, java.lang.String... props) Marks the given properties as "built" on the buildable object.
protected boolean	needsBuilding(T obj, java.lang.String key) Returns true if the given subcomponent of the object hasn't been explicitly built yet.
boolean	needsBuilding(T obj, java.lang.String key, boolean checkBuilder) Checks whether the given component key on the given object needs building and optionally includes a check as to whether the object has been completely built already.
protected <D extends DBObject> D	newObject(java.lang.Class<? extends D> clz, DBObject parent, java.lang.String name) Creates a new object of the given class using the provider's object factory.
protected <D extends DBObject> D	newObject(java.lang.Class<? extends D> clz, java.lang.String name) Creates a new object of the given class using the provider's object factory.
protected void	registerObject(T object) Shared between buildObject and buildObjects to perform any post-build tasks that are needed (e.g.
protected void	replaceReferenceIDs(T object, java.util.Map<DBObjectID,DBObjectID> idMap) Directly replaces DBObejctID property values on the given object without building further properties on the object.
protected void	setBuilder(T obj) (Re)sets this builder as the DBObjectBuilder for the given object.
void	updateTimestamp(T object) Sets the timestamp of the given object if the underyling DBObjectProvider supports timestamping.
protected void	updateTimestamp(T object, boolean force)

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractDBObjectBuilder

protected AbstractDBObjectBuilder(AbstractDBObjectProvider pro,
                       java.lang.String type)

Method Detail

getObjectType

protected final java.lang.String getObjectType()

getProvider

protected final AbstractDBObjectProvider getProvider()

getLogger

protected java.util.logging.Logger getLogger()

canBuildEditableObject

public boolean canBuildEditableObject()

Description copied from interface: DBObjectBuilder

Tests whether this builder does a complete build of the given object, or whether it is only used to create stub objects. If the build of an object is not complete, it cannot be edited or transferred between providers because its definition is not sufficient to re-create it.

Specified by:

canBuildEditableObject in interface DBObjectBuilder<T extends AbstractBuildableObject>

cancelCurrentBuild

public void cancelCurrentBuild(T object)

The default implementation sets an internal flagged that can be checked using #isCurrentBuildCancelled(). If your builder implementation is designed to throw CancelledException internally you can periodically call #checkInterruptOrCancel() to achieve this check.

Specified by:

cancelCurrentBuild in interface DBObjectBuilder<T extends AbstractBuildableObject>

Parameters:

object - the object whose build should be cancelled.

isCurrentBuildCancelled

protected boolean isCurrentBuildCancelled(T object)

Tests whether #cancelCurrentBuild() has been called during the current build.

checkInterruptOrCancel

protected void checkInterruptOrCancel(T object)
                               throws CancelledException

Checks whether the current thread has been interrupted, or whether the current build has been explictly cancelled. If either is true a CancelledException is thrown.

Throws:

CancelledException - to abort the current build.

getSchema

protected final Schema getSchema(java.lang.String name)
                          throws DBException

Gets the schema with the given name from the underlying provider. Use in preference to getProvider().getSchema( name ) because it skips timestamping checking and is therefore faster.

Throws:

DBException

findObjectInProviderCache

protected final SystemObject findObjectInProviderCache(java.lang.String type,
                                     Schema schema,
                                     java.lang.String name)

Finds an existing object in the provider's object cache by name.

Parameters:

type - the type of object to find

schema - the owning schema (if the object is a SchemaObject)

name - the name of the object to find

Returns:

an existing object in the provider's cache, or null if a matching object doesn't already exist.

findObjectInProviderCache

protected final SystemObject findObjectInProviderCache(DBObjectID id)

Finds an existing object in the provider's object cache by id.

Parameters:

id - the id of the object to find

Returns:

an existing object in the provider's cache, or null if a matching object doesn't already exist.

newObject

protected final <D extends DBObject> D newObject(java.lang.Class<? extends D> clz,
                               java.lang.String name)

Creates a new object of the given class using the provider's object factory.

Parameters:

clz - the class of object to create.

name - the name to give the new object (can be null)

Returns:

a new object ready for building

newObject

protected final <D extends DBObject> D newObject(java.lang.Class<? extends D> clz,
                               DBObject parent,
                               java.lang.String name)

Creates a new object of the given class using the provider's object factory.

Parameters:

clz - the class of object to create.

parent - the parent of the new object (can be a Schema for SchemaObjects).

name - the name to give the new object (can be null)

Returns:

a new object ready for building

createObject

public T createObject(java.lang.String name,
             Schema schema,
             DBObjectID id)

Description copied from interface: DBObjectBuilder

Requests the creation of a new SchemaObject of the type built by this DBObjectBuilder instance.

Specified by:

createObject in interface DBObjectBuilder<T extends AbstractBuildableObject>

Parameters:

name - The name of the new object

schema - The schema containing the new object

id - the DBObjectID for the new object

Returns:

The newly created object

buildObject

public final void buildObject(T object)
                       throws DBException

Description copied from interface: DBObjectBuilder

Requests that the specified object be completed. The object should be completely initialized after the call completes.

Specified by:

buildObject in interface DBObjectBuilder<T extends AbstractBuildableObject>

Parameters:

object - The object needing building

Throws:

DBException - if an error occurs trying to build the object

fillInObject

protected void fillInObject(T object)
                     throws DBException

Fills in the entire object definition - i.e. builds all components. If the implementation doesn't support component building, this method must be overridden.

Parameters:

object - the object to fill in

Throws:

DBException

registerObject

protected void registerObject(T object)
                       throws DBException

Shared between buildObject and buildObjects to perform any post-build tasks that are needed (e.g. timestamping, registration with the object manager etc. Really we should try and do this for multiple objects at once as well but the timestamping work isn't easy to change that too so for now we'll stick with one at a time.

Throws:

DBException

updateTimestamp

public final void updateTimestamp(T object)
                           throws DBException

Sets the timestamp of the given object if the underyling DBObjectProvider supports timestamping.

Throws:

DBException

updateTimestamp

protected final void updateTimestamp(T object,
                   boolean force)
                              throws DBException

Throws:

DBException

needsBuilding

protected final boolean needsBuilding(T obj,
                    java.lang.String key)

Returns true if the given subcomponent of the object hasn't been explicitly built yet. If the object has been wholely built then this will confusingly return true because the object's builder is not checked.

Calling this is the same as needsBuilding( obj, key false ).

needsBuilding

public final boolean needsBuilding(T obj,
                    java.lang.String key,
                    boolean checkBuilder)

Checks whether the given component key on the given object needs building and optionally includes a check as to whether the object has been completely built already.

markAsBuilt

protected final void markAsBuilt(T obj)

setBuilder

protected final void setBuilder(T obj)

(Re)sets this builder as the DBObjectBuilder for the given object.

Parameters:

obj - the object to set "this" as the build for.

ensureComponent

protected final void ensureComponent(T obj,
                   java.lang.String key)
                              throws DBException

Ensures that the given component has been built. Use in a fillInObject implementation to ensure that dependent components are built before the component required.

Throws:

DBException

buildObjectComponent

public final void buildObjectComponent(T object,
                        java.lang.String key)
                                throws DBException

Uses canBuildComponents() to work out whether this builder can build just the given (key) subcomponent. If it can't the whole object is built.

Specified by:

buildObjectComponent in interface DBObjectBuilder<T extends AbstractBuildableObject>

Parameters:

object - the object that needs building

key - the component to build - in the majority of cases this will be a property name.

Throws:

DBException - if an error occurs trying to build the object

fillInObjectComponent

protected final boolean fillInObjectComponent(T object,
                            java.lang.String key)
                                       throws DBException

Builds the whole object by default. Override if canBuildComponents returns true to build the respective components. Defer to this implementation for unrecongnized keys.

Parameters:

object - the object to build

key - the property/component to build on the object

Returns:

false if there was nothing to build

Throws:

DBException

isBuiltOnFailure

protected boolean isBuiltOnFailure(T object,
                       java.lang.String[] props,
                       DBException dbe)

Tests whether the given properties should be considered "built" by the object even though the build threw an exception.

Parameters:

object - the object being built

props - the properties being built

dbe - the exception that the property building threw

Returns:

true if the properties should be marked as "built" even though the build method failed

markAsBuilt

protected final void markAsBuilt(T object,
               java.lang.String... props)

Marks the given properties as "built" on the buildable object.

Parameters:

object - the buildable object

props - the properties that should be marked as built.

fillInObjectComponentImpl

protected boolean fillInObjectComponentImpl(T object,
                                java.lang.String prop)
                                     throws DBException

Actually fills in the given component on an object.

Parameters:

object - the object to build

key - the component (i.e. property name) to build

Returns:

true if the component/property was successfully built

Throws:

CancelledException - if the build is cancelled, or interrupted.

DBException - if the build fails

canBuildComponents

protected boolean canBuildComponents()

Returns false by default. Override to enable building by component in this builder. Once enabled, component building is supported by the use of methods annotated with the AbstractDBObjectBuilder.PropertyBuilder annotation.

isBuildableProperty

protected boolean isBuildableProperty(java.lang.String key)

If this returns false, it means that the given property should not trigger any kind of build on the object.

Parameters:

key - the property key for component building

Returns:

false if no build should be performed

getBuiltProperties

protected java.lang.String[] getBuiltProperties(java.lang.String key)

Gets the list of properties that will be built by the given component key. Most build methods build more than one property, so this is used to notify the object which properties are in the process of being built, and then they get marked as built at the end.

Parameters:

key - the component key we're building

getDerivedProperties

public java.util.Collection<java.lang.String> getDerivedProperties(java.lang.String property)

Gets the properties that are derived from the given property.

Parameters:

property - the property to query

Returns:

the properties that are derived from the given property. Will return null if the property is not a derived property source property.

getDerivedPropertySource

protected java.lang.String getDerivedPropertySource(java.lang.String property)

Gets the source property name for a derived property.

Parameters:

property - the derived property

Returns:

the source property for the derived property, or null if the given property is not derived.

replaceReferenceIDs

protected void replaceReferenceIDs(T object,
                       java.util.Map<DBObjectID,DBObjectID> idMap)

Directly replaces DBObejctID property values on the given object without building further properties on the object. Use within a builder in preference to DBObject.replaceReferenceIDs to avoid unnecessary initialisation.

Parameters:

object - the object to replace ids on

idMap - the map of ids to replace