nz.co.gregs.dbvolution.internal.properties

Class PropertyWrapperDefinition

java.lang.Object

nz.co.gregs.dbvolution.internal.properties.PropertyWrapperDefinition

public class PropertyWrapperDefinition
extends Object

Abstracts a java field or bean-property 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 target objects. Instances of this class are not bound to specific target objects, nor are they bound to specific database definitions.

For binding to specific target objects and database definitions, use the PropertyWrapper class.

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 value() and setValue() 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 expensive to create and should be cached.

This class is thread-safe.

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PropertyWrapperDefinition.ColumnAspects

Field Summary

Fields

Modifier and Type	Field and Description
ArrayList<PropertyWrapperDefinition.ColumnAspects>	allColumnAspects

Method Summary

Methods

Modifier and Type	Method and Description
boolean	equals(Object obj) Equality of this property wrapper definition, based on the java property it wraps in a specific class.
List<PropertyWrapperDefinition.ColumnAspects>	getColumnAspects(DBDefinition defn, RowDefinition actualRow)
DBExpression[]	getColumnExpression() Support DBvolution at Patreon
Integer	getColumnIndex() Support DBvolution at Patreon
String	getColumnName() Gets the annotated column name.
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
QueryableDatatype<?>	getQueryableDatatype(RowDefinition target) 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.
RowDefinitionClassWrapper	getRowDefinitionClassWrapper() Gets the wrapper for the RowDefinition (DBRow or DBReport) subclass containing this property.
int	hashCode() Generates a hash-code of this property wrapper definition, based entirely on the java property it wraps.
boolean	isColumn() Indicates whether this property is a column.
boolean	isForeignKey() Indicates whether this property is a foreign key.
boolean	isInstanceOf(Class<? extends QueryableDatatype<?>> refType) Convenience method for testing the type.
boolean	isInstanceOfLargeObject() Convenience method for testing the type.
boolean	isPrimaryKey() Indicates whether this property is a primary key.
boolean	isReadable() Indicates whether the value of the property can be retrieved.
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(Object target) 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 identity 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(RowDefinition target, QueryableDatatype<?> value) Sets the DBvolution-centric value of the property.
void	setRawJavaValue(Object target, 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<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

Field Detail

allColumnAspects

public ArrayList<PropertyWrapperDefinition.ColumnAspects> allColumnAspects

Method Detail

toString

public String toString()

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

Support DBvolution at Patreon

Overrides:

toString in class Object

Returns:

a string representation of this object

hashCode

public int hashCode()

Generates a hash-code of this property wrapper definition, based entirely on the java property it wraps.

Support DBvolution at Patreon

Overrides:

hashCode in class Object

Returns:

a hash-code.

equals

public boolean equals(Object obj)

Equality of this property wrapper definition, based on the java property it wraps in a specific class. Two instances are identical if they wrap the same java property (field or bean-property) in the same class and the same class-loader.

Overrides:

equals in class Object

Parameters:

obj - the other object to compare to.

Support DBvolution at Patreon

Returns:

true if the two objects are equal, 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 getColumnName() to determine column name.

Support DBvolution at Patreon

Returns:

a String of the Java field name for 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 getColumnName() to determine column name.

Support DBvolution at Patreon

Returns:

a String of the short name of the declared class of 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 getColumnName() to determine column name.

Support DBvolution at Patreon

Returns:

a String of the full name of the class of this property

type

public Class<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 internal QueryableDatatype used by this property

isInstanceOf

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

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

Parameters:

refType - refType

Support DBvolution at Patreon

Returns:

TRUE if the supplied type is assignable from the internal QueryableDatatype, FALSE otherwise.

isInstanceOfLargeObject

public boolean isInstanceOfLargeObject()

Convenience method for testing the type. Equivalent to this.type().isAssignableFrom(DBLargeObject.class).

Support DBvolution at Patreon

Returns:

TRUE if a DBLargeObject is assignable from the internal QueryableDatatype, FALSE otherwise.

tableName

public String tableName()

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

Support DBvolution at Patreon

Returns:

a String of the table name containing this property.

getColumnName

public String getColumnName()

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 referenced column name if this property is a foreign key; null if not a foreign key

referencedPropertyDefinitionIdentity

public PropertyWrapperDefinition referencedPropertyDefinitionIdentity()

Gets identity 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 the 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 be 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 QueryableDatatype<?> getQueryableDatatype(RowDefinition target)

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.

Parameters:

target - object instance containing this property

Support DBvolution at Patreon

Returns:

the QueryableDatatype used internally.

Throws:

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

DBThrownByEndUserCodeException - if any user code throws an exception

setQueryableDatatype

public void setQueryableDatatype(RowDefinition target,
                        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:

target - object instance containing this property

value - 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(Object target)

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(nz.co.gregs.dbvolution.query.RowDefinition) and setQueryableDatatype(nz.co.gregs.dbvolution.query.RowDefinition, nz.co.gregs.dbvolution.datatypes.QueryableDatatype) methods.

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

Parameters:

target - object instance containing this property

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 target,
                   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(nz.co.gregs.dbvolution.query.RowDefinition) and setQueryableDatatype(nz.co.gregs.dbvolution.query.RowDefinition, nz.co.gregs.dbvolution.datatypes.QueryableDatatype) methods.

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

Parameters:

target - object instance containing this property

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(nz.co.gregs.dbvolution.query.RowDefinition) and setQueryableDatatype(nz.co.gregs.dbvolution.query.RowDefinition, nz.co.gregs.dbvolution.datatypes.QueryableDatatype) methods. Use the type() method to get the DBv-centric property type, after type conversion.

Support DBvolution at Patreon

Returns:

the declared class of the property

getRowDefinitionClassWrapper

public RowDefinitionClassWrapper getRowDefinitionClassWrapper()

Gets the wrapper for the RowDefinition (DBRow or DBReport) subclass containing this property.

Support DBvolution at Patreon

Returns:

the RowDefinitionClassWrapper representing the enclosing object of this property

getColumnExpression

public DBExpression[] getColumnExpression()

Support DBvolution at Patreon

Returns:

the columnExpression

getColumnAspects

public List<PropertyWrapperDefinition.ColumnAspects> getColumnAspects(DBDefinition defn,
                                                             RowDefinition actualRow)

getColumnIndex

public Integer getColumnIndex()

Support DBvolution at Patreon

Returns:

the columnIndex