author | chegar |
Fri, 16 Feb 2018 16:50:27 +0000 | |
branch | http-client-branch |
changeset 56142 | 571ba7474214 |
parent 56141 | c28d710b8ef9 |
child 56143 | 11e32a62803d |
permissions | -rw-r--r-- |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
1 |
/* |
56088
38fac6d0521d
http-client-branch: update copyright year ranges in prep for file moves
chegar
parents:
56087
diff
changeset
|
2 |
* Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
4 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
5 |
* This code is free software; you can redistribute it and/or modify it |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
6 |
* under the terms of the GNU General Public License version 2 only, as |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
7 |
* published by the Free Software Foundation. Oracle designates this |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
8 |
* particular file as subject to the "Classpath" exception as provided |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
9 |
* by Oracle in the LICENSE file that accompanied this code. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
10 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
15 |
* accompanied this code). |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
16 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
17 |
* You should have received a copy of the GNU General Public License version |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
20 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
22 |
* or visit www.oracle.com if you need additional information or have any |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
23 |
* questions. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
24 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
25 |
|
56089
42208b2f224e
http-client-branch: move to standard package and module name
chegar
parents:
56088
diff
changeset
|
26 |
package java.net.http; |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
27 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
28 |
import java.io.FileNotFoundException; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
29 |
import java.io.InputStream; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
30 |
import java.net.URI; |
48083 | 31 |
import java.net.URLPermission; |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
32 |
import java.nio.ByteBuffer; |
48083 | 33 |
import java.nio.charset.Charset; |
34 |
import java.nio.charset.StandardCharsets; |
|
35 |
import java.nio.file.Files; |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
36 |
import java.nio.file.Path; |
48083 | 37 |
import java.security.AccessController; |
38 |
import java.security.PrivilegedAction; |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
39 |
import java.time.Duration; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
40 |
import java.util.Iterator; |
48083 | 41 |
import java.util.Objects; |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
42 |
import java.util.Optional; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
43 |
import java.util.concurrent.CompletableFuture; |
48083 | 44 |
import java.util.concurrent.Executor; |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
45 |
import java.util.concurrent.Flow; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
46 |
import java.util.function.Supplier; |
56089
42208b2f224e
http-client-branch: move to standard package and module name
chegar
parents:
56088
diff
changeset
|
47 |
import java.net.http.HttpResponse.BodyHandler; |
56092
fd85b2bf2b0d
http-client-branch: move implementation to jdk.internal.net.http
chegar
parents:
56089
diff
changeset
|
48 |
import jdk.internal.net.http.HttpRequestBuilderImpl; |
fd85b2bf2b0d
http-client-branch: move implementation to jdk.internal.net.http
chegar
parents:
56089
diff
changeset
|
49 |
import jdk.internal.net.http.RequestPublishers; |
48083 | 50 |
import static java.nio.charset.StandardCharsets.UTF_8; |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
51 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
52 |
/** |
56085
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
53 |
* An HTTP request. |
43302
45de1dc92ecd
8173354: javadoc warning notice for types in Incubator Modules
chegar
parents:
42460
diff
changeset
|
54 |
* |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
55 |
* <p> An {@code HttpRequest} instance is built through an {@code HttpRequest} |
56085
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
56 |
* {@linkplain HttpRequest.Builder builder}. An {@code HttpRequest} builder |
56099
41ba54ac9403
http-client-branch: revert overzealous use of @linkplain
chegar
parents:
56097
diff
changeset
|
57 |
* is obtained from one of the {@link HttpRequest#newBuilder(URI) newBuilder} |
41ba54ac9403
http-client-branch: revert overzealous use of @linkplain
chegar
parents:
56097
diff
changeset
|
58 |
* methods. A request's {@link URI}, headers, and body can be set. Request |
41ba54ac9403
http-client-branch: revert overzealous use of @linkplain
chegar
parents:
56097
diff
changeset
|
59 |
* bodies are provided through a {@link BodyPublisher BodyPublisher} supplied |
41ba54ac9403
http-client-branch: revert overzealous use of @linkplain
chegar
parents:
56097
diff
changeset
|
60 |
* to one of the {@link Builder#DELETE(BodyPublisher) DELETE}, |
41ba54ac9403
http-client-branch: revert overzealous use of @linkplain
chegar
parents:
56097
diff
changeset
|
61 |
* {@link Builder#POST(BodyPublisher) POST} or |
41ba54ac9403
http-client-branch: revert overzealous use of @linkplain
chegar
parents:
56097
diff
changeset
|
62 |
* {@link Builder#PUT(BodyPublisher) PUT} methods. |
56085
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
63 |
* Once all required parameters have been set in the builder, {@link |
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
64 |
* Builder#build() build} will return the {@code HttpRequest}. Builders can be |
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
65 |
* copied and modified many times in order to build multiple related requests |
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
66 |
* that differ in some parameters. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
67 |
* |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
68 |
* <p><b>Example:</b> GET request that prints the response body as a String |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
69 |
* <pre>{@code HttpClient client = HttpClient.newHttpClient(); |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
70 |
* HttpRequest request = HttpRequest.newBuilder() |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
71 |
* .uri(URI.create("http://foo.com/")) |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
72 |
* .build(); |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
73 |
* client.sendAsync(request, BodyHandler.asString()) |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
74 |
* .thenApply(HttpResponse::body) |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
75 |
* .thenAccept(System.out::println) |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
76 |
* .join(); }</pre> |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
77 |
* |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
78 |
* <p><b>Request bodies</b> |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
79 |
* |
48083 | 80 |
* <p> Request bodies can be sent using one of the convenience request publisher |
56099
41ba54ac9403
http-client-branch: revert overzealous use of @linkplain
chegar
parents:
56097
diff
changeset
|
81 |
* implementations, provided in {@link BodyPublisher BodyPublisher}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
82 |
* <ul> |
48083 | 83 |
* <li>{@link BodyPublisher#fromByteArray(byte[]) fromByteArray(byte[])} from byte array</li> |
84 |
* <li>{@link BodyPublisher#fromByteArrays(Iterable) fromByteArrays(Iterable)} |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
85 |
* from an Iterable of byte arrays</li> |
48083 | 86 |
* <li>{@link BodyPublisher#fromFile(java.nio.file.Path) fromFile(Path)} from the file located |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
87 |
* at the given Path</li> |
48083 | 88 |
* <li>{@link BodyPublisher#fromString(java.lang.String) fromString(String)} from a String </li> |
89 |
* <li>{@link BodyPublisher#fromInputStream(Supplier) fromInputStream}({@link Supplier}< |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
90 |
* {@link InputStream}>) from an InputStream obtained from a Supplier</li> |
56085
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
91 |
* <li>{@link BodyPublisher#noBody() noBody()} no request body is sent</li> |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
92 |
* </ul> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
93 |
* |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
94 |
* <p> Alternatively, a custom {@code BodyPublisher} implementation can be used. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
95 |
* |
56086 | 96 |
* @since 11 |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
97 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
98 |
public abstract class HttpRequest { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
99 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
100 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
101 |
* Creates an HttpRequest. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
102 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
103 |
protected HttpRequest() {} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
104 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
105 |
/** |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
106 |
* A builder of {@linkplain HttpRequest HTTP requests}. |
43302
45de1dc92ecd
8173354: javadoc warning notice for types in Incubator Modules
chegar
parents:
42460
diff
changeset
|
107 |
* |
48083 | 108 |
* <p> Instances of {@code HttpRequest.Builder} are created by calling {@link |
43302
45de1dc92ecd
8173354: javadoc warning notice for types in Incubator Modules
chegar
parents:
42460
diff
changeset
|
109 |
* HttpRequest#newBuilder(URI)} or {@link HttpRequest#newBuilder()}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
110 |
* |
56142 | 111 |
* <p> Each of the setter methods modifies the state of the builder |
112 |
* and returns the same instance. The methods are not synchronized and |
|
113 |
* should not be called from multiple threads without external |
|
114 |
* synchronization. The {@link #build() build} method returns a new |
|
115 |
* {@code HttpRequest} each time it is invoked. Once built an {@code |
|
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
116 |
* HttpRequest} is immutable, and can be sent multiple times. |
48083 | 117 |
* |
118 |
* <p> Note, that not all request headers may be set by user code. Some are |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
119 |
* restricted for security reasons and others such as the headers relating |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
120 |
* to authentication, redirection and cookie management may be managed by |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
121 |
* specific APIs rather than through directly user set headers. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
122 |
* |
56086 | 123 |
* @since 11 |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
124 |
*/ |
56140 | 125 |
public interface Builder { |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
126 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
127 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
128 |
* Sets this {@code HttpRequest}'s request {@code URI}. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
129 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
130 |
* @param uri the request URI |
56142 | 131 |
* @return this builder |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
132 |
* @throws IllegalArgumentException if the {@code URI} scheme is not |
48083 | 133 |
* supported |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
134 |
*/ |
56140 | 135 |
public Builder uri(URI uri); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
136 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
137 |
/** |
48083 | 138 |
* Requests the server to acknowledge the request before sending the |
139 |
* body. This is disabled by default. If enabled, the server is |
|
140 |
* requested to send an error response or a {@code 100 Continue} |
|
141 |
* response before the client sends the request body. This means the |
|
142 |
* request publisher for the request will not be invoked until this |
|
143 |
* interim response is received. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
144 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
145 |
* @param enable {@code true} if Expect continue to be sent |
56142 | 146 |
* @return this builder |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
147 |
*/ |
56140 | 148 |
public Builder expectContinue(boolean enable); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
149 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
150 |
/** |
48083 | 151 |
* Sets the preferred {@link HttpClient.Version} for this request. |
152 |
* |
|
153 |
* <p> The corresponding {@link HttpResponse} should be checked for the |
|
154 |
* version that was actually used. If the version is not set in a |
|
155 |
* request, then the version requested will be that of the sending |
|
156 |
* {@link HttpClient}. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
157 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
158 |
* @param version the HTTP protocol version requested |
56142 | 159 |
* @return this builder |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
160 |
*/ |
56140 | 161 |
public Builder version(HttpClient.Version version); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
162 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
163 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
164 |
* Adds the given name value pair to the set of headers for this request. |
48083 | 165 |
* The given value is added to the list of values for that name. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
166 |
* |
56033
db102c5ca88a
http-client-branch: 8194729: Java 9's HttpClient doesn't allow custom 'Authorization' headers
dfuchs
parents:
56030
diff
changeset
|
167 |
* @implNote An implementation may choose to restrict some header names |
db102c5ca88a
http-client-branch: 8194729: Java 9's HttpClient doesn't allow custom 'Authorization' headers
dfuchs
parents:
56030
diff
changeset
|
168 |
* or values, as the HTTP Client may determine their value itself. |
db102c5ca88a
http-client-branch: 8194729: Java 9's HttpClient doesn't allow custom 'Authorization' headers
dfuchs
parents:
56030
diff
changeset
|
169 |
* For example, "Content-Length", which will be determined by |
db102c5ca88a
http-client-branch: 8194729: Java 9's HttpClient doesn't allow custom 'Authorization' headers
dfuchs
parents:
56030
diff
changeset
|
170 |
* the request Publisher. In such a case, an implementation of |
db102c5ca88a
http-client-branch: 8194729: Java 9's HttpClient doesn't allow custom 'Authorization' headers
dfuchs
parents:
56030
diff
changeset
|
171 |
* {@code HttpRequest.Builder} may choose to throw an |
db102c5ca88a
http-client-branch: 8194729: Java 9's HttpClient doesn't allow custom 'Authorization' headers
dfuchs
parents:
56030
diff
changeset
|
172 |
* {@code IllegalArgumentException} if such a header is passed |
db102c5ca88a
http-client-branch: 8194729: Java 9's HttpClient doesn't allow custom 'Authorization' headers
dfuchs
parents:
56030
diff
changeset
|
173 |
* to the builder. |
db102c5ca88a
http-client-branch: 8194729: Java 9's HttpClient doesn't allow custom 'Authorization' headers
dfuchs
parents:
56030
diff
changeset
|
174 |
* |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
175 |
* @param name the header name |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
176 |
* @param value the header value |
56142 | 177 |
* @return this builder |
48083 | 178 |
* @throws IllegalArgumentException if the header name or value is not |
179 |
* valid, see <a href="https://tools.ietf.org/html/rfc7230#section-3.2"> |
|
56033
db102c5ca88a
http-client-branch: 8194729: Java 9's HttpClient doesn't allow custom 'Authorization' headers
dfuchs
parents:
56030
diff
changeset
|
180 |
* RFC 7230 section-3.2</a>, or the header name or value is restricted |
db102c5ca88a
http-client-branch: 8194729: Java 9's HttpClient doesn't allow custom 'Authorization' headers
dfuchs
parents:
56030
diff
changeset
|
181 |
* by the implementation. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
182 |
*/ |
56140 | 183 |
public Builder header(String name, String value); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
184 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
185 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
186 |
* Adds the given name value pairs to the set of headers for this |
48083 | 187 |
* request. The supplied {@code String} instances must alternate as |
188 |
* header names and header values. |
|
189 |
* To add several values to the same name then the same name must |
|
190 |
* be supplied with each new value. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
191 |
* |
48083 | 192 |
* @param headers the list of name value pairs |
56142 | 193 |
* @return this builder |
48083 | 194 |
* @throws IllegalArgumentException if there are an odd number of |
195 |
* parameters, or if a header name or value is not valid, see |
|
196 |
* <a href="https://tools.ietf.org/html/rfc7230#section-3.2"> |
|
56033
db102c5ca88a
http-client-branch: 8194729: Java 9's HttpClient doesn't allow custom 'Authorization' headers
dfuchs
parents:
56030
diff
changeset
|
197 |
* RFC 7230 section-3.2</a>, or a header name or value is |
db102c5ca88a
http-client-branch: 8194729: Java 9's HttpClient doesn't allow custom 'Authorization' headers
dfuchs
parents:
56030
diff
changeset
|
198 |
* {@linkplain #header(String, String) restricted} by the |
db102c5ca88a
http-client-branch: 8194729: Java 9's HttpClient doesn't allow custom 'Authorization' headers
dfuchs
parents:
56030
diff
changeset
|
199 |
* implementation. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
200 |
*/ |
56140 | 201 |
public Builder headers(String... headers); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
202 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
203 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
204 |
* Sets a timeout for this request. If the response is not received |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
205 |
* within the specified timeout then a {@link HttpTimeoutException} is |
56089
42208b2f224e
http-client-branch: move to standard package and module name
chegar
parents:
56088
diff
changeset
|
206 |
* thrown from {@link HttpClient#send(java.net.http.HttpRequest, |
42208b2f224e
http-client-branch: move to standard package and module name
chegar
parents:
56088
diff
changeset
|
207 |
* java.net.http.HttpResponse.BodyHandler) HttpClient::send} or |
42208b2f224e
http-client-branch: move to standard package and module name
chegar
parents:
56088
diff
changeset
|
208 |
* {@link HttpClient#sendAsync(java.net.http.HttpRequest, |
42208b2f224e
http-client-branch: move to standard package and module name
chegar
parents:
56088
diff
changeset
|
209 |
* java.net.http.HttpResponse.BodyHandler) HttpClient::sendAsync} |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
210 |
* completes exceptionally with a {@code HttpTimeoutException}. The effect |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
211 |
* of not setting a timeout is the same as setting an infinite Duration, ie. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
212 |
* block forever. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
213 |
* |
44847 | 214 |
* @param duration the timeout duration |
56142 | 215 |
* @return this builder |
48083 | 216 |
* @throws IllegalArgumentException if the duration is non-positive |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
217 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
218 |
public abstract Builder timeout(Duration duration); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
219 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
220 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
221 |
* Sets the given name value pair to the set of headers for this |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
222 |
* request. This overwrites any previously set values for name. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
223 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
224 |
* @param name the header name |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
225 |
* @param value the header value |
56142 | 226 |
* @return this builder |
48083 | 227 |
* @throws IllegalArgumentException if the header name or value is not valid, |
228 |
* see <a href="https://tools.ietf.org/html/rfc7230#section-3.2"> |
|
56033
db102c5ca88a
http-client-branch: 8194729: Java 9's HttpClient doesn't allow custom 'Authorization' headers
dfuchs
parents:
56030
diff
changeset
|
229 |
* RFC 7230 section-3.2</a>, or the header name or value is |
db102c5ca88a
http-client-branch: 8194729: Java 9's HttpClient doesn't allow custom 'Authorization' headers
dfuchs
parents:
56030
diff
changeset
|
230 |
* {@linkplain #header(String, String) restricted} by the |
db102c5ca88a
http-client-branch: 8194729: Java 9's HttpClient doesn't allow custom 'Authorization' headers
dfuchs
parents:
56030
diff
changeset
|
231 |
* implementation. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
232 |
*/ |
56140 | 233 |
public Builder setHeader(String name, String value); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
234 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
235 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
236 |
* Sets the request method of this builder to GET. |
48083 | 237 |
* This is the default. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
238 |
* |
56142 | 239 |
* @return this builder |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
240 |
*/ |
56140 | 241 |
public Builder GET(); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
242 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
243 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
244 |
* Sets the request method of this builder to POST and sets its |
48083 | 245 |
* request body publisher to the given value. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
246 |
* |
48083 | 247 |
* @param bodyPublisher the body publisher |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
248 |
* |
56142 | 249 |
* @return this builder |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
250 |
*/ |
56140 | 251 |
public Builder POST(BodyPublisher bodyPublisher); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
252 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
253 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
254 |
* Sets the request method of this builder to PUT and sets its |
48083 | 255 |
* request body publisher to the given value. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
256 |
* |
48083 | 257 |
* @param bodyPublisher the body publisher |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
258 |
* |
56142 | 259 |
* @return this builder |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
260 |
*/ |
56140 | 261 |
public Builder PUT(BodyPublisher bodyPublisher); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
262 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
263 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
264 |
* Sets the request method of this builder to DELETE and sets its |
48083 | 265 |
* request body publisher to the given value. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
266 |
* |
48083 | 267 |
* @param bodyPublisher the body publisher |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
268 |
* |
56142 | 269 |
* @return this builder |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
270 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
271 |
|
56140 | 272 |
public Builder DELETE(BodyPublisher bodyPublisher); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
273 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
274 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
275 |
* Sets the request method and request body of this builder to the |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
276 |
* given values. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
277 |
* |
56099
41ba54ac9403
http-client-branch: revert overzealous use of @linkplain
chegar
parents:
56097
diff
changeset
|
278 |
* @apiNote The {@link BodyPublisher#noBody() noBody} request |
48083 | 279 |
* body publisher can be used where no request body is required or |
56030
69fbcac27e35
http-client-branch: clarify behavior of restricted methods in the builder
chegar
parents:
56008
diff
changeset
|
280 |
* appropriate. Whether a method is restricted, or not, is |
69fbcac27e35
http-client-branch: clarify behavior of restricted methods in the builder
chegar
parents:
56008
diff
changeset
|
281 |
* implementation specific. For example, some implementations may choose |
69fbcac27e35
http-client-branch: clarify behavior of restricted methods in the builder
chegar
parents:
56008
diff
changeset
|
282 |
* to restrict the {@code CONNECT} method. |
48083 | 283 |
* |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
284 |
* @param method the method to use |
48083 | 285 |
* @param bodyPublisher the body publisher |
56142 | 286 |
* @return this builder |
56030
69fbcac27e35
http-client-branch: clarify behavior of restricted methods in the builder
chegar
parents:
56008
diff
changeset
|
287 |
* @throws IllegalArgumentException if the method is restricted |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
288 |
*/ |
56140 | 289 |
public Builder method(String method, BodyPublisher bodyPublisher); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
290 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
291 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
292 |
* Builds and returns a {@link HttpRequest}. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
293 |
* |
56142 | 294 |
* @return a new {@code HttpRequest} |
48083 | 295 |
* @throws IllegalStateException if a URI has not been set |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
296 |
*/ |
56140 | 297 |
public HttpRequest build(); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
298 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
299 |
/** |
48083 | 300 |
* Returns an exact duplicate copy of this {@code Builder} based on |
301 |
* current state. The new builder can then be modified independently of |
|
302 |
* this builder. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
303 |
* |
56142 | 304 |
* @return an exact copy of this builder |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
305 |
*/ |
56140 | 306 |
public Builder copy(); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
307 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
308 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
309 |
/** |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
310 |
* Creates an {@code HttpRequest} builder with the given URI. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
311 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
312 |
* @param uri the request URI |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
313 |
* @return a new request builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
314 |
* @throws IllegalArgumentException if the URI scheme is not supported. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
315 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
316 |
public static HttpRequest.Builder newBuilder(URI uri) { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
317 |
return new HttpRequestBuilderImpl(uri); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
318 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
319 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
320 |
/** |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
321 |
* Creates an {@code HttpRequest} builder. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
322 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
323 |
* @return a new request builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
324 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
325 |
public static HttpRequest.Builder newBuilder() { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
326 |
return new HttpRequestBuilderImpl(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
327 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
328 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
329 |
/** |
48083 | 330 |
* Returns an {@code Optional} containing the {@link BodyPublisher} set on |
331 |
* this request. If no {@code BodyPublisher} was set in the requests's |
|
332 |
* builder, then the {@code Optional} is empty. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
333 |
* |
48083 | 334 |
* @return an {@code Optional} containing this request's {@code BodyPublisher} |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
335 |
*/ |
48083 | 336 |
public abstract Optional<BodyPublisher> bodyPublisher(); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
337 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
338 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
339 |
* Returns the request method for this request. If not set explicitly, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
340 |
* the default method for any request is "GET". |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
341 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
342 |
* @return this request's method |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
343 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
344 |
public abstract String method(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
345 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
346 |
/** |
48083 | 347 |
* Returns an {@code Optional} containing this request's timeout duration. |
348 |
* If the timeout duration was not set in the request's builder, then the |
|
349 |
* {@code Optional} is empty. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
350 |
* |
48083 | 351 |
* @return an {@code Optional} containing this request's timeout duration |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
352 |
*/ |
48083 | 353 |
public abstract Optional<Duration> timeout(); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
354 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
355 |
/** |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
356 |
* Returns this request's {@linkplain HttpRequest.Builder#expectContinue(boolean) |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
357 |
* expect continue} setting. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
358 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
359 |
* @return this request's expect continue setting |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
360 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
361 |
public abstract boolean expectContinue(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
362 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
363 |
/** |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
364 |
* Returns this request's {@code URI}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
365 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
366 |
* @return this request's URI |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
367 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
368 |
public abstract URI uri(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
369 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
370 |
/** |
44854
5a486e0acd29
8175814: Update default HttpClient protocol version and optional request version
michaelm
parents:
44847
diff
changeset
|
371 |
* Returns an {@code Optional} containing the HTTP protocol version that |
5a486e0acd29
8175814: Update default HttpClient protocol version and optional request version
michaelm
parents:
44847
diff
changeset
|
372 |
* will be requested for this {@code HttpRequest}. If the version was not |
5a486e0acd29
8175814: Update default HttpClient protocol version and optional request version
michaelm
parents:
44847
diff
changeset
|
373 |
* set in the request's builder, then the {@code Optional} is empty. |
5a486e0acd29
8175814: Update default HttpClient protocol version and optional request version
michaelm
parents:
44847
diff
changeset
|
374 |
* In that case, the version requested will be that of the sending |
5a486e0acd29
8175814: Update default HttpClient protocol version and optional request version
michaelm
parents:
44847
diff
changeset
|
375 |
* {@link HttpClient}. The corresponding {@link HttpResponse} should be |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
376 |
* queried to determine the version that was actually used. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
377 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
378 |
* @return HTTP protocol version |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
379 |
*/ |
44854
5a486e0acd29
8175814: Update default HttpClient protocol version and optional request version
michaelm
parents:
44847
diff
changeset
|
380 |
public abstract Optional<HttpClient.Version> version(); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
381 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
382 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
383 |
* The (user-accessible) request headers that this request was (or will be) |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
384 |
* sent with. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
385 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
386 |
* @return this request's HttpHeaders |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
387 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
388 |
public abstract HttpHeaders headers(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
389 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
390 |
/** |
48083 | 391 |
* Tests this HTTP request instance for equality with the given object. |
392 |
* |
|
393 |
* <p> If the given object is not an {@code HttpRequest} then this |
|
394 |
* method returns {@code false}. Two HTTP requests are equal if their URI, |
|
395 |
* method, and headers fields are all equal. |
|
396 |
* |
|
397 |
* <p> This method satisfies the general contract of the {@link |
|
398 |
* Object#equals(Object) Object.equals} method. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
399 |
* |
48083 | 400 |
* @param obj the object to which this object is to be compared |
401 |
* @return {@code true} if, and only if, the given object is an {@code |
|
402 |
* HttpRequest} that is equal to this HTTP request |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
403 |
*/ |
48083 | 404 |
@Override |
405 |
public final boolean equals(Object obj) { |
|
406 |
if (! (obj instanceof HttpRequest)) |
|
407 |
return false; |
|
408 |
HttpRequest that = (HttpRequest)obj; |
|
409 |
if (!that.method().equals(this.method())) |
|
410 |
return false; |
|
411 |
if (!that.uri().equals(this.uri())) |
|
412 |
return false; |
|
413 |
if (!that.headers().equals(this.headers())) |
|
414 |
return false; |
|
415 |
return true; |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
416 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
417 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
418 |
/** |
48083 | 419 |
* Computes a hash code for this HTTP request instance. |
420 |
* |
|
421 |
* <p> The hash code is based upon the HTTP request's URI, method, and |
|
422 |
* header components, and satisfies the general contract of the |
|
423 |
* {@link Object#hashCode Object.hashCode} method. |
|
424 |
* |
|
425 |
* @return the hash-code value for this HTTP request |
|
426 |
*/ |
|
427 |
public final int hashCode() { |
|
428 |
return method().hashCode() |
|
429 |
+ uri().hashCode() |
|
430 |
+ headers().hashCode(); |
|
431 |
} |
|
432 |
||
433 |
/** |
|
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
434 |
* A {@code BodyPublisher} converts high-level Java objects into a flow of |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
435 |
* byte buffers suitable for sending as a request body. |
48083 | 436 |
* |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
437 |
* <p> The {@code BodyPublisher} interface extends {@link Flow.Publisher |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
438 |
* Flow.Publisher<ByteBuffer>}, which means that a {@code BodyPublisher} |
48083 | 439 |
* acts as a publisher of {@linkplain ByteBuffer byte buffers}. |
440 |
* |
|
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
441 |
* <p> When sending a request that contains a body, the HTTP Client |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
442 |
* subscribes to the request's {@code BodyPublisher} in order to receive the |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
443 |
* flow of outgoing request body data. The normal semantics of {@link |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
444 |
* Flow.Subscriber} and {@link Flow.Publisher} are implemented by the HTTP |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
445 |
* Client and are expected from {@code BodyPublisher} implementations. Each |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
446 |
* outgoing request results in one HTTP Client {@code Subscriber} |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
447 |
* subscribing to the {@code BodyPublisher} in order to provide the sequence |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
448 |
* of byte buffers containing the request body. Instances of {@code |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
449 |
* ByteBuffer} published by the publisher must be allocated by the |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
450 |
* publisher, and must not be accessed after being published to the HTTP |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
451 |
* Client. These subscriptions complete normally when the request body is |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
452 |
* fully sent, and can be canceled or terminated early through error. If a |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
453 |
* request needs to be resent for any reason, then a new subscription is |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
454 |
* created which is expected to generate the same data as before. |
48083 | 455 |
* |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
456 |
* <p> A {@code BodyPublisher} that reports a {@linkplain #contentLength() |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
457 |
* content length} of {@code 0} may not be subscribed to by the HTTP Client, |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
458 |
* as it has effectively no data to publish. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
459 |
*/ |
48083 | 460 |
public interface BodyPublisher extends Flow.Publisher<ByteBuffer> { |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
461 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
462 |
/** |
48408
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
463 |
* Returns a request body publisher whose body is retrieved from the |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
464 |
* given {@code Flow.Publisher}. The returned request body publisher |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
465 |
* has an unknown content length. |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
466 |
* |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
467 |
* @apiNote This method can be used as an adapter between {@code |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
468 |
* BodyPublisher} and {@code Flow.Publisher}, where the amount of |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
469 |
* request body that the publisher will publish is unknown. |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
470 |
* |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
471 |
* @param publisher the publisher responsible for publishing the body |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
472 |
* @return a BodyPublisher |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
473 |
*/ |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
474 |
static BodyPublisher fromPublisher(Flow.Publisher<? extends ByteBuffer> publisher) { |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
475 |
return new RequestPublishers.PublisherAdapter(publisher, -1L); |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
476 |
} |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
477 |
|
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
478 |
/** |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
479 |
* Returns a request body publisher whose body is retrieved from the |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
480 |
* given {@code Flow.Publisher}. The returned request body publisher |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
481 |
* has the given content length. |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
482 |
* |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
483 |
* <p> The given {@code contentLength} is a positive number, that |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
484 |
* represents the exact amount of bytes the {@code publisher} must |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
485 |
* publish. |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
486 |
* |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
487 |
* @apiNote This method can be used as an adapter between {@code |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
488 |
* BodyPublisher} and {@code Flow.Publisher}, where the amount of |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
489 |
* request body that the publisher will publish is known. |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
490 |
* |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
491 |
* @param publisher the publisher responsible for publishing the body |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
492 |
* @param contentLength a positive number representing the exact |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
493 |
* amount of bytes the publisher will publish |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
494 |
* @throws IllegalArgumentException if the content length is |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
495 |
* non-positive |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
496 |
* @return a BodyPublisher |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
497 |
*/ |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
498 |
static BodyPublisher fromPublisher(Flow.Publisher<? extends ByteBuffer> publisher, |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
499 |
long contentLength) { |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
500 |
if (contentLength < 1) |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
501 |
throw new IllegalArgumentException("non-positive contentLength: " + contentLength); |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
502 |
return new RequestPublishers.PublisherAdapter(publisher, contentLength); |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
503 |
} |
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
504 |
|
4f830b447edf
8193365: Improve interoperability between HTTP Client's BodyPublisher/BodySubscriber and Flow.Subscriber/Publisher
chegar
parents:
48083
diff
changeset
|
505 |
/** |
48083 | 506 |
* Returns a request body publisher whose body is the given {@code |
507 |
* String}, converted using the {@link StandardCharsets#UTF_8 UTF_8} |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
508 |
* character set. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
509 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
510 |
* @param body the String containing the body |
48083 | 511 |
* @return a BodyPublisher |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
512 |
*/ |
48083 | 513 |
static BodyPublisher fromString(String body) { |
514 |
return fromString(body, UTF_8); |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
515 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
516 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
517 |
/** |
48083 | 518 |
* Returns a request body publisher whose body is the given {@code |
519 |
* String}, converted using the given character set. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
520 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
521 |
* @param s the String containing the body |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
522 |
* @param charset the character set to convert the string to bytes |
48083 | 523 |
* @return a BodyPublisher |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
524 |
*/ |
48083 | 525 |
static BodyPublisher fromString(String s, Charset charset) { |
526 |
return new RequestPublishers.StringPublisher(s, charset); |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
527 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
528 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
529 |
/** |
48083 | 530 |
* A request body publisher that reads its data from an {@link |
531 |
* InputStream}. A {@link Supplier} of {@code InputStream} is used in |
|
532 |
* case the request needs to be repeated, as the content is not buffered. |
|
533 |
* The {@code Supplier} may return {@code null} on subsequent attempts, |
|
534 |
* in which case the request fails. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
535 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
536 |
* @param streamSupplier a Supplier of open InputStreams |
48083 | 537 |
* @return a BodyPublisher |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
538 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
539 |
// TODO (spec): specify that the stream will be closed |
48083 | 540 |
static BodyPublisher fromInputStream(Supplier<? extends InputStream> streamSupplier) { |
541 |
return new RequestPublishers.InputStreamPublisher(streamSupplier); |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
542 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
543 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
544 |
/** |
48083 | 545 |
* Returns a request body publisher whose body is the given byte array. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
546 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
547 |
* @param buf the byte array containing the body |
48083 | 548 |
* @return a BodyPublisher |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
549 |
*/ |
48083 | 550 |
static BodyPublisher fromByteArray(byte[] buf) { |
551 |
return new RequestPublishers.ByteArrayPublisher(buf); |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
552 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
553 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
554 |
/** |
48083 | 555 |
* Returns a request body publisher whose body is the content of the |
556 |
* given byte array of {@code length} bytes starting from the specified |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
557 |
* {@code offset}. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
558 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
559 |
* @param buf the byte array containing the body |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
560 |
* @param offset the offset of the first byte |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
561 |
* @param length the number of bytes to use |
48083 | 562 |
* @return a BodyPublisher |
563 |
* @throws IndexOutOfBoundsException if the sub-range is defined to be |
|
564 |
* out-of-bounds |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
565 |
*/ |
48083 | 566 |
static BodyPublisher fromByteArray(byte[] buf, int offset, int length) { |
567 |
Objects.checkFromIndexSize(offset, length, buf.length); |
|
568 |
return new RequestPublishers.ByteArrayPublisher(buf, offset, length); |
|
569 |
} |
|
570 |
||
571 |
private static String pathForSecurityCheck(Path path) { |
|
572 |
return path.toFile().getPath(); |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
573 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
574 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
575 |
/** |
48083 | 576 |
* A request body publisher that takes data from the contents of a File. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
577 |
* |
56138
4f92b988600e
http-client-branch: HTTP Client file publishers, handlers, and subscribers as capability objects
chegar
parents:
56099
diff
changeset
|
578 |
* <p> Security manager permission checks are performed in this factory |
56141 | 579 |
* method, when the {@code BodyPublisher} is created. Care must be taken |
56138
4f92b988600e
http-client-branch: HTTP Client file publishers, handlers, and subscribers as capability objects
chegar
parents:
56099
diff
changeset
|
580 |
* that the {@code BodyPublisher} is not shared with untrusted code. |
4f92b988600e
http-client-branch: HTTP Client file publishers, handlers, and subscribers as capability objects
chegar
parents:
56099
diff
changeset
|
581 |
* |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
582 |
* @param path the path to the file containing the body |
48083 | 583 |
* @return a BodyPublisher |
584 |
* @throws java.io.FileNotFoundException if the path is not found |
|
585 |
* @throws SecurityException if a security manager has been installed |
|
586 |
* and it denies {@link SecurityManager#checkRead(String) |
|
587 |
* read access} to the given file |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
588 |
*/ |
48083 | 589 |
static BodyPublisher fromFile(Path path) throws FileNotFoundException { |
590 |
Objects.requireNonNull(path); |
|
591 |
SecurityManager sm = System.getSecurityManager(); |
|
592 |
if (sm != null) |
|
593 |
sm.checkRead(pathForSecurityCheck(path)); |
|
594 |
if (Files.notExists(path)) |
|
595 |
throw new FileNotFoundException(path + " not found"); |
|
596 |
return new RequestPublishers.FilePublisher(path); |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
597 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
598 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
599 |
/** |
48083 | 600 |
* A request body publisher that takes data from an {@code Iterable} |
601 |
* of byte arrays. An {@link Iterable} is provided which supplies |
|
602 |
* {@link Iterator} instances. Each attempt to send the request results |
|
603 |
* in one invocation of the {@code Iterable}. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
604 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
605 |
* @param iter an Iterable of byte arrays |
48083 | 606 |
* @return a BodyPublisher |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
607 |
*/ |
48083 | 608 |
static BodyPublisher fromByteArrays(Iterable<byte[]> iter) { |
609 |
return new RequestPublishers.IterablePublisher(iter); |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
610 |
} |
48083 | 611 |
|
612 |
/** |
|
613 |
* A request body publisher which sends no request body. |
|
614 |
* |
|
615 |
* @return a BodyPublisher which completes immediately and sends |
|
616 |
* no request body. |
|
617 |
*/ |
|
618 |
static BodyPublisher noBody() { |
|
619 |
return new RequestPublishers.EmptyPublisher(); |
|
620 |
} |
|
621 |
||
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
622 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
623 |
* Returns the content length for this request body. May be zero |
48083 | 624 |
* if no request body being sent, greater than zero for a fixed |
625 |
* length content, or less than zero for an unknown content length. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
626 |
* |
48083 | 627 |
* This method may be invoked before the publisher is subscribed to. |
628 |
* This method may be invoked more than once by the HTTP client |
|
629 |
* implementation, and MUST return the same constant value each time. |
|
630 |
* |
|
631 |
* @return the content length for this request body, if known |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
632 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
633 |
long contentLength(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
634 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
635 |
} |