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 a 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.

An example validator template:

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

   @PropertyValidator( Property.myProp1 )
   public void validateMyProp1( MyObject original, MyObject update )
   throws ValidationException
   {
     // TODO: validation logic for myProp1 here that will always run
   }

   @PropertyValidator( value = Property.myProp2,
                       level = ValidationLevel.FULL )
   public void validateMyProp2( MyObject original, MyObject update )
   throws ValidationException
   {
     // TODO: validation logic for myProp2 here that only runs if the
     // validation level is FULL
   }

   @PropertyValidator( Property.myProp3 )
   public void validateMyProp3( ValidationContext context )
   throws ValidationException
   {
     // TODO: validation logic for myProp3 here that always runs

     if( context.getLevel() == ValidationLevel.FULL )
     {
       // TODO: validation logic for myProp3 here that only runs if the
       // validation level is FULL
     }
   }
 }
 

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

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) Deprecated. no longer used, will be removed in future.
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.
protected boolean	shouldValidateProperty(ValidationContext<? extends T> context, java.lang.String propertyName) Tests whether validation should be fired for the given context.
void	validate(ValidationContext<? extends T> context) Performs the validation defined by the given context.
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) Validates that the name for the object is a valid identifier.
protected void	validateNameInUse(T object) Validates whether the given name is already in use.
protected void	validateNameInUse(T object, DBObjectValidator.NamespaceType nsType) 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) Deprecated. replaced by validate(ValidationContext)
void	validateObject(T original, T updated) Deprecated. replaced by validate(ValidationContext). Overriding this method disables all ValidationLevel awareness.
void	validateObjectProperty(T object, java.lang.String property) Deprecated. replaced by validate(ValidationContext)
void	validateObjectProperty(T original, T updated, java.lang.String property) Deprecated. replaced by validate(ValidationContext). Overriding this method disables all ValidationLevel awareness.
protected void	validateOwnedObjects(DBObject... children) Deprecated. use validateOwnedObjects(ValidationLevel,DBObject[]).
protected void	validateOwnedObjects(ValidationLevel level, DBObject... children) Convenience method to call validateObject on the provider for any owned objects.
void	validateType(T original, T updated) If original is not null, this validates that the objects are of the same type.
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

@Deprecated
public final void validateObject(T object)
                                      throws ValidationException

Deprecated. replaced by validate(ValidationContext)

Specified by:

validateObject in interface DBObjectValidator<T extends DBObject>

Throws:

ValidationException

validateObjectProperty

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

Deprecated. replaced by validate(ValidationContext)

Specified by:

validateObjectProperty in interface DBObjectValidator<T extends DBObject>

Throws:

ValidationException

shouldValidateProperty

protected boolean shouldValidateProperty(ValidationContext<? extends T> context,
                                         java.lang.String propertyName)

Tests whether validation should be fired for the given context. This can be used to skip particular parts of the validation.

Parameters:

context - the overall context for the validation being performed

propertyName - the specific property that is about to be validated from the context

Returns:

true for the property to be validated (i.e. the method annotated with the appropriate @PropertyValidator(propertyName) called).

validateObject

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

Deprecated. replaced by validate(ValidationContext). Overriding this method disables all ValidationLevel awareness.

Specified by:

validateObject in interface DBObjectValidator<T extends DBObject>

Throws:

ValidationException

validateObjectProperty

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

Deprecated. replaced by validate(ValidationContext). Overriding this method disables all ValidationLevel awareness.

Specified by:

validateObjectProperty in interface DBObjectValidator<T extends DBObject>

Throws:

ValidationException

validate

public final void validate(ValidationContext<? extends T> context)
                    throws ValidationException

Performs the validation defined by the given context. The context contains the objects to validate, and optionally defines the validation level and specific properties to validate.

If the context does not contain an original object, any name validation will include a check to see whether the name is already in use. The original object is also required for any validation logic specifically checking whether a property can be changed.

Parameters:

context - the validation context defining the required validation

Throws:

ValidationException - if the validation finds any errors with the objects being validated. ValidationExceptions can be be chained, so multiple errors can be reported.

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<String> listAlwaysValidProperties()
   {
     final Collection<String> retval = super.listAlwaysValidProperties();
     retval.add( Property.myValidProperty );
     return retval;
   }
 

validateType

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

If original is not null, this validates that the objects are of the same type.

Parameters:

original - the original object

updated - the updated object

Throws:

ValidationException - if original is not null and updated has a different type.

validateName

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

Validates that the name for the object is a valid identifier. If original is null, or the name has changed on updated this also checks that the name is unique within the appropriate namespace.

Parameters:

original - the original object

updated - the updated object

Throws:

ValidationException - if the name if invalid

See Also:

canRename(), validateName(DBObject), validateNameInUse(DBObject)

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

validateNameInUse

protected final void validateNameInUse(T object,
                                       DBObjectValidator.NamespaceType nsType)
                                throws NameInUseException

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

Parameters:

object - the object whose name should be checked

nsType - the namespace to check for uniqueness

Throws:

NameInUseException

findExistingObject

@Deprecated
protected T findExistingObject(T object)
                                    throws ValidationException

Deprecated. no longer used, will be removed in future.

Throws:

ValidationException

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

@Deprecated
protected final void validateOwnedObjects(DBObject... children)
                                               throws ValidationException

Deprecated. use validateOwnedObjects(ValidationLevel,DBObject[]).

Throws:

ValidationException

validateOwnedObjects

protected final void validateOwnedObjects(ValidationLevel level,
                                          DBObject... children)
                                   throws ValidationException

Convenience method to call validateObject on the provider for any owned objects. Every child will be validated (i.e. it won't stop at the first invalid child) and the error thrown will be compound if more than one is invalid.

Parameters:

level - the validation level to validate to

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