oracle.javatools.db.validators

Class DBObjectValidator<T extends DBObject>

java.lang.Object

oracle.javatools.db.refactoring.CascadeWorker<T>

oracle.javatools.db.validators.DBObjectValidator<T>

All Implemented Interfaces:

DBObjectValidator<T>

Direct Known Subclasses:

SchemaObjectValidator

public abstract class DBObjectValidator<T extends DBObject>
extends CascadeWorker<T>
implements DBObjectValidator<T>

Class responsible for validating an object definition in a DBObjectProvider.

Implementors use this class as a starting point for validation logic as validation of name, schema name (if appropriate) and duplication of name are provided by the base implementation.

To validate SchemaObject implementation, subclass SchemaObjectValidator

To implement property specific validation, the DBObjectValidator.PropertyValidator annotation can be used to mark methods as being the validation for a given property or properties. Such methods are automatically called when a call to validateObjectProperty(DBObject,DBObject,String) is made. They are all called when validateObject(DBObject,DBObject) is called.

For example to validate getMyProp/setMyProp on DBObject subclass MyObject:

 public class MyObjectValidator extends DBObjectValidator
 {
   public MyObjectValidator( DBObjectProvider pro )
   {
     super( pro );
   }

 

   @PropertyValidator( Property.myProp )
   public void validateMyProp( MyObject original, MyObject update )
   throws ValidationException
   {
     // TODO: validation logic here
   }
 }
 

This is now a complete validator implementation for MyObject with its one myProp property.

Since:

12

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DBObjectValidator.NamespaceType Types of namespace check that can be done when verifying that a given object's name is unqiue with the database.
protected static interface	DBObjectValidator.PropertyDependency Identifiers the property that a method that has a PropertyValidator is dependent on the value of other properties, and therefore the validation is also co-dependent.
protected static interface	DBObjectValidator.PropertyValidator Marks a method as being the validation logic for a given property, or properties.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DBObjectValidator(DBObjectProvider pro)

Method Summary

Methods

Modifier and Type	Method and Description
protected boolean	canHaveEmptyName() By default names cannot be empty (or null).
protected boolean	canRename() Default name validation is to allow rename on update.
protected void	checkInterrupt() Checks whether validation has been interrupted or cancelled and throws an exception to stop validation.
protected boolean	enforceChildNameUniqueInSchema(DBObject child) Deprecated. replaced by #getNamespaceType(DBObject).
protected T	findExistingObject(T object) Finds an existing object for the given object.
java.util.Collection<java.lang.String[]>	getDependencies(java.lang.String path)
DBObjectValidator.NamespaceType	getNamespaceType() Gets the type of namespace check that should be done by validateNameInUse(T).
boolean	initializeWithDefaultName() Tests whether a newly created object should be initialized with a default base name.
protected boolean	isChildOfPendingObject(DBObject obj) Tests whether the given object has a SchemaObject parent that is a pending (templated) object.
protected boolean	isPendingObject(SchemaObject obj) Tests whether the given SchemaObject is pending a template expansion.
protected java.util.Collection<java.lang.String>	listAlwaysValidProperties() Lists the properties that are always valid for this object.
protected void	logException(DBException dbe, java.util.logging.Level level) Logs the message for the given DBException to an appropriate level.
void	validateComment(T original, T update)
protected void	validateMissingPath(T original, T updated, java.lang.String property) When a path is validated, and the start of that path is missing the root object, this method is called to allow subclasses to customise validation for mandatory child properties when their parent is missing.
void	validateName(java.lang.String type, java.lang.String externalName) Validates that the given name is a valid identifier for the given object type.
protected void	validateName(T obj) Validates the given object's name to see if it is a legal identifier.
void	validateName(T original, T updated)
protected void	validateNameInUse(T object) Validates whether the given name is already in use.
protected void	validateNonNullableProperty(DBObject original, DBObject updated, java.lang.String propName) Validate that the property has not been updated from not null to null in an online database.
void	validateObject(T object) Tests whether the specified DBObject is valid for creation.
void	validateObject(T original, T updated) Determines whether the specified "updated" object is valid.
void	validateObjectProperty(T object, java.lang.String property) Tries to find an existing object for the given object and calls #validateObject(DBObject original, DBObject updated, Object property) This is final - all subclasses should implement #validateObject(DBObject original, DBObject updated, Object property)
void	validateObjectProperty(T original, T updated, java.lang.String property) Validates the given property for the given object.
protected void	validateOwnedObjects(DBObject[] children) Convenience method to call validateObject on the provider for each of the owned objects in the given array.
void	validateType(T original, T updated) Shouldn't be necessary but hey!
static void	validateUniqueNames(DBObject[] objs) Deprecated. with no replacement. Unique name validation is done by validateNameInUse.

Methods inherited from class oracle.javatools.db.refactoring.CascadeWorker

cascadeDelete, cascadeDelete, cascadePropertyChange, cascadeUpdate, getCascadeProperties, getLogger, getProvider, removeReference

Methods inherited from class java.lang.Object

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

Constructor Detail

DBObjectValidator

protected DBObjectValidator(DBObjectProvider pro)

Method Detail

checkInterrupt

protected void checkInterrupt()
                       throws ValidationCancelledException

Checks whether validation has been interrupted or cancelled and throws an exception to stop validation.

Throws:

ValidationCancelledException - if validation should stop

logException

protected void logException(DBException dbe,
                java.util.logging.Level level)
                     throws ValidationCancelledException

Logs the message for the given DBException to an appropriate level. If the DBException is a CancelledException this instead throws a ValidationCancelledException to propagate the cancel.

Use this method to log non-fatal exceptions ( e.g. resolveID() ) during validation so that a cancel/interrupt is not missed.

Parameters:

dbe - the exception to log

level - the level to log the exception's message at.

Throws:

ValidationCancelledException - if the DBException is a CancelledException.

validateObject

public final void validateObject(T object)
                          throws ValidationException

Tests whether the specified DBObject is valid for creation. If an existing object is found for the object, a NameInUseException will be thrown. Use validateObject(DBObject,DBObject) to validate that an object can be updated.

Specified by:

validateObject in interface DBObjectValidator<T extends DBObject>

Parameters:

object - the DBObject to validate

Throws:

ValidationException - if the object is not valid to create

validateObjectProperty

public final void validateObjectProperty(T object,
                          java.lang.String property)
                                  throws ValidationException

Tries to find an existing object for the given object and calls #validateObject(DBObject original, DBObject updated, Object property) This is final - all subclasses should implement #validateObject(DBObject original, DBObject updated, Object property)

Specified by:

validateObjectProperty in interface DBObjectValidator<T extends DBObject>

Parameters:

object - the DBObject to validate

property - the property identfier for the specific property to validate.

Throws:

ValidationException - if the object is not valid.

validateObject

public void validateObject(T original,
                  T updated)
                    throws ValidationException

Determines whether the specified "updated" object is valid. If original is null, this validates that the object can be created. If original is not null, this validates that the changes in updated are valid (as well as that updated is valid in general).

In general this should not need to be overridden. Validation should be complete by simply providing property specific validation methods. See the class javadoc for more details.

Specified by:

validateObject in interface DBObjectValidator<T extends DBObject>

Parameters:

object - the original DBObject (or null)

object - the updated DBObject to validate

Throws:

ValidationException - if the object is not valid.

validateObjectProperty

public void validateObjectProperty(T original,
                          T updated,
                          java.lang.String property)
                            throws ValidationException

Validates the given property for the given object. The default implementation calls the relevant method that has the DBObjectValidator.PropertyValidatorannotation for the requested property. If no such method is registered, a MissingValidatorExceptionis thrown.

Specified by:

validateObjectProperty in interface DBObjectValidator<T extends DBObject>

property - the property identfier for the specific property to validate.

Throws:

ValidationException - if the object is not valid.

validateMissingPath

protected void validateMissingPath(T original,
                       T updated,
                       java.lang.String property)
                            throws ValidationException

When a path is validated, and the start of that path is missing the root object, this method is called to allow subclasses to customise validation for mandatory child properties when their parent is missing.

Parameters:

original - the original object

updated - the updated object

property - the property path whose first property is null on the updated object.

Throws:

ValidationException

listAlwaysValidProperties

protected java.util.Collection<java.lang.String> listAlwaysValidProperties()

Lists the properties that are always valid for this object. Any bean property from the API that requires no validation should be returned from this method.

This should not be used to simply suppress warnings for properties that genuinely require validation. Add a validation method instead.

This will be checked after an annotated validation method cannot be found, so that if you subclass another validator that lists a property as "always valid" and you wish to add validation for it, your annotated validation method will still be called regardless of the contents of this collection.

In order to support heirarchical listing subclasses are expected to add to the super's return value. For example:

   protected Collection listAlwaysValidProperties()
   {
     final Collection retval = super.listAlwaysValidProperties();
     retval.add( Property.myValidProperty );
     return retval;
   }
 

validateType

public final void validateType(T original,
                T updated)
                        throws ValidationException

Shouldn't be necessary but hey!

Throws:

ValidationException

validateName

public final void validateName(T original,
                T updated)
                        throws ValidationException

Throws:

ValidationException

isChildOfPendingObject

protected final boolean isChildOfPendingObject(DBObject obj)

Tests whether the given object has a SchemaObject parent that is a pending (templated) object.

isPendingObject

protected final boolean isPendingObject(SchemaObject obj)

Tests whether the given SchemaObject is pending a template expansion.

validateName

protected void validateName(T obj)
                     throws InvalidNameException

Validates the given object's name to see if it is a legal identifier. Does not check for existing objects, so that it can be used for update as well as create.

This method should only be overridden to provide logic specific to an actual object. For generic name validation subclasses must override validateName(String,String), as that is also called by DBObjectProvider.validateName(String,String).

Parameters:

obj - the object whose name requires validation

Throws:

InvalidNameException

See Also:

validateNameInUse(DBObject)

validateName

public void validateName(java.lang.String type,
                java.lang.String externalName)
                  throws InvalidNameException

Validates that the given name is a valid identifier for the given object type. The name will be in external form (i.e. quoted if necessary). The type will be an object type that this validator is registered against in a provider.

The default implementation just calls DatabaseDescriptor.validateName(String,String) to validate invalid characters and reserved words. Override to include custom logic.

Parameters:

type - the object type

externalName - the name to validate

Throws:

InvalidNameException

validateNonNullableProperty

protected final void validateNonNullableProperty(DBObject original,
                               DBObject updated,
                               java.lang.String propName)
                                          throws ValidationException

Validate that the property has not been updated from not null to null in an online database.

Parameters:

original - the orginal object owning the property

updated - the updated object

propName - the name of the property

Throws:

ValidationException - if the property value has been updated from a non-null value to null and the context provider is an online database.

canHaveEmptyName

protected boolean canHaveEmptyName()

By default names cannot be empty (or null). If this method returns true then by default getNamespaceType will return DBObjectValidator.NamespaceType.NONE to indicate no name validation. To allow null names but also validate their uniqueness override both methods.

canRename

protected boolean canRename()

Default name validation is to allow rename on update.

validateNameInUse

protected void validateNameInUse(T object)
                          throws NameInUseException

Validates whether the given name is already in use. The object should have a valid Schema and Type for this to work.

Throws:

NameInUseException

findExistingObject

protected T findExistingObject(T object)
                                         throws ValidationException

Finds an existing object for the given object. Default implementation finds by ID.

Parameters:

object - the object to look for an existing version of

Returns:

the version of the given object that already exists in the provider.

Throws:

ValidationException - if the types of the given object and existing object don't match.

getNamespaceType

public DBObjectValidator.NamespaceType getNamespaceType()

Gets the type of namespace check that should be done by validateNameInUse(T). By default this will return TYPE unless canHaveEmptyName() returns true, then it will return NONE. Override as appropriate.

initializeWithDefaultName

public boolean initializeWithDefaultName()

Tests whether a newly created object should be initialized with a default base name. This isn't validation strictly, but it fits with the decisions canHaveEmptyName() and getNamespaceType().

Returns:

true if a new object created of the type validated by this object should be given a default name by the provider's DBObjectFactory.

enforceChildNameUniqueInSchema

@Deprecated
protected boolean enforceChildNameUniqueInSchema(DBObject child)

Deprecated. replaced by #getNamespaceType(DBObject).

validateComment

public void validateComment(T original,
                   T update)
                     throws ValidationException

Throws:

ValidationException

getDependencies

public java.util.Collection<java.lang.String[]> getDependencies(java.lang.String path)

validateOwnedObjects

protected final void validateOwnedObjects(DBObject[] children)
                                   throws ValidationException

Convenience method to call validateObject on the provider for each of the owned objects in the given array. All children will be validated and the error returned will be compound if more than one is invalid.

Parameters:

children - the children to validate

uniqueNames - whether to validate that the name of each child in the array is unique

Throws:

ValidationException - if any of the children is invalid

validateUniqueNames

@Deprecated
public static void validateUniqueNames(DBObject[] objs)
                                throws ValidationException

Deprecated. with no replacement. Unique name validation is done by validateNameInUse.

Throws:

ValidationException