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 HTTP Requests.
    Incubating Feature. Will be removed in a future release.

    Instances of HttpRequest.Builder 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)
        Requests the server to acknowledge the request before sending the 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 publisher 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 actually 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. The given value is added to the list of values for that name.
        Parameters:
        name - the header name
        value - the header value
        Returns:
        this request builder
        Throws:
        IllegalArgumentException - if the header name or value is not valid, see RFC 7230 section-3.2

      • headers

        public abstract HttpRequest.Builder headers​(String... headers)
        Adds the given name value pairs to the set of headers for this request. The supplied String instances must alternate as header names and header values. To add several values to the same name then the same name must be supplied with each new value.
        Parameters:
        headers - the list of name value pairs
        Returns:
        this request builder
        Throws:
        IllegalArgumentException - if there are an odd number of parameters, or if a header name or value is not valid, see RFC 7230 section-3.2

      • 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
        Throws:
        IllegalArgumentException - if the duration is non-positive

      • 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
        Throws:
        IllegalArgumentException - if the header name or value is not valid, see RFC 7230 section-3.2

      • GET

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

      • POST

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

      • PUT

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

      • DELETE

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

      • method

        public abstract HttpRequest.Builder method​(String method,
                                           HttpRequest.BodyPublisher bodyPublisher)
        Sets the request method and request body of this builder to the given values.
        API Note:
        The noBody request body publisher can be used where no request body is required or appropriate.
        Parameters:
        method - the method to use
        bodyPublisher - the body publisher
        Returns:
        a HttpRequest
        Throws:
        IllegalArgumentException - if the method is unrecognised

      • 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