Class PropertyWrapper

  • All Implemented Interfaces:
    java.io.Serializable

    public class PropertyWrapper
    extends java.lang.Object
    implements java.io.Serializable
    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.

    See Also:
    Serialized Form
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String columnName()
      Gets the annotated column name.
      boolean equals​(java.lang.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.
      java.lang.Class<?> getAutoFillingClass()
      Returns the class provided to the AutoFillDuringQueryIfPossible annotation.
      java.lang.String[] getColumnAlias​(DBDefinition defn)
      The alias to the column for use in the select clause and during value retrieval
      java.util.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.
      java.lang.Class<?> getEnumCodeType()
      Gets the type of the code supplied by enum values.
      java.lang.Class<? extends java.lang.Enum<?>> getEnumType()
      Gets the enum type, or null if not appropriate
      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.
      java.lang.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.
      java.lang.Object getRawJavaTypeInstance()  
      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​(java.lang.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 isLargeObjectType()
      Returns true if the property wrapped is a Large Object column.
      boolean isNotPrimaryKey()
      Indicates whether this property is a primary key.
      boolean isPrimaryKey()
      Indicates whether this property is a primary key.
      boolean isReadable()
      Indicates whether the value of the property can be retrieved.
      boolean isRecursiveForeignKey()
      Returns TRUE if the property wrapped is a foreign key reference to the table supplied
      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.
      java.lang.String javaName()
      Gets the name of the java property, without the containing class name.
      java.lang.String qualifiedJavaName()
      Gets the fully qualified name of the underlying java property, including the fully qualified name of the containing class.
      java.lang.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.
      java.lang.Class<? extends DBRow> referencedClass()
      Gets the class referenced by this property, if this property is a foreign key.
      java.lang.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.
      java.lang.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​(java.lang.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.
      java.lang.String shortQualifiedJavaName()
      Gets the partially qualified name of the underlying java property, using the short-name of the containing class.
      java.lang.String tableName()
      Gets the annotated table name of the table this property belongs to.
      java.lang.String toString()
      Gets a string representation of the wrapped property, suitable for debugging and logging.
      java.lang.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
    • Method Detail

      • toString

        public java.lang.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 java.lang.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 java.lang.Object
        Returns:
        a hash code for this instance
      • equals

        public boolean equals​(java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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​(java.lang.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 java.lang.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 java.lang.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
      • isNotPrimaryKey

        public boolean isNotPrimaryKey()
        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 java.lang.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 java.lang.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 java.lang.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 java.lang.Class<? extends java.lang.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 java.lang.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:
        java.lang.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:
        java.lang.IllegalStateException - if not writable (you should have called isWritable() first)
        DBThrownByEndUserCodeException - if any user code throws an exception
      • rawJavaValue

        public java.lang.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:
        java.lang.IllegalStateException - if not readable (you should have called isReadable() first)
        DBThrownByEndUserCodeException - if any user code throws an exception
      • setRawJavaValue

        public void setRawJavaValue​(java.lang.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:
        java.lang.IllegalStateException - if not writable (you should have called isWritable() first)
        DBThrownByEndUserCodeException - if any user code throws an exception
      • getRawJavaType

        public java.lang.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.
      • getColumnExpression

        public DBExpression[] getColumnExpression()
                                           throws java.lang.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:
        java.lang.ClassCastException
      • getColumnAspects

        public java.util.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 java.lang.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.
      • isRecursiveForeignKey

        public boolean isRecursiveForeignKey()
        Returns TRUE if the property wrapped is a foreign key reference to the table supplied
        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 java.lang.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.
      • isLargeObjectType

        public boolean isLargeObjectType()
        Returns true if the property wrapped is a Large Object column.

        This generally means that the column is a BLOB, CLOB, TEXT, Java Object of other binary type.

        Spatial columns are special in that they can't generally be used in WHERE clauses.

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

        public java.lang.Object getRawJavaTypeInstance()