org.apache.hc.core5.http.protocol

## Class ViaRequest

- java.lang.Object
- - org.apache.hc.core5.http.protocol.ViaRequest

- All Implemented Interfaces:
    HttpRequestInterceptor

      @Contract(threading=IMMUTABLE)
      public class ViaRequest
      extends Object
      implements HttpRequestInterceptor

  This request interceptor can be used by an HTTP proxy or intemediary to add the `HttpHeaders.VIA` HTTP header to outgoing request messages.

  The `HttpHeaders.VIA` header is used to indicate intermediate protocols and recipients between the user agent and the server (on requests) or between the origin server and the client (on responses). It can be used for tracking message forwards, avoiding request loops, and identifying the protocol capabilities of senders along the request/response chain. Each member of the `HttpHeaders.VIA` header field value represents a proxy or gateway that has forwarded the message.

  A proxy MUST send an appropriate `HttpHeaders.VIA` header field, as described in the HTTP specification, in each message that it forwards. An HTTP-to-HTTP gateway MUST send an appropriate `HttpHeaders.VIA` header field in each inbound request message and MAY send a `HttpHeaders.VIA` header field in forwarded response messages.

  This interceptor ensures that the `HttpHeaders.VIA` header is added to the request only if it has not been added previously, as per the HTTP specification. Additionally, it updates the values in the `HttpHeaders.VIA` header correctly in case of multiple intermediate protocols or recipients, by appending its own information about how the message was received to the end of the header field value.

  Since:
    5.3

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static HttpRequestInterceptor` | `INSTANCE` Singleton instance.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ViaRequest()` Constructs a new `ViaRequest`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `process(HttpRequest request, EntityDetails entity, HttpContext context)` Adds the HTTP `HttpHeaders.VIA` header to the request if it does not already exist.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### INSTANCE

          public static final HttpRequestInterceptor INSTANCE

      Singleton instance.

  - ### Constructor Detail

    - #### ViaRequest

          public ViaRequest()

      Constructs a new `ViaRequest`.

  - ### Method Detail

    - #### process

          public void process(HttpRequest request,
                              EntityDetails entity,
                              HttpContext context)
                       throws ProtocolException,
                              IOException

      Adds the HTTP `HttpHeaders.VIA` header to the request if it does not already exist.

      This method ensures that the version of the request is HTTP/1.1 or higher, and adds the Via header in the format `<protocol> <version> <host>`, where `<protocol>` is the protocol name, `<version>` is the major and minor version of the request, and `<host>` is the value of the Host header.

      In case the `HttpHeaders.VIA` header already exists, this method updates its value by appending the new protocol information in the same format.

      If the version of the request is lower than `HTTP/1.1` or the request authority not being specified, this method throws a `ProtocolException`.

      Specified by:
        `process` in interface `HttpRequestInterceptor`
      Parameters:
        `request` - the request object to modify
        `entity` - the entity for the request, may be `null`
        `context` - the context for the request
      Throws:
        `ProtocolException` - if there was a protocol error, such as the request version being lower than `HTTP/1.1`, or the request authority not being specified
        `IOException` - if there was an I/O error

Copyright © 2005–2021 The Apache Software Foundation. All rights reserved.