src/java.net.http/share/classes/java/net/http/HttpRequest.java
branchhttp-client-branch
changeset 56140 049b6940e9db
parent 56138 4f92b988600e
child 56141 c28d710b8ef9
equal deleted inserted replaced
56139:b3d6203051df 56140:049b6940e9db
   120      * to authentication, redirection and cookie management may be managed by
   120      * to authentication, redirection and cookie management may be managed by
   121      * specific APIs rather than through directly user set headers.
   121      * specific APIs rather than through directly user set headers.
   122      *
   122      *
   123      * @since 11
   123      * @since 11
   124      */
   124      */
   125     public abstract static class Builder {
   125     public interface Builder {
   126 
       
   127         /**
       
   128          * Creates a Builder.
       
   129          */
       
   130         protected Builder() {}
       
   131 
   126 
   132         /**
   127         /**
   133          * Sets this {@code HttpRequest}'s request {@code URI}.
   128          * Sets this {@code HttpRequest}'s request {@code URI}.
   134          *
   129          *
   135          * @param uri the request URI
   130          * @param uri the request URI
   136          * @return this request builder
   131          * @return this request builder
   137          * @throws IllegalArgumentException if the {@code URI} scheme is not
   132          * @throws IllegalArgumentException if the {@code URI} scheme is not
   138          *         supported
   133          *         supported
   139          */
   134          */
   140         public abstract Builder uri(URI uri);
   135         public Builder uri(URI uri);
   141 
   136 
   142         /**
   137         /**
   143          * Requests the server to acknowledge the request before sending the
   138          * Requests the server to acknowledge the request before sending the
   144          * body. This is disabled by default. If enabled, the server is
   139          * body. This is disabled by default. If enabled, the server is
   145          * requested to send an error response or a {@code 100 Continue}
   140          * requested to send an error response or a {@code 100 Continue}
   148          * interim response is received.
   143          * interim response is received.
   149          *
   144          *
   150          * @param enable {@code true} if Expect continue to be sent
   145          * @param enable {@code true} if Expect continue to be sent
   151          * @return this request builder
   146          * @return this request builder
   152          */
   147          */
   153         public abstract Builder expectContinue(boolean enable);
   148         public Builder expectContinue(boolean enable);
   154 
   149 
   155         /**
   150         /**
   156          * Sets the preferred {@link HttpClient.Version} for this request.
   151          * Sets the preferred {@link HttpClient.Version} for this request.
   157          *
   152          *
   158          * <p> The corresponding {@link HttpResponse} should be checked for the
   153          * <p> The corresponding {@link HttpResponse} should be checked for the
   161          * {@link HttpClient}.
   156          * {@link HttpClient}.
   162          *
   157          *
   163          * @param version the HTTP protocol version requested
   158          * @param version the HTTP protocol version requested
   164          * @return this request builder
   159          * @return this request builder
   165          */
   160          */
   166         public abstract Builder version(HttpClient.Version version);
   161         public Builder version(HttpClient.Version version);
   167 
   162 
   168         /**
   163         /**
   169          * Adds the given name value pair to the set of headers for this request.
   164          * Adds the given name value pair to the set of headers for this request.
   170          * The given value is added to the list of values for that name.
   165          * The given value is added to the list of values for that name.
   171          *
   166          *
   183          * @throws IllegalArgumentException if the header name or value is not
   178          * @throws IllegalArgumentException if the header name or value is not
   184          *         valid, see <a href="https://tools.ietf.org/html/rfc7230#section-3.2">
   179          *         valid, see <a href="https://tools.ietf.org/html/rfc7230#section-3.2">
   185          *         RFC 7230 section-3.2</a>, or the header name or value is restricted
   180          *         RFC 7230 section-3.2</a>, or the header name or value is restricted
   186          *         by the implementation.
   181          *         by the implementation.
   187          */
   182          */
   188         public abstract Builder header(String name, String value);
   183         public Builder header(String name, String value);
   189 
   184 
   190         /**
   185         /**
   191          * Adds the given name value pairs to the set of headers for this
   186          * Adds the given name value pairs to the set of headers for this
   192          * request. The supplied {@code String} instances must alternate as
   187          * request. The supplied {@code String} instances must alternate as
   193          * header names and header values.
   188          * header names and header values.
   201          *         <a href="https://tools.ietf.org/html/rfc7230#section-3.2">
   196          *         <a href="https://tools.ietf.org/html/rfc7230#section-3.2">
   202          *         RFC 7230 section-3.2</a>, or a header name or value is
   197          *         RFC 7230 section-3.2</a>, or a header name or value is
   203          *         {@linkplain #header(String, String) restricted} by the
   198          *         {@linkplain #header(String, String) restricted} by the
   204          *         implementation.
   199          *         implementation.
   205          */
   200          */
   206         public abstract Builder headers(String... headers);
   201         public Builder headers(String... headers);
   207 
   202 
   208         /**
   203         /**
   209          * Sets a timeout for this request. If the response is not received
   204          * Sets a timeout for this request. If the response is not received
   210          * within the specified timeout then a {@link HttpTimeoutException} is
   205          * within the specified timeout then a {@link HttpTimeoutException} is
   211          * thrown from {@link HttpClient#send(java.net.http.HttpRequest,
   206          * thrown from {@link HttpClient#send(java.net.http.HttpRequest,
   233          *         see <a href="https://tools.ietf.org/html/rfc7230#section-3.2">
   228          *         see <a href="https://tools.ietf.org/html/rfc7230#section-3.2">
   234          *         RFC 7230 section-3.2</a>, or the header name or value is
   229          *         RFC 7230 section-3.2</a>, or the header name or value is
   235          *         {@linkplain #header(String, String) restricted} by the
   230          *         {@linkplain #header(String, String) restricted} by the
   236          *         implementation.
   231          *         implementation.
   237          */
   232          */
   238         public abstract Builder setHeader(String name, String value);
   233         public Builder setHeader(String name, String value);
   239 
   234 
   240         /**
   235         /**
   241          * Sets the request method of this builder to GET.
   236          * Sets the request method of this builder to GET.
   242          * This is the default.
   237          * This is the default.
   243          *
   238          *
   244          * @return a {@code HttpRequest}
   239          * @return a {@code HttpRequest}
   245          */
   240          */
   246         public abstract Builder GET();
   241         public Builder GET();
   247 
   242 
   248         /**
   243         /**
   249          * Sets the request method of this builder to POST and sets its
   244          * Sets the request method of this builder to POST and sets its
   250          * request body publisher to the given value.
   245          * request body publisher to the given value.
   251          *
   246          *
   252          * @param bodyPublisher the body publisher
   247          * @param bodyPublisher the body publisher
   253          *
   248          *
   254          * @return a {@code HttpRequest}
   249          * @return a {@code HttpRequest}
   255          */
   250          */
   256         public abstract Builder POST(BodyPublisher bodyPublisher);
   251         public Builder POST(BodyPublisher bodyPublisher);
   257 
   252 
   258         /**
   253         /**
   259          * Sets the request method of this builder to PUT and sets its
   254          * Sets the request method of this builder to PUT and sets its
   260          * request body publisher to the given value.
   255          * request body publisher to the given value.
   261          *
   256          *
   262          * @param bodyPublisher the body publisher
   257          * @param bodyPublisher the body publisher
   263          *
   258          *
   264          * @return a {@code HttpRequest}
   259          * @return a {@code HttpRequest}
   265          */
   260          */
   266         public abstract Builder PUT(BodyPublisher bodyPublisher);
   261         public Builder PUT(BodyPublisher bodyPublisher);
   267 
   262 
   268         /**
   263         /**
   269          * Sets the request method of this builder to DELETE and sets its
   264          * Sets the request method of this builder to DELETE and sets its
   270          * request body publisher to the given value.
   265          * request body publisher to the given value.
   271          *
   266          *
   272          * @param bodyPublisher the body publisher
   267          * @param bodyPublisher the body publisher
   273          *
   268          *
   274          * @return a {@code HttpRequest}
   269          * @return a {@code HttpRequest}
   275          */
   270          */
   276 
   271 
   277         public abstract Builder DELETE(BodyPublisher bodyPublisher);
   272         public Builder DELETE(BodyPublisher bodyPublisher);
   278 
   273 
   279         /**
   274         /**
   280          * Sets the request method and request body of this builder to the
   275          * Sets the request method and request body of this builder to the
   281          * given values.
   276          * given values.
   282          *
   277          *
   289          * @param method the method to use
   284          * @param method the method to use
   290          * @param bodyPublisher the body publisher
   285          * @param bodyPublisher the body publisher
   291          * @return a {@code HttpRequest}
   286          * @return a {@code HttpRequest}
   292          * @throws IllegalArgumentException if the method is restricted
   287          * @throws IllegalArgumentException if the method is restricted
   293          */
   288          */
   294         public abstract Builder method(String method, BodyPublisher bodyPublisher);
   289         public Builder method(String method, BodyPublisher bodyPublisher);
   295 
   290 
   296         /**
   291         /**
   297          * Builds and returns a {@link HttpRequest}.
   292          * Builds and returns a {@link HttpRequest}.
   298          *
   293          *
   299          * @return the request
   294          * @return the request
   300          * @throws IllegalStateException if a URI has not been set
   295          * @throws IllegalStateException if a URI has not been set
   301          */
   296          */
   302         public abstract HttpRequest build();
   297         public HttpRequest build();
   303 
   298 
   304         /**
   299         /**
   305          * Returns an exact duplicate copy of this {@code Builder} based on
   300          * Returns an exact duplicate copy of this {@code Builder} based on
   306          * current state. The new builder can then be modified independently of
   301          * current state. The new builder can then be modified independently of
   307          * this builder.
   302          * this builder.
   308          *
   303          *
   309          * @return an exact copy of this Builder
   304          * @return an exact copy of this Builder
   310          */
   305          */
   311         public abstract Builder copy();
   306         public Builder copy();
   312     }
   307     }
   313 
   308 
   314     /**
   309     /**
   315      * Creates an {@code HttpRequest} builder with the given URI.
   310      * Creates an {@code HttpRequest} builder with the given URI.
   316      *
   311      *