com.holonplatform.datastore.jpa.jpql.context

## Interface JPQLResolutionContext

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

      public interface JPQLResolutionContext
      extends JpaContext, com.holonplatform.core.ExpressionResolver.ResolutionContext, com.holonplatform.core.ExpressionResolver.ExpressionResolverSupport

  JPQL `ExpressionResolver.ResolutionContext`.

  Supports `ExpressionResolver`s to resolve JPQL expressions.

  Supports named parameters definitions, which can be added using `addNamedParameter(JPQLParameter)`. The named parameters can provided to a query definition using `setupQueryParameters(Query)`.

  JPQL 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` | `JPQLResolutionContext.JPQLStatementPreparationException` Runtime exception related to JPQL 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(JPQLParameter<T> parameter)` Convenience method to add a named parameter using current `JPQLContextParametersHandler`.
    `JPQLResolutionContext` | `childContext()` Create a new `JPQLResolutionContext` as child of this context.
    `static JPQLResolutionContext` | `create(JpaContext context)` Create a new default `JPQLResolutionContext`.
    `static int` | `getContextSequence(JPQLResolutionContext context, Class<? extends JPQLResolutionContext> contextType)` Get the given `context` hierarchy sequence, where `0` is the sequence number of the root context.
    `JPQLContextParametersHandler` | `getNamedParametersHandler()` Get the JPQL named parameters handler.
    `Optional<JPQLResolutionContext>` | `getParent()` Get the parent context, if available.
    `static Optional<JPQLResolutionContext>` | `isJPQLResolutionContext(com.holonplatform.core.ExpressionResolver.ResolutionContext context)` Checks if given `ExpressionResolver.ResolutionContext` is a `JPQLResolutionContext`.
    `default Optional<JPQLStatementResolutionContext>` | `isStatementCompositionContext()` Checks whether this context is a `JPQLStatementResolutionContext`.
    `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.
    `void` | `setupQueryParameters(javax.persistence.Query query)` Setup given `query` parameters using the named parameters defined in this context.

    - ### Methods inherited from interface com.holonplatform.datastore.jpa.context.JpaContext

      `getDialect, getEntityManagerFactory, getORMPlatform, getValueDeserializer, getValueSerializer, trace, traceOperation`

    - ### 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<JPQLResolutionContext> getParent()

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

    - #### getNamedParametersHandler

          JPQLContextParametersHandler getNamedParametersHandler()

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

    - #### addNamedParameter

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

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

    - #### setupQueryParameters

          void setupQueryParameters(javax.persistence.Query query)

      Setup given `query` parameters using the named parameters defined in this context.
      Parameters:
        `query` - The JPQL query to configure (not null)
      Throws:
        `JPQLResolutionContext.JPQLStatementPreparationException` - 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

          JPQLResolutionContext childContext()

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

    - #### isStatementCompositionContext

          default Optional<JPQLStatementResolutionContext> isStatementCompositionContext()

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

    - #### create

          static JPQLResolutionContext create(JpaContext context)

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

    - #### isJPQLResolutionContext

          static Optional<JPQLResolutionContext> isJPQLResolutionContext(com.holonplatform.core.ExpressionResolver.ResolutionContext context)

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

    - #### getContextSequence

          static int getContextSequence(JPQLResolutionContext context,
                                        Class<? extends JPQLResolutionContext> 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.