< prev index next >

src/java.net.http/share/classes/java/net/http/HttpRequest.java

Print this page

 19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 20  *
 21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 22  * or visit www.oracle.com if you need additional information or have any
 23  * questions.
 24  */
 25 
 26 package java.net.http;
 27 
 28 import java.io.FileNotFoundException;
 29 import java.io.InputStream;
 30 import java.net.URI;
 31 import java.nio.ByteBuffer;
 32 import java.nio.charset.Charset;
 33 import java.nio.charset.StandardCharsets;
 34 import java.nio.file.Files;
 35 import java.nio.file.OpenOption;
 36 import java.nio.file.Path;
 37 import java.time.Duration;
 38 import java.util.Iterator;


 39 import java.util.Objects;
 40 import java.util.Optional;
 41 import java.util.concurrent.Flow;

 42 import java.util.function.Supplier;
 43 import jdk.internal.net.http.HttpRequestBuilderImpl;
 44 import jdk.internal.net.http.RequestPublishers;
 45 import static java.nio.charset.StandardCharsets.UTF_8;
 46 
 47 /**
 48  * An HTTP request.
 49  *
 50  * <p> An {@code HttpRequest} instance is built through an {@code HttpRequest}
 51  * {@linkplain HttpRequest.Builder builder}. An {@code HttpRequest} builder
 52  * is obtained from one of the {@link HttpRequest#newBuilder(URI) newBuilder}
 53  * methods. A request's {@link URI}, headers, and body can be set. Request
 54  * bodies are provided through a {@link BodyPublisher BodyPublisher} supplied
 55  * to one of the {@link Builder#POST(BodyPublisher) POST},
 56  * {@link Builder#PUT(BodyPublisher) PUT} or
 57  * {@link Builder#method(String,BodyPublisher) method} methods.
 58  * Once all required parameters have been set in the builder, {@link
 59  * Builder#build() build} will return the {@code HttpRequest}. Builders can be
 60  * copied and modified many times in order to build multiple related requests
 61  * that differ in some parameters.

637          * of byte arrays. An {@link Iterable} is provided which supplies
638          * {@link Iterator} instances. Each attempt to send the request results
639          * in one invocation of the {@code Iterable}.
640          *
641          * @param iter an Iterable of byte arrays
642          * @return a BodyPublisher
643          */
644         public static BodyPublisher ofByteArrays(Iterable<byte[]> iter) {
645             return new RequestPublishers.IterablePublisher(iter);
646         }
647 
648         /**
649          * A request body publisher which sends no request body.
650          *
651          * @return a BodyPublisher which completes immediately and sends
652          *         no request body.
653          */
654         public static BodyPublisher noBody() {
655             return new RequestPublishers.EmptyPublisher();
656         }












































































657     }
658 }

 19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 20  *
 21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 22  * or visit www.oracle.com if you need additional information or have any
 23  * questions.
 24  */
 25 
 26 package java.net.http;
 27 
 28 import java.io.FileNotFoundException;
 29 import java.io.InputStream;
 30 import java.net.URI;
 31 import java.nio.ByteBuffer;
 32 import java.nio.charset.Charset;
 33 import java.nio.charset.StandardCharsets;
 34 import java.nio.file.Files;
 35 import java.nio.file.OpenOption;
 36 import java.nio.file.Path;
 37 import java.time.Duration;
 38 import java.util.Iterator;
 39 import java.util.List;
 40 import java.util.Map;
 41 import java.util.Objects;
 42 import java.util.Optional;
 43 import java.util.concurrent.Flow;
 44 import java.util.function.BiFunction;
 45 import java.util.function.Supplier;
 46 import jdk.internal.net.http.HttpRequestBuilderImpl;
 47 import jdk.internal.net.http.RequestPublishers;
 48 import static java.nio.charset.StandardCharsets.UTF_8;
 49 
 50 /**
 51  * An HTTP request.
 52  *
 53  * <p> An {@code HttpRequest} instance is built through an {@code HttpRequest}
 54  * {@linkplain HttpRequest.Builder builder}. An {@code HttpRequest} builder
 55  * is obtained from one of the {@link HttpRequest#newBuilder(URI) newBuilder}
 56  * methods. A request's {@link URI}, headers, and body can be set. Request
 57  * bodies are provided through a {@link BodyPublisher BodyPublisher} supplied
 58  * to one of the {@link Builder#POST(BodyPublisher) POST},
 59  * {@link Builder#PUT(BodyPublisher) PUT} or
 60  * {@link Builder#method(String,BodyPublisher) method} methods.
 61  * Once all required parameters have been set in the builder, {@link
 62  * Builder#build() build} will return the {@code HttpRequest}. Builders can be
 63  * copied and modified many times in order to build multiple related requests
 64  * that differ in some parameters.

640          * of byte arrays. An {@link Iterable} is provided which supplies
641          * {@link Iterator} instances. Each attempt to send the request results
642          * in one invocation of the {@code Iterable}.
643          *
644          * @param iter an Iterable of byte arrays
645          * @return a BodyPublisher
646          */
647         public static BodyPublisher ofByteArrays(Iterable<byte[]> iter) {
648             return new RequestPublishers.IterablePublisher(iter);
649         }
650 
651         /**
652          * A request body publisher which sends no request body.
653          *
654          * @return a BodyPublisher which completes immediately and sends
655          *         no request body.
656          */
657         public static BodyPublisher noBody() {
658             return new RequestPublishers.EmptyPublisher();
659         }
660 
661         // -- Minimal piece of low-level machinery
662 
663         /**
664          * A request body publisher which publishes items emitted by each of the
665          * given request body publishers, one after the other, without
666          * interleaving.
667          *
668          * // TODO: tighten spec, subscribe to each publisher in turn, drain,
669          * // to onComplete, next... Any error encountered is propagated and
670          * // no further activity, etc ...
671          * // The content-length of the returned publisher will be that of the
672          * // accumulated publisher lengths, unless any is unknown in which case
673          * // the returned publisher's content-length is unknown.
674          *
675          * @param publishers an array of request body publishers
676          * @return a BodyPublisher composed of the given publishers
677          * @throws IllegalArgumentException if publishers array is less than 2
678          */
679         public static BodyPublisher concat(BodyPublisher... publishers) {
680             Objects.requireNonNull(publishers);
681             if (publishers.length < 2)
682                 throw new IllegalArgumentException("error");
683 
684             return null; // TODO implement
685         }
686 
687         // -- The following are three alternatives to support multipart common syntax
688 
689         /**
690          * A multipart part!  Alternative #1 requires a carrier tuple (Uck!)
691          *
692          * @headers the, possibly empty, part's headers  << headers are optional
693          * @publisher the non-null part's publisher
694          */
695         public static record Part(HttpHeaders headers, BodyPublisher publisher) { }
696 
697         /**
698          * A multipart request body publisher...
699          *
700          * Publishes each of the given parts, one after another, in order. Each
701          * part is separated by the given boundary.
702          *
703          * // TODO: tighten spec, content-length?, etc
704          *
705          * TODO: supports the multipart common syntax, see https://tools.ietf.org/html/rfc2046#section-5.1.1
706          *
707          * One can embed multipart inside multipart - verify
708          *
709          * @param boundary a non-null boundary
710          * @param parts an non-null array of multipart parts
711          * @throws IllegalArgumentException if boundary not less than 70 chars ...
712          *         if parts does not contain at least one element ...
713          * @return a multipart BodyPublisher
714          */
715         // Alternative #1
716         public static BodyPublisher ofMultipart(String boundary, Part... parts) {
717             return null; // TODO implement
718         }
719 
720         // Alternative #2
721         public static BodyPublisher ofMultipart2(String boundary,
722                                                  List<Map.Entry<HttpHeaders,BodyPublisher>> parts) {
723             return null; // TODO implement
724         }
725 
726         // Alternative #3
727         public static BodyPublisher ofMultipart3(String boundary,
728                                                  BodyPublisher... parts) {  // this is ambiguous(ish) OR maybe not, default ascii/text?
729             return null; // TODO implement
730         }
731 
732         public static BodyPublisher multipartPart(HttpHeaders headers,  // what a name!
733                                                   BodyPublisher publisher) {
734             return concat(ofString(headers.toString()), publisher);  // Argh! header to string representation
735         }
736     }
737 }
< prev index next >