Package org.apache.juneau.rest.server

Class RestSession

java.lang.Object
org.apache.juneau.marshall.ContextSession
org.apache.juneau.rest.server.RestSession
public class RestSession extends ContextSession
Represents a single HTTP request.
Notes:
  • This class is not thread safe.

  • Field Details

    • REQUEST_SESSION_ATTR

      public static final String REQUEST_SESSION_ATTR
      Public-internal servlet-request attribute key under which the active RestSession publishes itself.

      The session-handle seam that lets code in other packages resolve the call's cached correlation id without a live public/custom-key attribute read: the debug formatter's statusLine (in the logging package) and RequestIdFilter (in the filter package) both read the session via fromRequest(jakarta.servlet.http.HttpServletRequest) and call getRequestId(). Not part of the public REST contract — the attribute name is an internal detail.

      See Also:

  • Constructor Details

  • Method Details

    • create

      public static RestSession.Builder create(RestContext ctx)
      Creates a builder of this object.
      Parameters:
      ctx - The context creating this builder.
      Cannot be null.
      Returns:
      A new builder.

    • fromRequest

      public static RestSession fromRequest(jakarta.servlet.http.HttpServletRequest req)
      Returns the RestSession published on the given servlet request via the REQUEST_SESSION_ATTR session-handle seam, or null if none is present.
      Parameters:
      req - The servlet request. Can be null (returns null).
      Returns:
      The active session, or null.

    • installCapture

      public RestSession installCapture() throws IOException
      Installs bounded body-caching wrappers on this call's request/response for debug capture.

      Called by the two-phase debug pipeline when the resolved logger is loggable at FINEST. Idempotent — the wrappers no-op if already installed.

      The capture cap is snapshotted from RestContext.getRestDebugFormatter().bodyCap() at install time, so a formatter override actually raises, lowers, or (via bodyCap(0)) disables the number of bytes retained — not just the wrapper's own 8 KB default.

      Returns:
      This object.
      Throws:
      IOException - Occurs if the request/response streams could not be wrapped.

    • exception

      public RestSession exception(Throwable value)
      Identifies that an exception occurred during this call.
      Parameters:
      value - The thrown exception.
      Can be null (will clear the exception attribute and remove the exception from the bean store).
      Returns:
      This object.

    • finish

      public RestSession finish()
      Called at the end of a call to finish any remaining tasks such as flushing buffers and logging the response.

      When the request has been handed off to a real AsyncContext, the response body/headers are written later on the response-completion thread. In that case this method neither flushes nor emits nor writes formatter-visible finish-time attributes — the completion hook owns all of that after the async body exists. The synchronous and synchronous-fallback (e.g. MockRestClient) paths are unchanged: they set finish-time attributes, flush, and emit here.

      Returns:
      This object.

    • closeRequestIdScope

      public void closeRequestIdScope()
      Closes this call's requestId LogContext scope, if open.

      Idempotent: safe to call more than once (and from a build path that never reaches finish(), such as a throwaway error session). Must run on the request thread that opened the scope so a pooled thread does not carry the scope into the next request.

    • setFinishTimeAttributes

      public void setFinishTimeAttributes()
      Records the finish-time request attributes consumed by the debug formatter (currently ExecTime).

      On the synchronous path this is called from finish(). On the asynchronous path it is called by the completion hook immediately before rendering — never by finish() after the async handoff — so the record always reflects the true request duration and the completion thread never races the request thread over formatter-visible response state. Idempotent: recomputing the value on repeat calls is harmless.

    • stashDebugSnapshot

      public void stashDebugSnapshot(Object value)
      Stashes the opaque debug-resolution snapshot on the request thread at the async-dispatch handoff.

      Internal plumbing for the two-thread async debug pipeline; not part of the public REST contract. The value is a package-private RestDebugSnapshot passed as Object so this class does not expose the type.

      Parameters:
      value - The snapshot, or null when access logging is off.

    • getDebugSnapshot

      public Object getDebugSnapshot()
      Returns the opaque debug-resolution snapshot stashed at the async-dispatch handoff.

      Internal plumbing for the two-thread async debug pipeline; not part of the public REST contract.

      Returns:
      The stashed snapshot, or null if none was stashed (synchronous path or access logging off).

    • getRequestId

      public String getRequestId()
      Returns the correlation id resolved for this call (mint-or-honor), cached at build time.

      This is the synchronous, session-cached value the debug formatter and RequestIdFilter read through the session-handle seam — never a live public/custom-key attribute read.

      Returns:
      The resolved request id. Never null (unless a custom id supplier returned null).

    • getBeanStore

      public WritableBeanStore getBeanStore()
      Returns the bean store of this call.
      Returns:
      The bean store of this call.

    • getContext

      public RestContext getContext()
      Returns the context that created this call.
      Overrides:
      getContext in class ContextSession
      Returns:
      The context that created this call.

    • getException

      public Throwable getException()
      Returns the exception that occurred during this call.
      Returns:
      The exception that occurred during this call, or null if no exception occurred.

    • getMethod

      public String getMethod() throws MethodNotAllowed, BadRequest
      Returns the HTTP method name.

      The request-line method, unless it is overridden by a method query parameter admitted by allowedMethodParams, or by one of the override headers admitted by allowedMethodHeaders (the query parameter wins, then the headers in that order).

      Override claims on an enabled channel (an allow-list that admits at least one method) must agree: more than one distinct claim, whether on one channel or across channels, is refused.

      Returns:
      The HTTP method name, always uppercased.
      Throws:
      MethodNotAllowed - If the method parameter contains invalid/malformed characters.
      BadRequest - If the request carries conflicting method overrides.

    • getOpSession

      public RestOpSession getOpSession() throws InternalServerError
      Returns the operation session of this REST session.

      The operation session is created once the Java method to be invoked has been determined.

      Returns:
      The operation session of this REST session.
      Throws:
      InternalServerError - If operation session has not been created yet.

    • getOpSessionOrNull

      public RestOpSession getOpSessionOrNull()
      Returns the RestOpSession created during run() if one has been built, or null otherwise.

      Unlike getOpSession(), this method does not throw — it lets callers in lifecycle code paths (such as mixin endCall dual-firing in RestContext.execute(Object, jakarta.servlet.http.HttpServletRequest, jakarta.servlet.http.HttpServletResponse)) inspect whether an operation was ever resolved without risking a spurious 500 when 404/405/412 paths bypass operation creation entirely.

      Returns:
      The operation session, or null if one was never created (e.g. early routing failure).
      Since:
      10.0.0

    • getPathInfo

      public String getPathInfo()
      Shortcut for calling getRequest().getPathInfo().
      Returns:
      The request servlet path info.

    • getPathInfoUndecoded

      public String getPathInfoUndecoded()
      Same as getPathInfo() but doesn't decode encoded characters.
      Returns:
      The undecoded request servlet path info, or null if there is no extra path information.

    • getPathVars

      public Map<String,String> getPathVars()
      Returns resolved @Resource(path) variable values on this call.
      Returns:
      Resolved @Resource(path) variable values on this call.

    • getQueryParams

      public Map<String,String[]> getQueryParams()
      Returns the query parameters on the request.

      Unlike ServletRequest.getParameterMap(), this doesn't parse the content if it's a POST.

      Returns:
      The query parameters on the request.

    • getRequest

      public jakarta.servlet.http.HttpServletRequest getRequest()
      Returns the HTTP servlet request of this REST call.
      Returns:
      the HTTP servlet request of this REST call.

    • getResource

      public Object getResource()
      Returns the REST object.
      Returns:
      The rest object, or null if no resource bean was specified.

    • getResponse

      public jakarta.servlet.http.HttpServletResponse getResponse()
      Returns the HTTP servlet response of this REST call.
      Returns:
      the HTTP servlet response of this REST call.

    • getServletPath

      public String getServletPath()
      Shortcut for calling getRequest().getServletPath().
      Returns:
      The request servlet path.

    • getStatus

      public int getStatus()
      Shortcut for calling getRequest().getStatus().
      Returns:
      The response status code.

    • getUrlPath

      public UrlPath getUrlPath()
      Returns the request path info as a UrlPath bean.
      Returns:
      The request path info as a UrlPath bean.

    • getUrlPathMatch

      public UrlPathMatch getUrlPathMatch()
      Returns the URL path pattern match on this call.
      Returns:
      The URL path pattern match on this call, or null if not set.

    • run

      public void run() throws Exception
      Runs this session.

      Does the following:

      1. Finds the Java method to invoke, refuses a safe request overridden to a method that is not a read (see RestOp.read()), and creates a RestOpSession for it.
      2. Invokes RestPreCall methods by calling RestContext.preCall(RestOpSession).
      3. Invokes Java method by calling RestOpSession.run().
      4. Invokes RestPostCall methods by calling RestContext.postCall(RestOpSession).
      5. If the Java method produced output, finds the response processor for it and runs it by calling RestContext.processResponse(RestOpSession).
      6. If no Java method matched, generates a 404/405/412 by calling RestContext.handleNotFound(RestSession).
      Throws:
      Exception - Any exception can be thrown.

    • status

      public RestSession status(int value)
      Sets the HTTP status on this call.
      Parameters:
      value - The status code.
      Returns:
      This object.

    • status

      public RestSession status(HttpStatusLine value)
      Sets the HTTP status on this call.
      Parameters:
      value - The status code.
      Can be null (ignored).
      Returns:
      This object.

    • urlPathMatch

      public RestSession urlPathMatch(UrlPathMatch value)
      Sets the URL path pattern match on this call.
      Parameters:
      value - The match pattern.
      Can be null (stored as an explicit null binding, distinct from no binding at all).
      Returns:
      This object.

    • properties

      protected FluentMap<String,Object> properties()
      Description copied from class: ContextSession
      Returns the properties on this bean as a map for debugging.
      Overrides:
      properties in class ContextSession
      Returns:
      The properties on this bean as a map for debugging.