Interface ParameterRedactor

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

Converts non-secure bound parameter values into safe display values for diagnostics.

This is display-only: it does not change what is bound to the database. Pyranid never invokes a ParameterRedactor for SecureParameter values; SecureParameter.getMask() always wins. For batch executions, Pyranid renders a bounded batch summary and does not invoke this redactor for individual batch values.

Scope. A ParameterRedactor governs Pyranid's rendering of its own parameters=[...] diagnostic list only. It does not reach text the database driver itself produces: driver error messages can echo bound values (for example, constraint-violation detail), and only values explicitly wrapped with Parameters.secure(Object) trigger Pyranid's best-effort scrub of driver-echoed text - see SecureParameter for that mechanism and its limits. Note that under the default none(), non-secure values render verbatim in statement logs and exception text; configure redactAll() or a custom redactor if diagnostics may leave a trusted boundary.

Implementations return a non-null Optional containing the safe display value. An empty Optional renders as null in the same parameter slot; it does not fall back to the original value or omit the slot. Direct diagnostic rendering propagates failures if an implementation throws or returns a null Optional. When rendering is part of reporting a SQL failure, Pyranid uses its fail-closed parameter-display fallback and retains the original SQL failure, with the rendering failure suppressed.

Since:
4.4.0
Author:
Mark Allen
  • Method Details

    • redactParameter

      @NonNull Optional<Object> redactParameter(@NonNull StatementContext<?> statementContext, @NonNull Integer parameterIndex, @Nullable Object parameter)
      Redacts a single non-secure parameter for diagnostics.

      Since 4.9.0 this method returns a non-null Optional rather than a nullable Object. Implementations, lambdas and direct callers compiled against the earlier contract must be updated and recompiled.

      Read the original binding name with statementContext.getParameterNames().get(parameterIndex). Names have no leading colon; repeated bindings and IN-list elements retain their original name, and unknown names are null. For example, "password".equals(name) is a null-safe name check. This method is the single redaction entry point for diagnostics, direct callers and lambda decorators.

      Parameters:
      statementContext - current SQL context
      parameterIndex - zero-based index into StatementContext.getParameters() after IN-list expansion
      parameter - parameter value to render safely
      Returns:
      the safe display value, or an empty Optional to render null; never null
    • none

      Acquires the default redactor, which renders non-secure values verbatim for non-batch executions.
      Returns:
      the default redactor
    • redactAll

      Acquires a redactor that masks every non-secure value as <redacted>.
      Returns:
      a redactor that masks every non-secure value