Package org.codelibs.fess.api.v2

Class V2EnvelopeWriter

java.lang.Object
org.codelibs.fess.api.v2.V2EnvelopeWriter
public class V2EnvelopeWriter extends Object
Writes the unified /api/v2 response envelope.

All responses share a common shape:


 { "response": { "status": <int>, ...payload-or-error... } }

status follows the same convention as the v1 JSON API (0 = success, 1 = user error, 9 = system error) so existing client SDKs that already branch on this integer continue to work. The version field is omitted from the envelope because the API version is already encoded in the URL path (/api/v2/...).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    STATUS_OK
    Status value indicating a successful response.
    static final int
    STATUS_SYSTEM_ERROR
    Status value indicating an unexpected server-side failure.
    static final int
    STATUS_USER_ERROR
    Status value indicating a client-side / user error.

  • Constructor Summary

    Constructors
    Constructor
    Description
    V2EnvelopeWriter()
    Creates the v2 envelope writer.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    writeError(jakarta.servlet.http.HttpServletResponse res, V2ErrorCode code, String message)
    Writes an error v2 envelope and sets the HTTP status to the code's default.
    void
    writeErrorWithDetails(jakarta.servlet.http.HttpServletResponse res, V2ErrorCode code, String message, Map<String,Object> details)
    Writes an error v2 envelope with optional structured details.
    void
    writeInternalError(jakarta.servlet.http.HttpServletResponse res, Throwable cause, org.apache.logging.log4j.Logger logger, String contextTag)
    Convenience method for internal error paths.
    void
    writeSuccess(jakarta.servlet.http.HttpServletResponse res, Map<String,Object> payload)
    Writes a successful v2 envelope wrapping the supplied payload.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • STATUS_OK

      public static final int STATUS_OK
      Status value indicating a successful response.
      See Also:

    • STATUS_USER_ERROR

      public static final int STATUS_USER_ERROR
      Status value indicating a client-side / user error.
      See Also:

    • STATUS_SYSTEM_ERROR

      public static final int STATUS_SYSTEM_ERROR
      Status value indicating an unexpected server-side failure.
      See Also:

  • Constructor Details

    • V2EnvelopeWriter

      public V2EnvelopeWriter()
      Creates the v2 envelope writer. Registered as the DI component v2EnvelopeWriter and obtained via ComponentUtil.getV2EnvelopeWriter().

  • Method Details

    • writeSuccess

      public void writeSuccess(jakarta.servlet.http.HttpServletResponse res, Map<String,Object> payload) throws IOException
      Writes a successful v2 envelope wrapping the supplied payload.

      Does not change the HTTP status (defaults to whatever the container set, normally 200 OK). Sets the response content type to application/json; charset=UTF-8.

      Reserved keys: the payload must not contain the key "status"; it is owned by the envelope itself. Passing a map that contains that key will throw IllegalStateException so the mistake is caught at development/test time.

      Parameters:
      res - the HTTP response to write to
      payload - key/value fields to merge into the envelope; null is treated as empty
      Throws:
      IOException - if writing to the response fails
      IllegalStateException - if payload contains a reserved envelope key ("status")

    • writeError

      public void writeError(jakarta.servlet.http.HttpServletResponse res, V2ErrorCode code, String message) throws IOException
      Writes an error v2 envelope and sets the HTTP status to the code's default.

      The envelope's integer status is set to STATUS_SYSTEM_ERROR for V2ErrorCode.INTERNAL_ERROR and STATUS_USER_ERROR otherwise. A null message is normalised to the empty string so the wire shape stays predictable.

      Buffer reset contract: when the response is not yet committed, this method calls ServletResponse.resetBuffer() before writing so that any buffered partial body from a streaming handler (e.g. NDJSON, SSE) is discarded. This guarantees the wire response contains ONLY the error envelope and a clean application/json Content-Type — no hybrid responses.

      Parameters:
      res - the HTTP response to write to
      code - the v2 error code; its default HTTP status is applied to the response
      message - a human-readable message safe to expose to API callers
      Throws:
      IOException - if writing to the response fails

    • writeErrorWithDetails

      public void writeErrorWithDetails(jakarta.servlet.http.HttpServletResponse res, V2ErrorCode code, String message, Map<String,Object> details) throws IOException
      Writes an error v2 envelope with optional structured details.

      Behaves exactly like writeError(HttpServletResponse, V2ErrorCode, String) except that, when details is non-null, the map is embedded as error.details so callers can carry structured diagnostics (e.g. the engine snapshot on a service_unavailable health check) without breaking the canonical envelope shape.

      Buffer reset contract: when the response is not yet committed, this method calls ServletResponse.resetBuffer() before writing so any buffered partial body from a streaming handler is discarded.

      Parameters:
      res - the HTTP response to write to
      code - the v2 error code; its default HTTP status is applied to the response
      message - a human-readable message safe to expose to API callers
      details - optional structured details merged under error.details; null omits the key
      Throws:
      IOException - if writing to the response fails

    • writeInternalError

      public void writeInternalError(jakarta.servlet.http.HttpServletResponse res, Throwable cause, org.apache.logging.log4j.Logger logger, String contextTag) throws IOException
      Convenience method for internal error paths.

      Safety policy: the cause message is never written to the wire. Instead, it is logged via the caller-supplied logger so the detail is available in server logs without leaking connection strings, stack fragments or other server-internal information to API consumers. If the response is already committed (e.g. SSE or NDJSON handlers that flushed before the failure), the method returns silently to avoid corrupting the in-flight body.

      Parameters:
      res - the HTTP response to write to
      cause - the cause to log (may be null; only logged, never written to wire)
      logger - the caller's logger to use for WARN-level logging
      contextTag - a brief tag identifying the call site (e.g. "/api/v2/health")
      Throws:
      IOException - if writing the envelope fails