nz.co.gregs.dbvolution.internal.properties

Class PropertyWrapper

java.lang.Object

nz.co.gregs.dbvolution.internal.properties.PropertyWrapper

public class PropertyWrapper
extends Object

Abstracts a java field or bean-property on a target object as a DBvolution-centric property, which contains values from a specific column in a database table. Transparently handles all annotations associated with the property, including type adaption.

Provides access to the meta-data defined on a single java property of a class, and provides methods for reading and writing the value of the property on a single bound object, given a specified database definition.

DB properties can be seen to have the types and values in the table that follows. This class provides a virtual view over the property whereby the DBv-centric type and value are easily accessible via the getQueryableDatatype() and setQueryableDatatype(QueryableDatatype) methods.

• rawType/rawValue - the type and value actually stored on the declared java property
• dbvType/dbvValue - the type and value used within DBv (a QueryableDataType)
• databaseType/databaseValue - the type and value of the database column itself (this class doesn't deal with these)

Note: instances of this class are cheap to create and do not need to be cached.

This class is thread-safe.

This class is not serializable. References to it within serializable classes should be marked as transient.

Constructor Summary

Constructors

Constructor and Description
PropertyWrapper(RowDefinitionInstanceWrapper instanceWrapper, PropertyWrapperDefinition classProperty, RowDefinition target)

Method Summary

Methods

Modifier and Type	Method and Description
String	columnName() Gets the annotated column name.
boolean	equals(Object obj) Equality of this property wrapper definition, based on the java property it wraps in a specific class, plus the underlying object reference containing the wrapped property.
Class<?>	getAutoFillingClass() Returns the class provided to the AutoFillDuringQueryIfPossible annotation.
String[]	getColumnAlias(DBDefinition defn) The alias to the column for use in the select clause and during value retrieval
List<PropertyWrapperDefinition.ColumnAspects>	getColumnAspects(DBDefinition db) The names and aliases of this property as it will appear in a SELECT and WHERE clauses.
DBExpression[]	getColumnExpression() Returns the Column Expression, if any, defined on this property.
Class<?>	getEnumCodeType() Gets the type of the code supplied by enum values.
Class<? extends Enum<?>>	getEnumType() Gets the enum type, or null if not appropriate Support DBvolution at Patreon
PropertyWrapperDefinition	getPropertyWrapperDefinition() Gets the definition of the property, independent of any DBRow instance.
<A extends QueryableDatatype<?>> A	getQueryableDatatype() Gets the DBvolution-centric value of the property.
Class<?>	getRawJavaType() Gets the declared type of the property in the end-user's target object, prior to type conversion to the DBvolution-centric type.
RowDefinitionInstanceWrapper	getRowDefinitionInstanceWrapper() Gets the wrapper for the DBRow instance containing this property.
boolean	hasColumnExpression() Indicates whether this property has a ColumnExpression.
int	hashCode() Generates a hash-code of this property wrapper definition, based on the java property it wraps and the referenced target object.
boolean	isAutoFilling() Returns true if the property wrapped is an auto-filling field.
boolean	isAutoIncrement() Returns true if the property wrapped is an auto-incrementing column.
boolean	isColumn() Indicates whether this property is a column.
boolean	isForeignKey() Indicates whether this property is a foreign key.
boolean	isForeignKeyTo(DBRow table) Returns TRUE if the property wrapped is a foreign key reference to the table supplied
boolean	isInstanceOf(Class<? extends QueryableDatatype<?>> refType) Convenience method for testing the type of the QueryableDatatype.
boolean	isInstanceOfLargeObject() Convenience method for testing the type of the QueryableDatatype.
boolean	isPrimaryKey() Indicates whether this property is a primary key.
boolean	isReadable() Indicates whether the value of the property can be retrieved.
boolean	isSpatial2DType() Returns true if the property wrapped is a Spatial2D column.
boolean	isTypeAdapted() Indicates whether the property's type is adapted by an explicit or implicit type adaptor.
boolean	isWritable() Indicates whether the value of the property can be modified.
String	javaName() Gets the name of the java property, without the containing class name.
String	qualifiedJavaName() Gets the fully qualified name of the underlying java property, including the fully qualified name of the containing class.
Object	rawJavaValue() Gets the value of the declared property in the end-user's target object, prior to type conversion to the DBvolution-centric type.
Class<? extends DBRow>	referencedClass() Gets the class referenced by this property, if this property is a foreign key.
String	referencedColumnName() Gets the column name in the foreign table referenced by this property.
PropertyWrapperDefinition	referencedPropertyDefinitionIdentity() Gets information for the referenced property in the referenced table.
String	referencedTableName() Gets the table referenced by this property, if this property is a foreign key.
void	setQueryableDatatype(QueryableDatatype<?> value) Sets the DBvolution-centric value of the property.
void	setRawJavaValue(Object value) Set the value of the declared property in the end-user's target object, without type conversion to/from the DBvolution-centric type.
String	shortQualifiedJavaName() Gets the partially qualified name of the underlying java property, using the short-name of the containing class.
String	tableName() Gets the annotated table name of the table this property belongs to.
String	toString() Gets a string representation of the wrapped property, suitable for debugging and logging.
Class<? extends QueryableDatatype<?>>	type() Gets the DBvolution-centric type of the property.

Methods inherited from class java.lang.Object

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

Constructor Detail

PropertyWrapper

public PropertyWrapper(RowDefinitionInstanceWrapper instanceWrapper,
               PropertyWrapperDefinition classProperty,
               RowDefinition target)

Parameters:

instanceWrapper - instanceWrapper

classProperty - the class-level wrapper

target - the target object containing the given property

Method Detail

toString

public String toString()

Gets a string representation of the wrapped property, suitable for debugging and logging.

For example:
"DBInteger nz.co.mycompany.myproject.Vehicle.fkSpecOptionColour<fk_17> = [15241672]"

Support DBvolution at Patreon

Overrides:

toString in class Object

Returns:

a String representing this PropertyWrapper

hashCode

public int hashCode()

Generates a hash-code of this property wrapper definition, based on the java property it wraps and the referenced target object.

Support DBvolution at Patreon

Overrides:

hashCode in class Object

Returns:

a hash code for this instance

equals

public boolean equals(Object obj)

Equality of this property wrapper definition, based on the java property it wraps in a specific class, plus the underlying object reference containing the wrapped property.

Two instances are identical if they wrap the same java property (field or bean-property) in the same object instance (by object reference, rather than .equals() equality).

Overrides:

equals in class Object

Parameters:

obj - obj

Support DBvolution at Patreon

Returns:

TRUE if this PropertyWrapper wraps the same property on the same RowDefinition as the object supplied, FALSE otherwise

javaName

public String javaName()

Gets the name of the java property, without the containing class name. Mainly used within error messages. eg: "uid"

Use columnName() to determine column name.

Support DBvolution at Patreon

Returns:

a String of the declared field name of this property

shortQualifiedJavaName

public String shortQualifiedJavaName()

Gets the partially qualified name of the underlying java property, using the short-name of the containing class. Mainly used within logging and error messages. eg: "Customer.uid"

Use columnName() to determine column name.

Support DBvolution at Patreon

Returns:

a convenient String including the class name of the RowDefinition and the field name for this property

qualifiedJavaName

public String qualifiedJavaName()

Gets the fully qualified name of the underlying java property, including the fully qualified name of the containing class. Mainly used within logging and error messages. eg: "nz.co.mycompany.myproject.Customer.uid"

Use columnName() to determine column name.

Support DBvolution at Patreon

Returns:

the String of the full class name of the containing RowDefinition.

type

public Class<? extends QueryableDatatype<?>> type()

Gets the DBvolution-centric type of the property. If a type adaptor is present, then this is the type after conversion from the target object's actual property type.

Use getRawJavaType() in the rare case that you need to know the underlying java property type.

Support DBvolution at Patreon

Returns:

the Class of the QDT used internally to handle database values.

isInstanceOf

public boolean isInstanceOf(Class<? extends QueryableDatatype<?>> refType)

Convenience method for testing the type of the QueryableDatatype. Equivalent to refType.isAssignableFrom(this.type()).

Parameters:

refType - refType

Support DBvolution at Patreon

Returns:

TRUE if this property's internal QueryableDatatype is the similar to that of the supplied instance.

isInstanceOfLargeObject

public boolean isInstanceOfLargeObject()

Convenience method for testing the type of the QueryableDatatype. Equivalent to refType.isAssignableFrom(this.type()).

Support DBvolution at Patreon

Returns:

TRUE if this property's internal QueryableDatatype is the similar to that of the supplied instance.

tableName

public String tableName()

Gets the annotated table name of the table this property belongs to. Equivalent to calling getRowDefinitionInstanceWrapper().tableName().

Support DBvolution at Patreon

Returns:

a String of the table name for this property

columnName

public String columnName()

Gets the annotated column name. Applies defaulting if the DBColumn annotation is present but does not explicitly specify the column name.

If the DBColumn annotation is missing, this method returns null.

Support DBvolution at Patreon

Returns:

the column name, if specified explicitly or implicitly

isColumn

public boolean isColumn()

Indicates whether this property is a column.

Support DBvolution at Patreon

Returns:

true if this property is a column

isPrimaryKey

public boolean isPrimaryKey()

Indicates whether this property is a primary key.

Support DBvolution at Patreon

Returns:

true if this property is a primary key

isForeignKey

public boolean isForeignKey()

Indicates whether this property is a foreign key.

Support DBvolution at Patreon

Returns:

true if this property is a foreign key

referencedClass

public Class<? extends DBRow> referencedClass()

Gets the class referenced by this property, if this property is a foreign key.

Support DBvolution at Patreon

Returns:

the referenced class if this property is a foreign key; null if not a foreign key

referencedTableName

public String referencedTableName()

Gets the table referenced by this property, if this property is a foreign key.

Support DBvolution at Patreon

Returns:

the referenced table name if this property is a foreign key; null if not a foreign key

referencedColumnName

public String referencedColumnName()

Gets the column name in the foreign table referenced by this property. The referenced column is either explicitly indicated by use of the DBForeignKey.column() attribute, or it is implicitly the single primary key of the referenced table if the DBForeignKey.column() attribute is unset.

Support DBvolution at Patreon

Returns:

the non-null referenced column name if this property is a foreign key; null if not a foreign key

referencedPropertyDefinitionIdentity

public PropertyWrapperDefinition referencedPropertyDefinitionIdentity()

Gets information for the referenced property in the referenced table. The referenced property is either explicitly indicated by use of the DBForeignKey.column() attribute, or it is implicitly the single primary key of the referenced table.

Note that the property definition returned provides identity of the property only. It provides access to the property's: java name, column name, type, and identity information about the table it belongs to (ie: table name). Attempts to get or set its value or get the type adaptor instance will result in an internal exception.

Support DBvolution at Patreon

Returns:

the referenced property if this property is a foreign key; null if not a foreign key

getEnumType

public Class<? extends Enum<?>> getEnumType()

Gets the enum type, or null if not appropriate

Support DBvolution at Patreon

Returns:

the enum type, which may also implement DBEnumValue

getEnumCodeType

public Class<?> getEnumCodeType()

Gets the type of the code supplied by enum values. This is derived from the DBEnumValue implementation in the enum.

Support DBvolution at Patreon

Returns:

null if not known or not appropriate

isReadable

public boolean isReadable()

Indicates whether the value of the property can be retrieved. Bean properties which are missing a 'getter' can not be read, but may be able to be set.

Support DBvolution at Patreon

Returns:

TRUE if this property is readable, FALSE otherwise.

isWritable

public boolean isWritable()

Indicates whether the value of the property can be modified. Bean properties which are missing a 'setter' can not be written to, but may be able to be read.

Support DBvolution at Patreon

Returns:

TRUE if the property can set, FALSE otherwise.

isTypeAdapted

public boolean isTypeAdapted()

Indicates whether the property's type is adapted by an explicit or implicit type adaptor. (Note: at present there is no support for implicit type adaptors)

Support DBvolution at Patreon

Returns:

true if a type adaptor is being used

getQueryableDatatype

public <A extends QueryableDatatype<?>> A getQueryableDatatype()

Gets the DBvolution-centric value of the property. The value returned may have undergone type conversion from the target object's actual property type, if a type adaptor is present.

Use isReadable() beforehand to check whether the property can be read.

Type Parameters:

A - the QDT type

Support DBvolution at Patreon

Returns:

The queryableDatatype instance representing this property

Throws:

IllegalStateException - if not readable (you should have called isReadable() first)

DBThrownByEndUserCodeException - if any user code throws an exception

setQueryableDatatype

public void setQueryableDatatype(QueryableDatatype<?> value)

Sets the DBvolution-centric value of the property. The value set may have undergone type conversion to the target object's actual property type, if a type adaptor is present.

Use isWritable() beforehand to check whether the property can be modified.

Parameters:

value - value

Throws:

IllegalStateException - if not writable (you should have called isWritable() first)

DBThrownByEndUserCodeException - if any user code throws an exception

rawJavaValue

public Object rawJavaValue()

Gets the value of the declared property in the end-user's target object, prior to type conversion to the DBvolution-centric type.

In most cases you will not need to call this method, as type conversion is done transparently via the getQueryableDatatype() and setQueryableDatatype(QueryableDatatype) methods.

Use isReadable() beforehand to check whether the property can be read.

Support DBvolution at Patreon

Returns:

value

Throws:

IllegalStateException - if not readable (you should have called isReadable() first)

DBThrownByEndUserCodeException - if any user code throws an exception

setRawJavaValue

public void setRawJavaValue(Object value)

Set the value of the declared property in the end-user's target object, without type conversion to/from the DBvolution-centric type.

In most cases you will not need to call this method, as type conversion is done transparently via the getQueryableDatatype() and setQueryableDatatype(QueryableDatatype) methods.

Use isWritable() beforehand to check whether the property can be modified.

Parameters:

value - new value

Throws:

IllegalStateException - if not writable (you should have called isWritable() first)

DBThrownByEndUserCodeException - if any user code throws an exception

getRawJavaType

public Class<?> getRawJavaType()

Gets the declared type of the property in the end-user's target object, prior to type conversion to the DBvolution-centric type.

In most cases you will not need to call this method, as type conversion is done transparently via the getQueryableDatatype() and setQueryableDatatype(QueryableDatatype) methods. Use the type() method to get the DBv-centric property type, after type conversion.

Support DBvolution at Patreon

Returns:

the declared Java class of the property.

getPropertyWrapperDefinition

public PropertyWrapperDefinition getPropertyWrapperDefinition()

Gets the definition of the property, independent of any DBRow instance.

Support DBvolution at Patreon

Returns:

the propertyDefinition

getRowDefinitionInstanceWrapper

public RowDefinitionInstanceWrapper getRowDefinitionInstanceWrapper()

Gets the wrapper for the DBRow instance containing this property.

Support DBvolution at Patreon

Returns:

the RowDefinitionInstanceWrapper for this property.

hasColumnExpression

public boolean hasColumnExpression()

Indicates whether this property has a ColumnExpression.

Column expressions are derived values created with DBexpressions like StringExpression, NumberExpression, and BooleanExpression. The often involve database columns using the DBRow column methods or literal values using the, for instance, the StringExpression value method.

Support DBvolution at Patreon

Returns:

TRUE if this property uses an expression to generate a value, otherwise FALSE.

getColumnExpression

public DBExpression[] getColumnExpression()
                                   throws ClassCastException

Returns the Column Expression, if any, defined on this property.

Support DBvolution at Patreon

Returns:

the expression used by this property to generate values, or null.

Throws:

ClassCastException

getColumnAspects

public List<PropertyWrapperDefinition.ColumnAspects> getColumnAspects(DBDefinition db)

The names and aliases of this property as it will appear in a SELECT and WHERE clauses.

Multiple names and aliases are supported for QueryableDatatypes like DBNumberStatistics which retrieve several expressions at once.

Parameters:

db - db

Support DBvolution at Patreon

Returns:

A map of all the selectable name and column aliases for this property.

getColumnAlias

public String[] getColumnAlias(DBDefinition defn)

The alias to the column for use in the select clause and during value retrieval

Parameters:

defn - db

Support DBvolution at Patreon

Returns:

the column alias for this property.

isForeignKeyTo

public boolean isForeignKeyTo(DBRow table)

Returns TRUE if the property wrapped is a foreign key reference to the table supplied

Parameters:

table - table

Support DBvolution at Patreon

Returns:

TRUE if the property wrapped is a foreign key reference to the table supplied, otherwise FALSE.

isAutoIncrement

public boolean isAutoIncrement()

Returns true if the property wrapped is an auto-incrementing column.

This generally means that the column is a primary key. and definitely means you do not need to set the value of the column.

Support DBvolution at Patreon

Returns:

TRUE if the value of this column is provided by the database's auto-increment functionality, otherwise FALSE.

isSpatial2DType

public boolean isSpatial2DType()

Returns true if the property wrapped is a Spatial2D column.

This generally means that the column is a polygon, line, point, or other 2D geometry.

Spatial columns are special in that some databases need indexes to support them properly.

Support DBvolution at Patreon

Returns:

TRUE if the value of this column is a 2D geometry type, otherwise FALSE.

isAutoFilling

public boolean isAutoFilling()

Returns true if the property wrapped is an auto-filling field.

Support DBvolution at Patreon

Returns:

TRUE if the value of this column is to be automatically filled during queries if possible, otherwise FALSE.

getAutoFillingClass

public Class<?> getAutoFillingClass()

Returns the class provided to the AutoFillDuringQueryIfPossible annotation.

Support DBvolution at Patreon

Returns:

the class that should be auto-filled if it is present in the query.