com.holonplatform.datastore.jdbc.composer

## Interface SQLCompositionContext

- All Superinterfaces:
    com.holonplatform.core.ExpressionResolver.ExpressionResolverHandler, com.holonplatform.core.ExpressionResolver.ExpressionResolverProvider, com.holonplatform.core.ExpressionResolver.ExpressionResolverSupport, com.holonplatform.core.ExpressionResolver.ResolutionContext, SQLContext
  All Known Subinterfaces:
    SQLStatementCompositionContext

      public interface SQLCompositionContext
      extends SQLContext, com.holonplatform.core.ExpressionResolver.ResolutionContext, com.holonplatform.core.ExpressionResolver.ExpressionResolverSupport

  SQL compostion context.

  Supports `ExpressionResolver`s to resolve SQL expressions and extends `ExpressionResolver.ResolutionContext`.

  Supports named parameters definitions, which can be added using `addNamedParameter(SQLParameter)`. The named parameters can be normalized as SQL statement parameters through the `prepareStatement(String)` method.

  SQL compostion contexts are hierarchical and provides methods to get the parent context and to create children using `childContext()`.

  Since:
    5.1.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `SQLCompositionContext.SQLStatementPreparationException` Runtime exception related to SQL statements preparation errors.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default <T> String` | `addNamedParameter(SQLParameter<T> parameter)` Convenience method to add a named parameter using current `SQLContextParametersHandler`.
    `SQLCompositionContext` | `childContext()` Create a new `SQLCompositionContext` as child of this context.
    `static SQLCompositionContext` | `create(SQLContext context)` Create a new default `SQLCompositionContext`.
    `static int` | `getContextSequence(SQLCompositionContext context, Class<? extends SQLCompositionContext> contextType)` Get the given `context` hierarchy sequence, where `0` is the sequence number of the root context.
    `SQLContextParametersHandler` | `getNamedParametersHandler()` Get the SQL named parameters handler.
    `Optional<SQLCompositionContext>` | `getParent()` Get the parent context, if available.
    `static Optional<SQLCompositionContext>` | `isSQLCompositionContext(com.holonplatform.core.ExpressionResolver.ResolutionContext context)` Checks if given `ExpressionResolver.ResolutionContext` is a `SQLCompositionContext`.
    `default Optional<SQLStatementCompositionContext>` | `isStatementCompositionContext()` Checks whether this context is a `SQLStatementCompositionContext`.
    `SQLStatement` | `prepareStatement(String sql)` Prepare given SQL statement, replacing named parameters with the default `?`
    `default <E extends com.holonplatform.core.Expression,R extends com.holonplatform.core.Expression> Optional<R>` | `resolve(E expression, Class<R> resolutionType)` Try to resolve given `expression` using current context resolvers to obtain a `resolutionType` type expression.
    `default <E extends com.holonplatform.core.Expression,R extends com.holonplatform.core.Expression> R` | `resolveOrFail(E expression, Class<R> resolutionType)` Resolve given `expression` using current context resolvers to obtain a `resolutionType` type expression.

    - ### Methods inherited from interface com.holonplatform.datastore.jdbc.composer.SQLContext

      `getDialect, getTypeConverter, getValueDeserializer, getValueSerializer, trace`

    - ### Methods inherited from interface com.holonplatform.core.ExpressionResolver.ExpressionResolverHandler

      `resolve`

    - ### Methods inherited from interface com.holonplatform.core.ExpressionResolver.ExpressionResolverProvider

      `getExpressionResolvers`

    - ### Methods inherited from interface com.holonplatform.core.ExpressionResolver.ExpressionResolverSupport

      `addExpressionResolver, addExpressionResolvers, removeExpressionResolver`

- - ### Method Detail

    - #### getParent

          Optional<SQLCompositionContext> getParent()

      Get the parent context, if available.
      Returns:
        Optional parent context

    - #### getNamedParametersHandler

          SQLContextParametersHandler getNamedParametersHandler()

      Get the SQL named parameters handler.
      Returns:
        the SQL named parameters handler

    - #### addNamedParameter

          default <T> String addNamedParameter(SQLParameter<T> parameter)

      Convenience method to add a named parameter using current `SQLContextParametersHandler`.
      Type Parameters:
        `T` - Parameter expression type
      Parameters:
        `parameter` - Parameter definition (not null)
      Returns:
        The generated parameter name

    - #### prepareStatement

          SQLStatement prepareStatement(String sql)

      Prepare given SQL statement, replacing named parameters with the default `?` parameter placeholder.
      Parameters:
        `sql` - The SQL statement to prepare (not null)
      Returns:
        An `SQLStatement` which provides the prepared SQL and the statement parameter definition in the right order according to the parameters placeholder index
      Throws:
        `SQLCompositionContext.SQLStatementPreparationException` - If an error occurred

    - #### resolve

          default <E extends com.holonplatform.core.Expression,R extends com.holonplatform.core.Expression> Optional<R> resolve(E expression,
                                                                                                                                Class<R> resolutionType)
                                                                                                                         throws com.holonplatform.core.Expression.InvalidExpressionException

      Try to resolve given `expression` using current context resolvers to obtain a `resolutionType` type expression.

      The resolved expression is validate using `Expression.validate()` before returning it to caller.

      Type Parameters:
        `E` - Expression type
        `R` - Resolution type
      Parameters:
        `expression` - Expression to resolve
        `resolutionType` - Expression type to obtain
      Returns:
        Resolved expression
      Throws:
        `com.holonplatform.core.Expression.InvalidExpressionException`

    - #### resolveOrFail

          default <E extends com.holonplatform.core.Expression,R extends com.holonplatform.core.Expression> R resolveOrFail(E expression,
                                                                                                                            Class<R> resolutionType)

      Resolve given `expression` using current context resolvers to obtain a `resolutionType` type expression. If no `ExpressionResolver` is available to resolve given expression, an `Expression.InvalidExpressionException` is thrown.

      The resolved expression is validate using `Expression.validate()` before returning it to caller.

      Type Parameters:
        `E` - Expression type
        `R` - Resolution type
      Parameters:
        `expression` - Expression to resolve
        `resolutionType` - Expression type to obtain
      Returns:
        Resolved expression
      Throws:
        `com.holonplatform.core.Expression.InvalidExpressionException` - If an error occurred during resolution, or if no `ExpressionResolver` is available to resolve given expression or if expression validation failed

    - #### childContext

          SQLCompositionContext childContext()

      Create a new `SQLCompositionContext` as child of this context. This context will be setted as parent of the new context.
      Returns:
        A new `SQLCompositionContext` with this context as parent

    - #### isStatementCompositionContext

          default Optional<SQLStatementCompositionContext> isStatementCompositionContext()

      Checks whether this context is a `SQLStatementCompositionContext`.
      Returns:
        If this context is a `SQLStatementCompositionContext` returns the context itself as `SQLStatementCompositionContext`, otherwise returns an empty Optional

    - #### create

          static SQLCompositionContext create(SQLContext context)

      Create a new default `SQLCompositionContext`.
      Parameters:
        `context` - SQL context to use (not null)
      Returns:
        A new `SQLCompositionContext`

    - #### isSQLCompositionContext

          static Optional<SQLCompositionContext> isSQLCompositionContext(com.holonplatform.core.ExpressionResolver.ResolutionContext context)

      Checks if given `ExpressionResolver.ResolutionContext` is a `SQLCompositionContext`.
      Parameters:
        `context` - The context to check
      Returns:
        if given context is a `SQLCompositionContext`, it is returned as a `SQLCompositionContext` type. Otherwise, an empty Optional is returned.

    - #### getContextSequence

          static int getContextSequence(SQLCompositionContext context,
                                        Class<? extends SQLCompositionContext> contextType)

      Get the given `context` hierarchy sequence, where `0` is the sequence number of the root context.
      Parameters:
        `context` - The context for which to obtain the sequence (not null)
        `contextType` - The context type to take into account to calculate the sequence
      Returns:
        Context sequence

Copyright © 2019 The Holon Platform. All rights reserved.