Package nz.co.gregs.dbvolution.datatypes

Class QueryableDatatype<T>

    • Field Detail

      • SORT_UNSORTED

        public static java.lang.Boolean SORT_UNSORTED
        Used to indicate the the QDT should be sorted using the default ordering when using the setSortOrder(java.lang.Boolean) method.

      • SORT_ASCENDING

        public static final java.lang.Boolean SORT_ASCENDING
        Used to indicate the the QDT should be sorted so that the values run from A->Z or 0->9 when using the setSortOrder(java.lang.Boolean) method.

      • SORT_DESCENDING

        public static final java.lang.Boolean SORT_DESCENDING
        Used to indicate the the QDT should be sorted so that the values run from Z->A or 9->0 when using the setSortOrder(java.lang.Boolean) method.

    • Constructor Detail

      • QueryableDatatype

        protected QueryableDatatype()
        Default Constructor

      • QueryableDatatype

        protected QueryableDatatype​(T obj)
        Create a QueryableDatatype with the exact value provided.

        Equivalent to new QueryableDatatype().setValue(obj);

        Parameters:
        obj - the literal value of the QDT.

      • QueryableDatatype

        protected QueryableDatatype​(DBExpression[] columnExpression)
        Create a QDT with a permanent column expression.

        Use this method within a DBRow sub-class to create a column that uses an expression to create the value at query time.

        This is particularly useful for trimming strings or converting between types but also allows for complex arithmetic and transformations.

        Parameters:
        columnExpression - columnExpression

      • QueryableDatatype

        protected QueryableDatatype​(DBExpression columnExpression)
        Create a QDT with a permanent column expression.

        Use this method within a DBRow sub-class to create a column that uses an expression to create the value at query time.

        This is particularly useful for trimming strings or converting between types but also allows for complex arithmetic and transformations.

        Parameters:
        columnExpression - columnExpression

    • Method Detail

      • getQueryableDatatypeInstance

        public static <T extends QueryableDatatype<?>> T getQueryableDatatypeInstance​(java.lang.Class<T> requiredQueryableDatatype)
                                                                       throws java.lang.NoSuchMethodException,
                                                                              java.lang.InstantiationException,
                                                                              java.lang.IllegalAccessException,
                                                                              java.lang.IllegalArgumentException,
                                                                              java.lang.reflect.InvocationTargetException
        Factory method that creates a new QDT instance with the same class as the provided example.

        This method only provides a new blank instance. To copy the QDT and its fields, use copy().

        Type Parameters:
        T - the QDT type
        Parameters:
        requiredQueryableDatatype - requiredQueryableDatatype

        Support DBvolution at Patreon

        Returns:
        a new instance of the supplied QDT class
        Throws:
        java.lang.NoSuchMethodException - All QDTs need an accessible default constructor
        java.lang.InstantiationException - All QDTs need an accessible default constructor
        java.lang.IllegalAccessException - All QDTs need an accessible default constructor
        java.lang.reflect.InvocationTargetException - All QDTs need an accessible default constructor
        java.lang.IllegalArgumentException

      • getQueryableDatatypeInstance

        public static <T extends QueryableDatatype<?>> T getQueryableDatatypeInstance​(T requiredQueryableDatatype)
                                                                       throws java.lang.NoSuchMethodException,
                                                                              java.lang.InstantiationException,
                                                                              java.lang.IllegalAccessException,
                                                                              java.lang.IllegalArgumentException,
                                                                              java.lang.reflect.InvocationTargetException
        Factory method that creates a new QDT instance with the same class as the provided example.

        This method only provides a new blank instance. To copy the QDT and its fields, use copy().

        Type Parameters:
        T - the QDT type
        Parameters:
        requiredQueryableDatatype - requiredQueryableDatatype

        Support DBvolution at Patreon

        Returns:
        a new instance of the supplied QDT class
        Throws:
        java.lang.NoSuchMethodException - All QDTs need an accessible default constructor
        java.lang.InstantiationException - All QDTs need an accessible default constructor
        java.lang.IllegalAccessException - All QDTs need an accessible default constructor
        java.lang.reflect.InvocationTargetException - All QDTs need an accessible default constructor
        java.lang.IllegalArgumentException

      • getQueryableDatatypeForObject

        public static <S> QueryableDatatype<S> getQueryableDatatypeForObject​(S o)
        Returns an appropriate QueryableDatatype for the provided object.

        Provides the base QDTs for Integer, Number, String, Date, Byte[], Boolean, NumberResult, StringResult, DateResult, LargeObjectResult, BooleanResult and defaults everything else to DBJavaObject.

        Type Parameters:
        S - the base datatype returned by the QDT
        Parameters:
        o - the object to be encapsulated in the QDT

        Support DBvolution at Patreon

        Returns:
        a QDT that will provide good results for the provided object.

      • copy

        public QueryableDatatype<T> copy()
        Copies a QueryableDatatype and returns the copy. Used internally to provide immutability to DBOperator objects. The intention is that this method will provide a snapshot of the QDT at this moment in time and copy or clone any internal objects that might change. Subclasses should extend this method if they have fields that maintain the state of the QDT. Always use the super.copy() method first when overriding this method.

        Support DBvolution at Patreon

        Specified by:
        copy in interface DBExpression
        Returns:
        a complete copy of the QDT with all values set.

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • stringValue

        public java.lang.String stringValue()
        Returns the raw value as a String

        A database NULL is treated as an empty string, use isNull() to handle NULLs separately.

        Support DBvolution at Patreon

        Returns:
        the literal value as a String

      • removeConstraints

        public QueryableDatatype<T> removeConstraints()
        Remove the conditions, criteria, and operators applied to this QDT.

        After calling this method, this object will not cause a where clause to be generated in any subsequent queries.

        Support DBvolution at Patreon

        Returns:
        this instance.

      • negateOperator

        public void negateOperator()
        Negate the meaning of the comparison associated with this object.

        For instance, given thisQDT.permittedValue(1), thisQDT.negateOperator() will cause the operator to return everything other than 1.

        If this object has an operator defined for it, this method will invert the meaning of the operator by calling the operator's DBOperator.invertOperator(java.lang.Boolean) with "true".

      • getValue

        public T getValue()
        Gets the current literal value of this queryable data type. The returned value should be in the correct type as appropriate for the type of queryable data type.

        This method will return NULL if the QDT represents a database NULL OR the field is undefined. Use isNull() and isDefined() to differentiate the 2 states.

        Undefined QDTs represents a QDT that is not a field from the database. Undefined QDTs are similar to undefined DBRows

        Support DBvolution at Patreon

        Returns:
        the literal value, if defined, which may be null

      • getValue

        public T getValue​(T defaultValue)
        Gets the current literal value of this queryable data type or the default value specified if no values is set or available. The returned value should be in the correct type as appropriate for the type of queryable data type.

        This method will return NULL if the QDT represents a database NULL OR the field is undefined. Use isNull() and isDefined() to differentiate the 2 states.

        Undefined QDTs represents a QDT that is not a field from the database. Undefined QDTs are similar to undefined DBRows

        Support DBvolution at Patreon

        Parameters:
        defaultValue - the value to return when the actual value is not set or is null
        Returns:
        the literal value, if defined, which may be null

      • getValueWithDefaultValue

        public T getValueWithDefaultValue​(T valueIfNull)
        Gets the current literal value of this queryable data type or the value supplied if the value is NULL.

        This method will return NULL if the QDT represents a database NULL OR the field is undefined. Use isNull() and isDefined() to differentiate the 2 states.

        Undefined QDTs represents a QDT that is not a field from the database. Undefined QDTs are similar to undefined DBRows

        Support DBvolution at Patreon

        Parameters:
        valueIfNull - the value to use if the column contains NULL
        Returns:
        the literal value, if defined, which may be null

      • getPreviousValue

        public T getPreviousValue()
        Gets the previous literal value of this queryable data type. The returned value should be in the correct type as appropriate for the type of queryable data type.

        This method will return NULL if the QDT represents a database NULL OR the field is undefined OR the field is unchanged. Use isNull() and isDefined() to differentiate the 2 states.

        Undefined QDTs represents a QDT that is not a field from the database. Undefined QDTs are similar to undefined DBRows

        Support DBvolution at Patreon

        Returns:
        the literal value, if defined, which may be null

      • setValue

        public void setValue​(T newLiteralValue)
        Set the value of this QDT to the value provided.
        Parameters:
        newLiteralValue - the new value

      • setValue

        public void setValue​(QueryableDatatype<T> newLiteralValue)
        Set the value of this QDT to the value provided.
        Parameters:
        newLiteralValue - the new value

      • setValueFromStandardStringEncoding

        protected abstract void setValueFromStandardStringEncoding​(java.lang.String encodedValue)
        Set the value of this QDT to the value provided from the standard string encoding of this datatype.

        A good example of this method is DBBoolean.setValueFromStandardStringEncoding(java.lang.String) which translates the string encodings TRUE, YES, and 1 to true.

        Subclass writers should ensure that the method handles nulls correctly and throws an exception if an inappropriate value is supplied.

        Parameters:
        encodedValue - the value of the QDT in the appropriate encoding

      • setLiteralValue

        protected void setLiteralValue​(T newLiteralValue)
        Sets the literal value of this queryable data type. Replaces any assigned operator with an equals operator on the given value.
        Parameters:
        newLiteralValue - the literalValue to set

      • setUnchanged

        public void setUnchanged()
        Clear the changes to this QDT and remove the previous value as though this QDT had never had any value other than the current value.

      • setChanged

        public void setChanged()
        Used internally

      • setToNull

        protected DBOperator setToNull()
        Sets the value of this column to DBNull Also changes the operator to DBIsNullOperator for comparisons

        Support DBvolution at Patreon

        Returns:
        the DBOperator that will be used with this QDT

      • includingNulls

        public void includingNulls()
        Causes the underlying operator to explicitly include NULL values in it's processing.

        For instance: normally thisQDT.permittedValue(1) will only return fields with the value 1. Calling thisQDT.includingNulls() as well will cause the operator to return fields with value 1 and those with value NULL.

      • toSQLString

        public final java.lang.String toSQLString​(DBDefinition defn)
        Formats the literal value for use within an SQL statement.

        This is used internally to transform the Java object in to SQL format. You won't need to use it.

        Support DBvolution at Patreon

        Specified by:
        toSQLString in interface HasSQLString
        Parameters:
        defn - the DBDefinition
        Returns:
        the literal value as it would appear in an SQL statement i.e. {yada} => 'yada', {1} => 1 and {} => NULL

      • formatValueForSQLStatement

        protected abstract java.lang.String formatValueForSQLStatement​(DBDefinition db)
        Returns the value of the object formatted for the database This should be overridden in each subclass This method is called by toSQLString after checking for NULLs and should return a string representation of the object formatted for use within a SQL select, insert, update, or delete statement. For Example: DBString{yada} => 'yada' DBInteger{1234} => 123 DBDate{1/March/2013} => TO_DATE('20130301', 'YYYYMMDD')
        Parameters:
        db - db

        Support DBvolution at Patreon

        Returns:
        the literal value translated to a String ready to insert into an SQL statement

      • getOperator

        public DBOperator getOperator()

        Support DBvolution at Patreon

        Returns:
        the operator

      • setOperator

        public void setOperator​(DBOperator operator)
        Parameters:
        operator - the operator to set

      • hasChanged

        public boolean hasChanged()
        Indicates that the value of this QDT has been changed from its defined value.

        Support DBvolution at Patreon

        Returns:
        TRUE if the set value of this QDT has been changed since it was retrieved or updated, otherwise FALSE.

      • setFromResultSet

        public void setFromResultSet​(DBDefinition defn,
                             java.sql.ResultSet resultSet,
                             java.lang.String resultSetColumnName)
                      throws java.sql.SQLException
        Used internally to set the QDT to the value returned from the database.

        If you create a new QDT you should override this method. The default implementation in QueryableDatatype processes the ResultSet column as a String. You should follow the basic pattern but change ResultSet.getString(String) to the required ResultSet method and add any required post-processing.

        Note that most of the method is dedicated to detecting NULL values. This is very important as are the calls to setUnchanged() and setDefined(boolean)

        Parameters:
        defn - database
        resultSet - resultSet
        resultSetColumnName - resultSetColumnName
        Throws:
        java.sql.SQLException - Database exceptions may be thrown

      • getFromResultSet

        protected abstract T getFromResultSet​(DBDefinition database,
                                      java.sql.ResultSet resultSet,
                                      java.lang.String fullColumnName)
                               throws java.sql.SQLException
        Returns the correct object from the ResultSet for the QueryableDatatype to handle.
        Parameters:
        database - database
        resultSet - resultSet
        fullColumnName - fullColumnName

        Support DBvolution at Patreon

        Returns:
        the expected object from the ResultSet. 1 Database exceptions may be thrown
        Throws:
        java.sql.SQLException - java.sql.SQLException

      • isNull

        public boolean isNull()
        Indicates whether object is NULL within the database.

        Databases and Java both use the term NULL but for slightly different meanings.

        This method indicates whether the field represented by this object is NULL in the database sense.

        If you are trying to set a test for a query, use permittedOnlyNull or excludedOnlyNull instead

        Support DBvolution at Patreon

        Returns:
        TRUE if this object represents a NULL database value, otherwise FALSE

      • isNotNull

        public boolean isNotNull()
        Indicates whether object is NULL within the database.

        Databases and Java both use the term NULL but for slightly different meanings.

        This method indicates whether the field represented by this object is NULL in the database sense.

        If you are trying to set a test for a query, use permittedOnlyNull or excludedOnlyNull instead

        Support DBvolution at Patreon

        Returns:
        TRUE if this object represents a NULL database value, otherwise FALSE

      • getPreviousSQLValue

        public java.lang.String getPreviousSQLValue​(DBDefinition db)
        Returns the previous value of this field as an SQL formatted String.

        Used by DBActionList to generate revert action lists.

        Parameters:
        db - db

        Support DBvolution at Patreon

        Returns:
        the previous value of this field as an SQL formatted String

      • setSortOrderAscending

        public QueryableDatatype<T> setSortOrderAscending()
        Used to switch the direction of the column's sort order

        Support DBvolution at Patreon

        Returns:
        this object

      • setSortOrderDescending

        public QueryableDatatype<T> setSortOrderDescending()
        Used to switch the direction of the column's sort order

        Support DBvolution at Patreon

        Returns:
        this object

      • getSortOrder

        public java.lang.Boolean getSortOrder()
        Return the order in which this QDT will be sorted.

        Support DBvolution at Patreon

        Returns:
        SORT_DESCENDING if the column is to be sorted descending, SORT_ASCENDING if the column is to be sorted ascending otherwise SORT_UNSORTED.

      • clear

        public QueryableDatatype<T> clear()
        Remove the conditions, criteria, and operators applied to this QDT.

        After calling this method, this object will not cause a where clause to be generated in any subsequent queries.

        Synonym for removeConstraints().

        Support DBvolution at Patreon

        Returns:
        this instance

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • equals

        public boolean equals​(java.lang.Object otherObject)
        Overrides:
        equals in class java.lang.Object

      • isDefined

        public boolean isDefined()

        Support DBvolution at Patreon

        Returns:
        true if the value was retrieved from the database

      • setDefined

        protected void setDefined​(boolean defined)
        Parameters:
        defined - the undefined to set

      • getColumnExpression

        public final DBExpression[] getColumnExpression()
        Returns the expression underlying this QDT or null.

        When the QDT is created using an expression , this method makes the expression accessible.

        Support DBvolution at Patreon

        Returns:
        the underlying expression if there is one, or NULL otherwise.

      • hasColumnExpression

        public final boolean hasColumnExpression()
        Tests for the expression underlying this QDT or returns FALSE.

        When the QDT is created using an expression , this method makes the expression accessible.

        Support DBvolution at Patreon

        Returns:
        TRUE if there is a underlying expression, or FALSE otherwise.

      • getTablesInvolved

        public java.util.Set<DBRow> getTablesInvolved()
        Description copied from interface: DBExpression
        Returns a Set of the DBRow instances involved in this expression.

        Used by QueryGraph to plot the connections between tables and avoid cartesian joins.

        Support DBvolution at Patreon

        Specified by:
        getTablesInvolved in interface DBExpression
        Returns:
        a set of DBRow instances involved in this DBExpression.

      • hasBeenSet

        public boolean hasBeenSet()

        Support DBvolution at Patreon

        Indicates whether this column has had it's value set, either by the external program or DBV's internal processes.
        Returns:
        the setValue method has been called

      • getLiteralValue

        protected T getLiteralValue()

        Support DBvolution at Patreon

        Returns:
        the literalValue

      • setToNull

        protected DBOperator setToNull​(DBDefinition database)
        Used during setFromResultSet to set the QDT to a database NULL value.

        DBDatabase is supplied so that database-specific processing, such as Oracle empty strings, can be performed.

        Sets the value of this column to DBNull Also changes the operator to DBIsNullOperator for comparisons.

        The default implementation just calls setToNull()

        Parameters:
        database - database

        Support DBvolution at Patreon

        Returns:
        the DBOperator that will be used with this QDT

      • setChanged

        protected void setChanged​(boolean hasChanged)
        Used internally.
        Parameters:
        hasChanged - hasChanged

      • getPreviousValueAsQDT

        protected QueryableDatatype<T> getPreviousValueAsQDT()
        Used internally.

        Support DBvolution at Patreon

        Returns:
        the previous value of this QDT.

      • setPreviousValue

        protected void setPreviousValue​(QueryableDatatype<T> queryableDatatype)
        Used internally.
        Parameters:
        queryableDatatype - queryableDatatype

      • getPropertyWrapperDefinition

        protected PropertyWrapperDefinition getPropertyWrapperDefinition()
        Used internally.

        Support DBvolution at Patreon

        Returns:
        the PropertyWrapperDefinition

      • setColumnExpression

        protected final void setColumnExpression​(DBExpression... columnExpression)
        Used Internally.
        Parameters:
        columnExpression - the columnExpression to set

      • setValueToNull

        public void setValueToNull()
        Convenient synonym for setValue(null).

      • isPurelyFunctional

        public boolean isPurelyFunctional()
        Description copied from interface: DBExpression
        Indicates whether or not the expression includes table columns.

        Purely functional expressions use only in-built functions or literal values to produce results and do not require data from tables.

        Some databases, notably MS SQLServer, can not group purely functional expressions.

        Support DBvolution at Patreon

        Specified by:
        isPurelyFunctional in interface DBExpression
        Returns:
        TRUE if the expression does not access table data, otherwise FALSE.

      • formatColumnForSQLStatement

        public java.lang.String formatColumnForSQLStatement​(DBDefinition db,
                                                    java.lang.String formattedColumnName)
        Returns the column of the object formatted for the database.

        This method provides a route to transforming all calls to a column prior to use in SQL.

        See the implementation in DBStringTrimmed for an example.

        Parameters:
        db - db
        formattedColumnName - the name of the database column or similar expression ready to be used in an SQL excerpt

        Support DBvolution at Patreon

        Returns:
        the formatted column ready to be used in an SQL statement

      • getColumn

        public abstract ColumnProvider getColumn​(RowDefinition row)
                                  throws IncorrectRowProviderInstanceSuppliedException
        Creates a Column Provider suitable to this QDT.

        Creates a ColumnProvider object of the correct type for this QueryableDatatype, using this object and the provided row.

        Used internally to maintain the relationship between QDTs and their ColumnProvider equivalents.

        Parameters:
        row - the row from which to get the column provider
        Returns:
        a column object appropriate to this datatype based on the object and the row
        Throws:
        IncorrectRowProviderInstanceSuppliedException - if this object is not a field in the row.

      • setDefaultInsertValue

        public QueryableDatatype<T> setDefaultInsertValue​(T value)
        Set the value to be inserted when no value has been set, using setValue(...), for the QDT.

        The value is only used during the initial insert and does not effect the definition of the column within the database.

        Care should be taken when using this as some "obvious" uses are better handled using the expression version. In particular, setDefaultInsertValue(new Date()) is probably NOT what you want, setDefaultInsertValue(DateExpression.currentDate()) will produce a correct creation date value.

        Parameters:
        value - the value to use during insertion when no particular value has been specified.
        Returns:
        This QDT

      • setDefaultInsertValue

        protected QueryableDatatype<T> setDefaultInsertValue​(AnyResult<T> value)
        Set the value to be inserted when no value has been set, using setValue(...), for the QDT.

        The value is only used during the initial insert and does not effect the definition of the column within the database.

        Parameters:
        value - the value to use during insertion when no particular value has been specified.
        Returns:
        This QDT

      • setDefaultUpdateValue

        public QueryableDatatype<T> setDefaultUpdateValue​(T value)
        Set the value to be used during an update when no value has been set, using setValue(...), for the QDT.

        The value is only used during updates and does not effect the definition of the column within the database nor the initial value of the column.

        Care should be taken when using this as some "obvious" uses are better handled using the expression version. In particular, setDefaultUpdateValue(new Date()) is probably NOT what you want, setDefaultUpdateValue(DateExpression.currentDate()) will produce a correct update time value.

        Parameters:
        value - the value to use during update when no particular value has been specified.
        Returns:
        This QDT

      • setDefaultUpdateValue

        protected QueryableDatatype<T> setDefaultUpdateValue​(AnyResult<T> value)
        Set the value to be used during an update when no value has been set, using setValue(...), for the QDT.

        The value is only used during updates and does not effect the definition of the column within the database nor the initial value of the column.

        Parameters:
        value - the value to use during update when no particular value has been specified.
        Returns:
        This QDT

      • hasDefaultInsertValue

        public boolean hasDefaultInsertValue()
        Return true if the QDT has a default insert value defined.
        Returns:
        TRUE if a default has been defined for use during inserts.

      • getDefaultInsertValueSQLString

        public java.lang.String getDefaultInsertValueSQLString​(DBDefinition defn)
        Returns the value of the default insert value formatted by the DBDefinition provided.

        Probably not the method you are looking for.

        Parameters:
        defn - the DBDefinition
        Returns:
        the SQL version of the default value

      • hasDefaultUpdateValue

        public boolean hasDefaultUpdateValue()
        Return true if the QDT has a default update value defined.
        Returns:
        TRUE if a default update value has been set

      • getDefaultUpdateValueSQLString

        public java.lang.String getDefaultUpdateValueSQLString​(DBDefinition defn)
        Returns the value of the default update value formatted by the DBDefinition provided.

        Probably not the method you are looking for.

        Parameters:
        defn - the DBDefinition
        Returns:
        the default update value as SQL