Interface LimitHandler

All Known Implementing Classes:
AbstractLimitHandler, AbstractNoOffsetLimitHandler, AbstractSimpleLimitHandler, DB2LimitHandler, FetchLimitHandler, LegacyDB2LimitHandler, LimitLimitHandler, LimitOffsetLimitHandler, NoopLimitHandler, OffsetFetchLimitHandler, Oracle12LimitHandler, SQLServer2012LimitHandler, TopLimitHandler
@SPI({USE,IMPLEMENT,SUPPLY}) public interface LimitHandler

Dialect strategy for applying execution-time limit and offset to already-rendered SQL.

This contract is used for pagination requested through Query.setMaxResults(int) or Query.setFirstResult(int). It is distinct from PaginationRenderingSupport, which selects syntax while translating pagination already represented in the SQL AST.

Implementations should normally extend AbstractLimitHandler or one of its supported syntax-family subclasses. processSql(PaginationRequest) must be side-effect free: it returns rewritten SQL and explicit JDBC instructions instead of retaining request-specific binding state in the handler. A Dialect may return the same handler instance for its whole lifetime, so custom handlers must be safe for concurrent use.

Since:
8.0
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    default int
    parameterPositionStart(PaginationRequest request)
    Determine the one-based position of the first original query parameter after any pagination parameters inserted at the beginning of the SQL.
    PaginationResult
    processSql(PaginationRequest request)
    Apply pagination to a complete SQL string.
    default boolean
    supportsLimit()
    Does this handler support limiting query results?
    default boolean
    supportsLimitOffset()
    Does this handler support combinations of limit and offset?
    default boolean
    supportsOffset()
    Does this handler support offsetting query results without also specifying a limit?

  • Method Details

    • supportsLimit

      default boolean supportsLimit()
      Does this handler support limiting query results?
      Returns:
      True if this handler supports limit alone.

    • supportsOffset

      default boolean supportsOffset()
      Does this handler support offsetting query results without also specifying a limit?
      Returns:
      True if this handler supports offset alone.

    • supportsLimitOffset

      default boolean supportsLimitOffset()
      Does this handler support combinations of limit and offset?
      Returns:
      True if the handler supports an offset within the limit support.

    • processSql

      PaginationResult processSql(PaginationRequest request)

      Apply pagination to a complete SQL string.

      Return PaginationResult.unchanged(String) when the request needs no SQL or JDBC pagination. The returned JDBC instructions must describe every pagination parameter introduced by the rewritten SQL.

      Parameters:
      request - immutable completed-SQL pagination input
      Returns:
      rewritten SQL and the JDBC work needed to execute it

    • parameterPositionStart

      default int parameterPositionStart(PaginationRequest request)

      Determine the one-based position of the first original query parameter after any pagination parameters inserted at the beginning of the SQL.

      This method must agree with PaginationJdbcInstructions.parametersAtStart returned by processSql(PaginationRequest) and must not mutate this handler.