Package eu.cloudnetservice.driver.network.http

Interface HttpContext

All Known Implementing Classes:
NettyHttpServerContext
public interface HttpContext
The context of a http request. Each request will pass this context to all handlers of it, allowing them the maximum control about the request flow.
Since:
4.0
See Also:

  • Method Details

    • upgrade

      @NonNull @NonNull eu.cloudnetservice.common.concurrent.Task<WebSocketChannel> upgrade()
      Upgrades this context to a websocket connection. In normal cases, as CloudNet currently only supports Http 1.X the client sends an upgrade header in its request to signal that an upgrade to a websocket channel is requested. See Mozilla - Upgrade docs for more information on how to use the header and the handshaking between the client and server works.

      This method blocks the current thread until the handshake processes completed. Either successfully or with a failure of any kind.

      If the upgrade to a websocket connection is not possible, the method automatically answers with a reason text to the client why the upgrade failed. Either because the socket version is not supported, or an exception occurred. Supported web socket versions are:

      1. Wire protocol version 13 (RFC-6455/draft version 17 of the hybi specification)

      If the upgrade fails this method returns a task which is completed exceptionally and sends a response to the client indicating the reason for the failure. After that, the connection is still able to send out http requests but will no longer accept / handle these.

      Returns:
      a task completed with the upgraded web socket channel or an exception if the upgrade was not possible.

    • webSocketChanel

      @Nullable @Nullable WebSocketChannel webSocketChanel()
      Get the web socket channel to which this request was upgraded. If the request was not upgraded, or the upgrade was not possible this method returns null.
      Returns:
      the upgraded web socket channel, or null if the connection upgrade was not done or failed.

    • channel

      @NonNull @NonNull HttpChannel channel()
      Get the channel to which the request came which is currently processed.
      Returns:
      the channel to which the request came.

    • request

      @NonNull @NonNull HttpRequest request()
      Get the current request which is handled in this context.
      Returns:
      the current request.

    • response

      @NonNull @NonNull HttpResponse response()
      Get the current response which will be sent to the client.
      Returns:
      the current response.

    • peekLast

      @Nullable @Nullable HttpHandler peekLast()
      Peeks (gets, but does not remove) the last handler in the chain.
      Returns:
      the last handler in the chain, null if there are no handlers.

    • cancelNext

      boolean cancelNext()
      Sets the current handler as the last handler, cancelling the call of all handlers which are still waiting to be called down the line. This is useful when a handler should set the final result of the request, not allowing any handler to overwrite it.
      Returns:
      true if the cancel state was updated, false otherwise.

    • cancelNext

      @NonNull @NonNull HttpContext cancelNext(boolean cancelNext)
      Sets whether the current handler should be the last handler in the listener call chain, cancelling the call of all handlers which are still waiting to be called down the line. This is useful when a handler should set the final result of the request, not allowing any handler to overwrite it.
      Parameters:
      cancelNext - if the next handlers in the chain should be skipped.
      Returns:
      the same instance of the context as used to call the method, for chaining.

    • component

      @NonNull @NonNull HttpComponent<?> component()
      Get the http component which received the request wrapped by this context.
      Returns:
      the http component which received the request.

    • closeAfter

      @NonNull @NonNull HttpContext closeAfter(boolean value)
      Sets whether the connection to client should be closed after the last handler in the chain. This defaults to true. If set to false, the connection will not be closed and the connection header will automatically be set to keep-alive. Mdn docs are providing a more in-depth walk through which other components may be set by a developer to customize the keep alive header.
      Parameters:
      value - true if the connection should get closed after the last handler, false to keep it open.
      Returns:
      the same instance of the context as used to call the method, for chaining.

    • closeAfter

      boolean closeAfter()
      Sets that the connection to the client should be terminated after the last handler in the chain.
      Returns:
      true if the closing state was updated, false otherwise.

    • cookie

      @Nullable @Nullable HttpCookie cookie(@NonNull @NonNull String name)
      Gets a cookie by its name from the current request. Cookies are decoded and encoded in a relaxed (lax) format, this means that duplicate cookies are allowed. If there are multiple cookies with the same name, the first one is returned by this method. If no cookie with the given name is present, this method returns null.
      Parameters:
      name - the name of the cookie to get.
      Returns:
      the first cookie with the given name sent by the client.
      Throws:
      NullPointerException - if the given name is null.

    • cookies

      @NonNull @NonNull Collection<HttpCookie> cookies()
      Get all cookies which were set in the current request wrapped in this context. Cookies are decoded and encoded in a relaxed (lax) format, this means that duplicate cookies are allowed.
      Returns:
      all cookies set by in the wrapped request.

    • hasCookie

      boolean hasCookie(@NonNull @NonNull String name)
      Get if a cookie with the given name was sent by the client sending the request to the server. Cookies are decoded and encoded in a relaxed (lax) format, this means that duplicate cookies are allowed. If there are multiple cookies with the same name set in the request this method returns true anyway.
      Parameters:
      name - the name of the cookie to check for.
      Returns:
      true if a cookie with the given name is present, false otherwise.
      Throws:
      NullPointerException - if the given name is null.

    • cookies

      @NonNull @NonNull HttpContext cookies(@NonNull @NonNull Collection<HttpCookie> cookies)
      Sets the given cookies in the response, removing all previously set cookies.
      Parameters:
      cookies - the new cookies of the response.
      Returns:
      the same instance of the context as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given cookie collection is null.

    • addCookie

      @NonNull @NonNull HttpContext addCookie(@NonNull @NonNull HttpCookie httpCookie)
      Adds the given cookie to the response, removing the current one if there is already a cookie with the same name.
      Parameters:
      httpCookie - the cookie to add.
      Returns:
      the same instance of the context as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given cookie is null.

    • removeCookie

      @NonNull @NonNull HttpContext removeCookie(@NonNull @NonNull String name)
      Removes the given cookie from the response, if set.
      Parameters:
      name - the name of the cookie to remove.
      Returns:
      the same instance of the context as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given cookie is null.

    • clearCookies

      @NonNull @NonNull HttpContext clearCookies()
      Removes all cookies previously set in the response.
      Returns:
      the same instance of the context as used to call the method, for chaining.

    • pathPrefix

      @NonNull @NonNull String pathPrefix()
      Get the path of the handler, supplied while registering, which currently handling the request.
      Returns:
      the path of the handler handling the request.

    • invocationHints

      @NonNull @NonNull Collection<Object> invocationHints(@NonNull @NonNull String key)
      Get all invocation hints which are registered for the given key. Invocation hints are only valid for the current handler call chain, and will be reset after a handler was called. Hints can for example get registered in a http context preprocessor.

      This method never returns null. If no hints are registered for the given key then an empty collection is returned.

      Parameters:
      key - the key of the hints to retrieve.
      Returns:
      the registered hints for the given key, or an empty collection if no hints are registered.
      Throws:
      NullPointerException - if the given key is null.

    • addInvocationHint

      @NonNull @NonNull HttpContext addInvocationHint(@NonNull @NonNull String key, @NonNull @NonNull Object value)
      Adds an invocation hint for the current handler call chain. Invocation hints are only valid for the current handler call chain, and will be reset after a handler was called. Hints can for example get registered in a http context preprocessor.

      One key can be mapped to multiple hints.

      Parameters:
      key - the key of the hint to register.
      value - the hint.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given key or hint is null.

    • addInvocationHints

      @NonNull <T> @NonNull HttpContext addInvocationHints(@NonNull @NonNull String key, @NonNull @NonNull Collection<T> value)
      Adds an invocation hint for the current handler call chain. Invocation hints are only valid for the current handler call chain, and will be reset after a handler was called. Hints can for example get registered in a http context preprocessor.

      One key can be mapped to multiple hints.

      Parameters:
      key - the key of the hint to register.
      value - the hints to add.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given key or hint is null.