Module jdk.incubator.httpclient
Package jdk.incubator.http

Class HttpRequest.Builder

  • Enclosing class:
    HttpRequest

    public abstract static class HttpRequest.Builder
extends Object
    A builder of HttpRequests.
    Incubating Feature. Will be removed in a future release.

    HttpRequest.Builders are created by calling HttpRequest.newBuilder(URI) or HttpRequest.newBuilder().

    Each of the setter methods in this class modifies the state of the builder and returns this (ie. the same instance). The methods are not synchronized and should not be called from multiple threads without external synchronization.

    Note, that not all request headers may be set by user code. Some are restricted for security reasons and others such as the headers relating to authentication, redirection and cookie management are managed by specific APIs rather than through directly user set headers.

    The build method returns a new HttpRequest each time it is invoked.

    Since:
    9

    • Constructor Detail

      • Builder

        protected Builder​()
        Creates a Builder.

    • Method Detail

      • uri

        public abstract HttpRequest.Builder uri​(URI uri)
        Sets this HttpRequest's request URI.
        Parameters:
        uri - the request URI
        Returns:
        this request builder
        Throws:
        IllegalArgumentException - if the URI scheme is not supported.

      • expectContinue

        public abstract HttpRequest.Builder expectContinue​(boolean enable)
        Request server to acknowledge request before sending request body. This is disabled by default. If enabled, the server is requested to send an error response or a 100 Continue response before the client sends the request body. This means the request processor for the request will not be invoked until this interim response is received.
        Parameters:
        enable - true if Expect continue to be sent
        Returns:
        this request builder

      • version

        public abstract HttpRequest.Builder version​(HttpClient.Version version)
        Sets the preferred HttpClient.Version for this request. The corresponding HttpResponse should be checked for the version that was used. If the version is not set in a request, then the version requested will be that of the sending HttpClient.
        Parameters:
        version - the HTTP protocol version requested
        Returns:
        this request builder

      • header

        public abstract HttpRequest.Builder header​(String name,
                                           String value)
        Adds the given name value pair to the set of headers for this request.
        Parameters:
        name - the header name
        value - the header value
        Returns:
        this request builder

      • headers

        public abstract HttpRequest.Builder headers​(String... headers)
        Adds the given name value pairs to the set of headers for this request. The supplied Strings must alternate as names and values.
        Parameters:
        headers - the list of String name value pairs
        Returns:
        this request builder
        Throws:
        IllegalArgumentException - if there is an odd number of parameters

      • timeout

        public abstract HttpRequest.Builder timeout​(Duration duration)
        Sets a timeout for this request. If the response is not received within the specified timeout then a HttpTimeoutException is thrown from HttpClient::send or HttpClient::sendAsync completes exceptionally with a HttpTimeoutException. The effect of not setting a timeout is the same as setting an infinite Duration, ie. block forever.
        Parameters:
        duration - the timeout duration
        Returns:
        this request builder

      • setHeader

        public abstract HttpRequest.Builder setHeader​(String name,
                                              String value)
        Sets the given name value pair to the set of headers for this request. This overwrites any previously set values for name.
        Parameters:
        name - the header name
        value - the header value
        Returns:
        this request builder

      • GET

        public abstract HttpRequest.Builder GET​()
        Sets the request method of this builder to GET.
        Returns:
        a HttpRequest

      • POST

        public abstract HttpRequest.Builder POST​(HttpRequest.BodyProcessor body)
        Sets the request method of this builder to POST and sets its request body processor to the given value.
        Parameters:
        body - the body processor
        Returns:
        a HttpRequest

      • PUT

        public abstract HttpRequest.Builder PUT​(HttpRequest.BodyProcessor body)
        Sets the request method of this builder to PUT and sets its request body processor to the given value.
        Parameters:
        body - the body processor
        Returns:
        a HttpRequest

      • DELETE

        public abstract HttpRequest.Builder DELETE​(HttpRequest.BodyProcessor body)
        Sets the request method of this builder to DELETE and sets its request body processor to the given value.
        Parameters:
        body - the body processor
        Returns:
        a HttpRequest

      • copy

        public abstract HttpRequest.Builder copy​()
        Returns an exact duplicate copy of this Builder based on current state. The new builder can then be modified independently of this builder.
        Returns:
        an exact copy of this Builder