605 * {@link Flow.Subscriber} and {@link Flow.Publisher} are implemented by the
606 * library and are expected from publisher implementations. Each outgoing
607 * request results in one {@code Subscriber} subscribing to the {@code
608 * BodyPublisher} in order to provide the sequence of byte buffers
609 * containing the request body.
610 * Instances of {@code ByteBuffer} published by the publisher must be
611 * allocated by the publisher, and must not be accessed after being handed
612 * over to the library.
613 * These subscriptions complete normally when the request is fully sent,
614 * and can be canceled or terminated early through error. If a request
615 * needs to be resent for any reason, then a new subscription is created
616 * which is expected to generate the same data as before.
617 *
618 * <p> A publisher that reports a {@linkplain #contentLength() content
619 * length} of {@code 0} may not be subscribed to by the HTTP client
620 * implementation, as it has effectively no data to publish.
621 */
622 public interface BodyPublisher extends Flow.Publisher<ByteBuffer> {
623
624 /**
625 * Returns a request body publisher whose body is the given {@code
626 * String}, converted using the {@link StandardCharsets#UTF_8 UTF_8}
627 * character set.
628 *
629 * @param body the String containing the body
630 * @return a BodyPublisher
631 */
632 static BodyPublisher fromString(String body) {
633 return fromString(body, UTF_8);
634 }
635
636 /**
637 * Returns a request body publisher whose body is the given {@code
638 * String}, converted using the given character set.
639 *
640 * @param s the String containing the body
641 * @param charset the character set to convert the string to bytes
642 * @return a BodyPublisher
643 */
644 static BodyPublisher fromString(String s, Charset charset) {
|
605 * {@link Flow.Subscriber} and {@link Flow.Publisher} are implemented by the
606 * library and are expected from publisher implementations. Each outgoing
607 * request results in one {@code Subscriber} subscribing to the {@code
608 * BodyPublisher} in order to provide the sequence of byte buffers
609 * containing the request body.
610 * Instances of {@code ByteBuffer} published by the publisher must be
611 * allocated by the publisher, and must not be accessed after being handed
612 * over to the library.
613 * These subscriptions complete normally when the request is fully sent,
614 * and can be canceled or terminated early through error. If a request
615 * needs to be resent for any reason, then a new subscription is created
616 * which is expected to generate the same data as before.
617 *
618 * <p> A publisher that reports a {@linkplain #contentLength() content
619 * length} of {@code 0} may not be subscribed to by the HTTP client
620 * implementation, as it has effectively no data to publish.
621 */
622 public interface BodyPublisher extends Flow.Publisher<ByteBuffer> {
623
624 /**
625 * Returns a request body publisher whose body is retrieved from the
626 * given {@code Flow.Publisher}. The returned request body publisher
627 * has an unknown content length.
628 *
629 * @apiNote This method can be used as an adapter between {@code
630 * BodyPublisher} and {@code Flow.Publisher}, where the amount of
631 * request body that the publisher will publish is unknown.
632 *
633 * @param publisher the publisher responsible for publishing the body
634 * @return a BodyPublisher
635 */
636 static BodyPublisher fromPublisher(Flow.Publisher<? extends ByteBuffer> publisher) {
637 return new RequestPublishers.PublisherAdapter(publisher, -1L);
638 }
639
640 /**
641 * Returns a request body publisher whose body is retrieved from the
642 * given {@code Flow.Publisher}. The returned request body publisher
643 * has the given content length.
644 *
645 * <p> The given {@code contentLength} is a positive number, that
646 * represents the exact amount of bytes the {@code publisher} must
647 * publish.
648 *
649 * @apiNote This method can be used as an adapter between {@code
650 * BodyPublisher} and {@code Flow.Publisher}, where the amount of
651 * request body that the publisher will publish is known.
652 *
653 * @param publisher the publisher responsible for publishing the body
654 * @param contentLength a positive number representing the exact
655 * amount of bytes the publisher will publish
656 * @throws IllegalArgumentException if the content length is
657 * non-positive
658 * @return a BodyPublisher
659 */
660 static BodyPublisher fromPublisher(Flow.Publisher<? extends ByteBuffer> publisher,
661 long contentLength) {
662 if (contentLength < 1)
663 throw new IllegalArgumentException("non-positive contentLength: " + contentLength);
664 return new RequestPublishers.PublisherAdapter(publisher, contentLength);
665 }
666
667 /**
668 * Returns a request body publisher whose body is the given {@code
669 * String}, converted using the {@link StandardCharsets#UTF_8 UTF_8}
670 * character set.
671 *
672 * @param body the String containing the body
673 * @return a BodyPublisher
674 */
675 static BodyPublisher fromString(String body) {
676 return fromString(body, UTF_8);
677 }
678
679 /**
680 * Returns a request body publisher whose body is the given {@code
681 * String}, converted using the given character set.
682 *
683 * @param s the String containing the body
684 * @param charset the character set to convert the string to bytes
685 * @return a BodyPublisher
686 */
687 static BodyPublisher fromString(String s, Charset charset) {
|