Package de.calamanari.adl.sql

Interface QueryParameter

All Superinterfaces:
Serializable
All Known Implementing Classes:
DefaultQueryParameter
public interface QueryParameter extends Serializable
A QueryParameter encapsulates the action to correctly set a parameter on a prepared statement.

The contained value is already pre-validated, so this class timely decouples the moment when we align types and convert values from the moment where we actually set the parameters on a statement.

Each QueryParameter has a unique id(). This was introduced to keep the parameters of the PreparedStatement independent from the parameter order. The issue with relying on the order is that it is difficult to guarantee strict left-to-right production of parameters while building a statement.
And even worse: if you later put together larger text blocks to form the final statement, it may be impossible to keep the connection between the position of the question marks and the actual parameter to set. Thus, in an intermediate step we include parameter id-references ${id} in the expression's SQL-text.
Eventually (once all parameters are known), these temporary placeholders will be replaced with question marks to set the parameters safely on the the resulting PreparedStatement.

Author:
Karl Eilebrecht

  • Method Details

    • id

      String id()
      Returns:
      technical identifier for this parameter, must not be blank or contain any whitespace or curly braces or dollar signs (see Character.isLetterOrDigit(char)), no whitespace

    • createReference

      default String createReference()
      Returns:
      temporary placeholder to be used in an SQL-expression template: ${id}, see QueryParameter

    • adlSqlType

      AdlSqlType adlSqlType()
      Returns:
      a description of the target column's type

    • value

      Serializable value()
      Returns:
      the value to be set on a prepared statement, concrete type depends on QueryParameterCreator and requires a matching QueryParameterApplicator

    • operator

      de.calamanari.adl.irl.MatchOperator operator()
      Returns the operator currently being translated. This contextual information may influence the formatter in case of applyUnsafe(StringBuilder, int).
      Returns:
      the operator this parameter is used with, by default MatchOperator.EQUALS, not null

    • apply

      default void apply(PreparedStatement stmt, int parameterIndex) throws SQLException
      Sets the value of this parameter on the statement at the given index.

      This is the preferred (safe) methods to process the parameters of an SQL-statement without the risk of SQL-injection.

      Parameters:
      stmt -
      parameterIndex -
      Throws:
      SQLException - if the set operation on the prepared statement failed

    • applyUnsafe

      default void applyUnsafe(StringBuilder sb, int parameterIndex)
      Appends the value of the given parameter to an SQL script.

      Warning! As the name of this method states, using this method to compose plain SQL-queries is inherently unsafe and highly discouraged.

      Please also read: QueryParameterApplicator.applyUnsafe(StringBuilder, QueryParameter, int)

      Parameters:
      sb - to append the parameter value
      parameterIndex -
      Throws:
      de.calamanari.adl.cnv.tps.AdlFormattingException - if the formatting failed