Request (Apache Tomcat 10.1.57 API Documentation)
Description: declaration: package: org.apache.coyote, class: Request

# Class Request

java.lang.Object
org.apache.coyote.Request

public final class Request extends Object
This is a low-level, efficient representation of a server request. Most fields are GC-free, expensive operations are delayed until the user code needs the information. Processing is delegated to modules, using a hook mechanism. This class is not intended for user code - it is used internally by tomcat for processing the request in the most efficient way. Users ( servlets ) can access the information using a facade, which provides the high-level view of the request. Tomcat defines a number of attributes:

- "org.apache.tomcat.request" - allows access to the low-level request object in trusted applications

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `NOTE_BAD_REQUEST`
  Note key for bad request.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Request()`
  Default constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `action(ActionCode actionCode, Object param)`
  Perform an action on this request.
  `void`
  `addPathParameter(String name, String value)`
  Add a path parameter.
  `void`
  `clearRequestThread()`
  Clear the request thread ID.
  `MessageBytes`
  `contentType()`
  Return the content type.
  `MessageBytes`
  `decodedURI()`
  Return the decoded request URI.
  `int`
  `doRead(ApplicationBufferHandler handler)`
  Read data from the input buffer and put it into ApplicationBufferHandler.
  `Object`
  `getAttribute(String name)`
  Return the value of the specified attribute.
  `HashMap<String,Object>`
  `getAttributes()`
  Return the request attributes map.
  `MessageBytes`
  `getAuthType()`
  Return the authentication type.
  `int`
  `getAvailable()`
  Return the number of available bytes.
  `long`
  `getBytesRead()`
  Return the number of bytes read.
  `String`
  `getCharacterEncoding()`
  Get the character encoding used for this request.
  `Charset`
  `getCharset()`
  Get the character encoding used for this request.
  `int`
  `getContentLength()`
  Return the content length.
  `long`
  `getContentLengthLong()`
  Return the content length as a long.
  `String`
  `getContentType()`
  Return the content type as a string.
  `ServerCookies`
  `getCookies()`
  Return the server cookies.
  `Exception`
  `getErrorException()`
  Get the Exception that occurred during the writing of the response.
  `String`
  `getHeader(String name)`
  Return the value of the specified header.
  `InputBuffer`
  `getInputBuffer()`
  Return the input buffer.
  `int`
  `getLocalPort()`
  Return the local port.
  `String`
  `getMethod()`
  Return the HTTP method.
  `MimeHeaders`
  `getMimeHeaders()`
  Return the MIME headers.
  `MimeHeaders`
  `getMimeTrailerFields()`
  Return the MIME trailer fields.
  `Object`
  `getNote(int pos)`
  Return the note at the specified position.
  `Parameters`
  `getParameters()`
  Return the request parameters.
  `String`
  `getPathParameter(String name)`
  Return the value of the specified path parameter.
  `String`
  `getProtocolRequestId()`
  Return the protocol request ID.
  `ReadListener`
  `getReadListener()`
  Return the read listener.
  `int`
  `getRemotePort()`
  Return the remote port.
  `MessageBytes`
  `getRemoteUser()`
  Return the remote user.
  `boolean`
  `getRemoteUserNeedsAuthorization()`
  Check if the remote user needs authorization.
  `String`
  `getRequestId()`
  Return the request ID.
  `RequestInfo`
  `getRequestProcessor()`
  Return the request processor info.
  `Response`
  `getResponse()`
  Return the associated response.
  `boolean`
  `getSendfile()`
  Check if sendfile is enabled.
  `int`
  `getServerPort()`
  Return the server port.
  `ServletConnection`
  `getServletConnection()`
  Return the servlet connection.
  `Instant`
  `getStartInstant()`
  Return the request start instant.
  `long`
  `getStartTime()`
  Return the request start time in milliseconds.
  `long`
  `getStartTimeNanos()`
  Return the request start time in nanoseconds.
  `boolean`
  `getSupportsRelativeRedirects()`
  Check if relative redirects are supported.
  `long`
  `getThreadId()`
  Return the thread ID.
  `Map<String,String>`
  `getTrailerFields()`
  Return the trailer fields as a map.
  `UDecoder`
  `getURLDecoder()`
  Return the URL decoder.
  `boolean`
  `hasExpectation()`
  Check if there is an expectation.
  `boolean`
  `isExceptionPresent()`
  Check if an error exception is present.
  `boolean`
  `isFinished()`
  Check if the request body has been fully read.
  `boolean`
  `isProcessing()`
  Check if the request is currently being processed.
  `boolean`
  `isReady()`
  Check if the request is ready for reading.
  `boolean`
  `isRequestThread()`
  Check if the current thread is the request thread.
  `boolean`
  `isTrailerFieldsReady()`
  Check if trailer fields are ready.
  `MessageBytes`
  `localAddr()`
  Return the local address.
  `MessageBytes`
  `localName()`
  Return the local name.
  `void`
  `markStartTime()`
  Mark the request start time.
  `MessageBytes`
  `method()`
  Deprecated.
  Use `getMethod()`, `setMethod(String)` and `setMethod(byte[], int, int)`
  `void`
  `onDataAvailable()`
  Called when data is available for reading.
  `MessageBytes`
  `peerAddr()`
  Return the peer address.
  `MessageBytes`
  `protocol()`
  Return the protocol.
  `MessageBytes`
  `queryString()`
  Return the query string.
  `void`
  `recycle()`
  Recycle this request for reuse.
  `MessageBytes`
  `remoteAddr()`
  Return the remote address.
  `MessageBytes`
  `remoteHost()`
  Return the remote host.
  `MessageBytes`
  `requestURI()`
  Return the request URI.
  `MessageBytes`
  `scheme()`
  Return the scheme (e.g.
  `boolean`
  `sendAllDataReadEvent()`
  Send the all-data-read event.
  `MessageBytes`
  `serverName()`
  Get the "virtual host", derived from the Host: header associated with this request.
  `void`
  `setAttribute(String name, Object o)`
  Set an attribute.
  `void`
  `setAvailable(int available)`
  Set the number of available bytes.
  `void`
  `setCharset(Charset charset)`
  `void`
  `setContentLength(long len)`
  Set the content length.
  `void`
  `setContentType(String type)`
  Set the content type.
  `void`
  `setContentType(MessageBytes mb)`
  Set the content type.
  `void`
  `setErrorException(Exception ex)`
  Set the error Exception that occurred during the writing of the response processing.
  `void`
  `setExpectation(boolean expectation)`
  Set the expectation flag.
  `void`
  `setInputBuffer(InputBuffer inputBuffer)`
  Set the input buffer.
  `void`
  `setLocalPort(int port)`
  Set the local port.
  `void`
  `setMethod(byte[] buf, int start, int len)`
  Set the HTTP method from a byte buffer.
  `void`
  `setMethod(String method)`
  Set the HTTP method.
  `void`
  `setNote(int pos, Object value)`
  Used to store private data.
  `void`
  `setReadListener(ReadListener listener)`
  Set the read listener for non-blocking reads.
  `void`
  `setRemotePort(int port)`
  Set the remote port.
  `void`
  `setRemoteUserNeedsAuthorization(boolean remoteUserNeedsAuthorization)`
  Set whether the remote user needs authorization.
  `void`
  `setRequestThread()`
  Set the request thread ID.
  `void`
  `setResponse(Response response)`
  Set the associated response.
  `void`
  `setSendfile(boolean sendfile)`
  Set whether sendfile is enabled.
  `void`
  `setServerPort(int serverPort)`
  Set the server port.
  `void`
  `setStartTime(long startTime)`
  Deprecated.
  This setter will be removed in Tomcat 11.
  `void`
  `setStartTimeNanos(long startTimeNanos)`
  Deprecated.
  Unused.
  `String`
  `toString()`
  `void`
  `updateCounters()`
  Update request counters.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### NOTE_BAD_REQUEST

    public static final int NOTE_BAD_REQUEST
    Note key for bad request.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### Request

    public Request()
    Default constructor.

- ## Method Details

  - ### getReadListener

    public ReadListener getReadListener()
    Return the read listener.
    Returns:
      the read listener

  - ### setReadListener

    public void setReadListener(ReadListener listener)
    Set the read listener for non-blocking reads.
    Parameters:
      `listener` - the read listener

  - ### isReady

    public boolean isReady()
    Check if the request is ready for reading.
    Returns:
      `true` if ready for reading

  - ### onDataAvailable

    public void onDataAvailable() throws IOException
    Called when data is available for reading.
    Throws:
      `IOException` - if an I/O error occurs

  - ### sendAllDataReadEvent

    public boolean sendAllDataReadEvent()
    Send the all-data-read event.
    Returns:
      `true` if the event was sent

  - ### getMimeHeaders

    public MimeHeaders getMimeHeaders()
    Return the MIME headers.
    Returns:
      the MIME headers

  - ### isTrailerFieldsReady

    public boolean isTrailerFieldsReady()
    Check if trailer fields are ready.
    Returns:
      `true` if trailer fields are ready

  - ### getTrailerFields

    public Map<String,String> getTrailerFields()
    Return the trailer fields as a map.
    Returns:
      the trailer fields

  - ### getMimeTrailerFields

    public MimeHeaders getMimeTrailerFields()
    Return the MIME trailer fields.
    Returns:
      the MIME trailer fields

  - ### getURLDecoder

    public UDecoder getURLDecoder()
    Return the URL decoder.
    Returns:
      the URL decoder

  - ### scheme

    public MessageBytes scheme()
    Return the scheme (e.g. "http" or "https").
    Returns:
      the scheme

  - ### method

    @Deprecated public MessageBytes method()
    Deprecated.
    Use `getMethod()`, `setMethod(String)` and `setMethod(byte[], int, int)`
    Get a MessageBytes instance that holds the current request's HTTP method.
    Returns:
      a MessageBytes instance that holds the current request's HTTP method.

  - ### setMethod

    public void setMethod(String method)
    Set the HTTP method.
    Parameters:
      `method` - the HTTP method

  - ### setMethod

    public void setMethod(byte[] buf, int start, int len)
    Set the HTTP method from a byte buffer.
    Parameters:
      `buf` - the byte buffer
      `start` - the start offset
      `len` - the length

  - ### getMethod

    public String getMethod()
    Return the HTTP method.
    Returns:
      the HTTP method

  - ### requestURI

    public MessageBytes requestURI()
    Return the request URI.
    Returns:
      the request URI

  - ### decodedURI

    public MessageBytes decodedURI()
    Return the decoded request URI.
    Returns:
      the decoded URI

  - ### queryString

    public MessageBytes queryString()
    Return the query string.
    Returns:
      the query string

  - ### protocol

    public MessageBytes protocol()
    Return the protocol.
    Returns:
      the protocol

  - ### serverName

    public MessageBytes serverName()
    Get the "virtual host", derived from the Host: header associated with this request.
    Returns:
      The buffer holding the server name, if any. Use isNull() to check if there is no value set.

  - ### getServerPort

    public int getServerPort()
    Return the server port.
    Returns:
      the server port

  - ### setServerPort

    public void setServerPort(int serverPort)
    Set the server port.
    Parameters:
      `serverPort` - the server port

  - ### remoteAddr

    public MessageBytes remoteAddr()
    Return the remote address.
    Returns:
      the remote address

  - ### peerAddr

    public MessageBytes peerAddr()
    Return the peer address.
    Returns:
      the peer address

  - ### remoteHost

    public MessageBytes remoteHost()
    Return the remote host.
    Returns:
      the remote host

  - ### localName

    public MessageBytes localName()
    Return the local name.
    Returns:
      the local name

  - ### localAddr

    public MessageBytes localAddr()
    Return the local address.
    Returns:
      the local address

  - ### getRemotePort

    public int getRemotePort()
    Return the remote port.
    Returns:
      the remote port

  - ### setRemotePort

    public void setRemotePort(int port)
    Set the remote port.
    Parameters:
      `port` - the remote port

  - ### getLocalPort

    public int getLocalPort()
    Return the local port.
    Returns:
      the local port

  - ### setLocalPort

    public void setLocalPort(int port)
    Set the local port.
    Parameters:
      `port` - the local port

  - ### getCharacterEncoding

    public String getCharacterEncoding()
    Get the character encoding used for this request.
    Returns:
      The value set via `setCharset(Charset)` or if no call has been made to that method try to obtain if from the content type.

  - ### getCharset

    public Charset getCharset() throws UnsupportedEncodingException
    Get the character encoding used for this request.
    Returns:
      The value set via `setCharset(Charset)` or if no call has been made to that method try to obtain if from the content type.
    Throws:
      `UnsupportedEncodingException` - If the user agent has specified an invalid character encoding

  - ### setCharset

    public void setCharset(Charset charset)

  - ### setContentLength

    public void setContentLength(long len)
    Set the content length.
    Parameters:
      `len` - the content length

  - ### getContentLength

    public int getContentLength()
    Return the content length.
    Returns:
      the content length

  - ### getContentLengthLong

    public long getContentLengthLong()
    Return the content length as a long.
    Returns:
      the content length

  - ### getContentType

    public String getContentType()
    Return the content type as a string.
    Returns:
      the content type

  - ### setContentType

    public void setContentType(String type)
    Set the content type.
    Parameters:
      `type` - the content type

  - ### contentType

    public MessageBytes contentType()
    Return the content type.
    Returns:
      the content type

  - ### setContentType

    public void setContentType(MessageBytes mb)
    Set the content type.
    Parameters:
      `mb` - the content type

  - ### getHeader

    public String getHeader(String name)
    Return the value of the specified header.
    Parameters:
      `name` - the header name
    Returns:
      the header value

  - ### setExpectation

    public void setExpectation(boolean expectation)
    Set the expectation flag.
    Parameters:
      `expectation` - the expectation flag

  - ### hasExpectation

    public boolean hasExpectation()
    Check if there is an expectation.
    Returns:
      `true` if there is an expectation

  - ### getResponse

    public Response getResponse()
    Return the associated response.
    Returns:
      the response

  - ### setResponse

    public void setResponse(Response response)
    Set the associated response.
    Parameters:
      `response` - the response

  - ### action

    public void action(ActionCode actionCode, Object param)
    Perform an action on this request.
    Parameters:
      `actionCode` - the action code
      `param` - the action parameter

  - ### getCookies

    public ServerCookies getCookies()
    Return the server cookies.
    Returns:
      the server cookies

  - ### getParameters

    public Parameters getParameters()
    Return the request parameters.
    Returns:
      the parameters

  - ### addPathParameter

    public void addPathParameter(String name, String value)
    Add a path parameter.
    Parameters:
      `name` - the parameter name
      `value` - the parameter value

  - ### getPathParameter

    public String getPathParameter(String name)
    Return the value of the specified path parameter.
    Parameters:
      `name` - the parameter name
    Returns:
      the parameter value

  - ### setAttribute

    public void setAttribute(String name, Object o)
    Set an attribute.
    Parameters:
      `name` - the attribute name
      `o` - the attribute value

  - ### getAttributes

    public HashMap<String,Object> getAttributes()
    Return the request attributes map.
    Returns:
      the attributes map

  - ### getAttribute

    public Object getAttribute(String name)
    Return the value of the specified attribute.
    Parameters:
      `name` - the attribute name
    Returns:
      the attribute value

  - ### getRemoteUser

    public MessageBytes getRemoteUser()
    Return the remote user.
    Returns:
      the remote user

  - ### getRemoteUserNeedsAuthorization

    public boolean getRemoteUserNeedsAuthorization()
    Check if the remote user needs authorization.
    Returns:
      `true` if the remote user needs authorization

  - ### setRemoteUserNeedsAuthorization

    public void setRemoteUserNeedsAuthorization(boolean remoteUserNeedsAuthorization)
    Set whether the remote user needs authorization.
    Parameters:
      `remoteUserNeedsAuthorization` - `true` if authorization is needed

  - ### getAuthType

    public MessageBytes getAuthType()
    Return the authentication type.
    Returns:
      the authentication type

  - ### getAvailable

    public int getAvailable()
    Return the number of available bytes.
    Returns:
      the available bytes

  - ### setAvailable

    public void setAvailable(int available)
    Set the number of available bytes.
    Parameters:
      `available` - the available bytes

  - ### getSendfile

    public boolean getSendfile()
    Check if sendfile is enabled.
    Returns:
      `true` if sendfile is enabled

  - ### setSendfile

    public void setSendfile(boolean sendfile)
    Set whether sendfile is enabled.
    Parameters:
      `sendfile` - `true` to enable sendfile

  - ### isFinished

    public boolean isFinished()
    Check if the request body has been fully read.
    Returns:
      `true` if finished

  - ### getSupportsRelativeRedirects

    public boolean getSupportsRelativeRedirects()
    Check if relative redirects are supported.
    Returns:
      `true` if relative redirects are supported

  - ### getInputBuffer

    public InputBuffer getInputBuffer()
    Return the input buffer.
    Returns:
      the input buffer

  - ### setInputBuffer

    public void setInputBuffer(InputBuffer inputBuffer)
    Set the input buffer.
    Parameters:
      `inputBuffer` - the input buffer

  - ### doRead

    public int doRead(ApplicationBufferHandler handler) throws IOException
    Read data from the input buffer and put it into ApplicationBufferHandler. The buffer is owned by the protocol implementation - it will be reused on the next read. The Adapter must either process the data in place or copy it to a separate buffer if it needs to hold it. In most cases this is done during byte->char conversions or via InputStream. Unlike InputStream, this interface allows the app to process data in place, without copy.
    Parameters:
      `handler` - The destination to which to copy the data
    Returns:
      The number of bytes copied
    Throws:
      `IOException` - If an I/O error occurs during the copy

  - ### setErrorException

    public void setErrorException(Exception ex)
    Set the error Exception that occurred during the writing of the response processing.
    Parameters:
      `ex` - The exception that occurred

  - ### getErrorException

    public Exception getErrorException()
    Get the Exception that occurred during the writing of the response.
    Returns:
      The exception that occurred

  - ### isExceptionPresent

    public boolean isExceptionPresent()
    Check if an error exception is present.
    Returns:
      `true` if an exception is present

  - ### getRequestId

    public String getRequestId()
    Return the request ID.
    Returns:
      the request ID

  - ### getProtocolRequestId

    public String getProtocolRequestId()
    Return the protocol request ID.
    Returns:
      the protocol request ID

  - ### getServletConnection

    public ServletConnection getServletConnection()
    Return the servlet connection.
    Returns:
      the servlet connection

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### getStartTime

    public long getStartTime()
    Return the request start time in milliseconds.
    Returns:
      the start time

  - ### getStartTimeNanos

    public long getStartTimeNanos()
    Return the request start time in nanoseconds.
    Returns:
      the start time in nanoseconds

  - ### setStartTime

    @Deprecated public void setStartTime(long startTime)
    Deprecated.
    This setter will be removed in Tomcat 11. Use `markStartTime()`.
    Parameters:
      `startTime` - time

  - ### setStartTimeNanos

    @Deprecated public void setStartTimeNanos(long startTimeNanos)
    Deprecated.
    Unused. Will be removed in Tomcat 12 onwards. Use `markStartTime()`.
    Set the start time using the value provided by `System.nanoTime()`.
    Parameters:
      `startTimeNanos` - The value returned from `System.nanoTime()` at the point the requests started.

  - ### markStartTime

    public void markStartTime()
    Mark the request start time.

  - ### getStartInstant

    public Instant getStartInstant()
    Return the request start instant.
    Returns:
      the start instant

  - ### getThreadId

    public long getThreadId()
    Return the thread ID.
    Returns:
      the thread ID

  - ### clearRequestThread

    public void clearRequestThread()
    Clear the request thread ID.

  - ### setRequestThread

    public void setRequestThread()
    Set the request thread ID.

  - ### isRequestThread

    public boolean isRequestThread()
    Check if the current thread is the request thread.
    Returns:
      `true` if the current thread is the request thread

  - ### setNote

    public void setNote(int pos, Object value)
    Used to store private data. Thread data could be used instead - but if you have the req, getting/setting a note is just an array access, may be faster than ThreadLocal for very frequent operations. Example use: Catalina CoyoteAdapter: ADAPTER_NOTES = 1 - stores the HttpServletRequest object ( req/res) To avoid conflicts, note in the range 0 - 8 are reserved for the servlet container ( catalina connector, etc ), and values in 9 - 16 for connector use. 17-31 range is not allocated or used.
    Parameters:
      `pos` - Index to use to store the note
      `value` - The value to store at that index

  - ### getNote

    public Object getNote(int pos)
    Return the note at the specified position.
    Parameters:
      `pos` - the position
    Returns:
      the note

  - ### recycle

    public void recycle()
    Recycle this request for reuse.

  - ### updateCounters

    public void updateCounters()
    Update request counters.

  - ### getRequestProcessor

    public RequestInfo getRequestProcessor()
    Return the request processor info.
    Returns:
      the request processor info

  - ### getBytesRead

    public long getBytesRead()
    Return the number of bytes read.
    Returns:
      the bytes read

  - ### isProcessing

    public boolean isProcessing()
    Check if the request is currently being processed.
    Returns:
      `true` if processing