Module methanol
Package com.github.mizosoft.methanol

Class MutableRequest

  • All Implemented Interfaces:
    HeadersAccumulator<MutableRequest>, TaggableRequest.Builder, java.net.http.HttpRequest.Builder
    public final class MutableRequest
extends TaggableRequest
implements TaggableRequest.Builder, HeadersAccumulator<MutableRequest>
    A mutable HttpRequest that supports tags, relative URIs & setting arbitrary objects as request bodies. This class implements HttpRequest.Builder for setting request fields. Querying a field before it's been set will return its default value. Invoking toImmutableRequest() will return an immutable copy that is independent of this instance.

    MutableRequest accepts an arbitrary object as the request body, referred to as the payload. The payload is resolved into a BodyPublisher only when one is requested. Resolution is done by this request's AdapterCodec. Sending the request through a Methanol client with an AdapterCodec sets the request's AdapterCodec automatically if one is not already present. Note that a request with an AdapterCodec overrides the client's AdapterCodec both for encoding the request body and decoding the response body.

    Additionally, this class allows setting a URI without a host or a scheme or not setting a URI at all. This is for the case when the request is used with a Methanol client that has a base URL, against which this request's URL is resolved.

    MutableRequest also adds some convenience when the HttpRequest is used immediately after creation: 

    
 client.send(
     MutableRequest
         .GET("https://www.google.com/search?q=java")
         .header("Accept", "text/html"),
     BodyHandlers.ofString());
    It is recommended, however, to use toImmutableRequest() if the request is stored somewhere before it's sent in order to prevent accidental mutation, especially when the request is sent asynchronously.

    • Nested Class Summary

      • Nested classes/interfaces inherited from class java.net.http.HttpRequest

        java.net.http.HttpRequest.BodyPublisher, java.net.http.HttpRequest.BodyPublishers

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.util.Optional<AdapterCodec> adapterCodec()
      Returns the AdapterCodec to be used for resolving this request's payload.
      MutableRequest adapterCodec​(AdapterCodec adapterCodec)
      Set's the AdapterCodec to be used for resolving this request's payload.
      MutableRequest apply​(java.util.function.Consumer<? super MutableRequest> consumer)
      Calls the given consumer against this request.
      java.util.Optional<java.net.http.HttpRequest.BodyPublisher> bodyPublisher()  
      TaggableRequest build()
      Returns an immutable copy of this request.
      MutableRequest cacheControl​(CacheControl cacheControl)
      Sets the Cache-Control header to the given value.
      MutableRequest copy()
      Returns a copy of this request that is independent of this instance.
      static MutableRequest copyOf​(java.net.http.HttpRequest other)
      Returns a new MutableRequest that is a copy of the given request.
      static MutableRequest create()
      Returns a new MutableRequest.
      static MutableRequest create​(java.lang.String uri)
      Returns a new MutableRequest with the given URI and a default GET method.
      static MutableRequest create​(java.net.URI uri)
      Returns a new MutableRequest with the given URI and a default GET method.
      MutableRequest DELETE()  
      static MutableRequest DELETE​(java.lang.String uri)
      Returns a new MutableRequest with the given URI and a DELETE method.
      static MutableRequest DELETE​(java.net.URI uri)
      Returns a new MutableRequest with the given URI and a DELETE method.
      boolean expectContinue()  
      MutableRequest expectContinue​(boolean enable)  
      MutableRequest GET()  
      static MutableRequest GET​(java.lang.String uri)
      Returns a new MutableRequest with the given URI and a GET method.
      static MutableRequest GET​(java.net.URI uri)
      Returns a new MutableRequest with the given URI and a GET method.
      MutableRequest HEAD()  
      static MutableRequest HEAD​(java.lang.String uri)
      Returns a new MutableRequest with the given URI and a HEAD method.
      static MutableRequest HEAD​(java.net.URI uri)
      Returns a new MutableRequest with the given URI and a HEAD method.
      MutableRequest header​(java.lang.String name, java.lang.String value)
      Adds the given header name-value pair.
      java.net.http.HttpHeaders headers()  
      MutableRequest headers​(java.lang.String... headers)
      Adds each of the given header name-value pairs.
      MutableRequest headers​(java.net.http.HttpHeaders headers)
      Adds each of the given HttpHeaders.
      <T> MutableRequest hint​(java.lang.Class<T> type, T value)
      Adds the given value to this request's BodyAdapter.Hints.
      BodyAdapter.Hints hints()
      Returns this request's BodyAdapter.Hints.
      MutableRequest hints​(java.util.function.Consumer<BodyAdapter.Hints.Builder> hintsMutator)
      Modifies this request's BodyAdapter.Hints by mutating a BodyAdapter.Hints.Builder.
      java.lang.String method()  
      MutableRequest method​(java.lang.String method, java.lang.Object payload, MediaType mediaType)
      Sets the request method and sets the payload to the given value.
      MutableRequest method​(java.lang.String method, java.net.http.HttpRequest.BodyPublisher bodyPublisher)  
      <T> MutableRequest method​(java.lang.String method, T payload, TypeRef<T> typeRef, MediaType mediaType)
      Sets the request method and sets the payload to the given value with an explicitly specified type.
      java.util.Optional<com.github.mizosoft.methanol.MimeBody> mimeBody()  
      MutableRequest PATCH​(java.lang.Object payload, MediaType mediaType)
      Sets the request method to PATCH and sets the payload to the given value.
      static MutableRequest PATCH​(java.lang.String uri, java.lang.Object payload, MediaType mediaType)
      Returns a new MutableRequest with the given URI and a PATCH method.
      static MutableRequest PATCH​(java.lang.String uri, java.net.http.HttpRequest.BodyPublisher bodyPublisher)
      Returns a new MutableRequest with the given URI and a PATCH method.
      static <T> MutableRequest PATCH​(java.lang.String uri, T payload, TypeRef<T> typeRef, MediaType mediaType)
      Returns a new MutableRequest with the given URI and a PATCH method.
      MutableRequest PATCH​(java.net.http.HttpRequest.BodyPublisher bodyPublisher)
      Sets the request method to PATCH and sets the body publisher to the given value.
      static MutableRequest PATCH​(java.net.URI uri, java.lang.Object payload, MediaType mediaType)
      Returns a new MutableRequest with the given URI and a PATCH method.
      static MutableRequest PATCH​(java.net.URI uri, java.net.http.HttpRequest.BodyPublisher bodyPublisher)
      Returns a new MutableRequest with the given URI and a PATCH method.
      static <T> MutableRequest PATCH​(java.net.URI uri, T payload, TypeRef<T> typeRef, MediaType mediaType)
      Returns a new MutableRequest with the given URI and a PATCH method.
      <T> MutableRequest PATCH​(T payload, TypeRef<T> typeRef, MediaType mediaType)
      Sets the request method to PATCH and sets the payload to the given value with an explicitly specified type.
      MutableRequest POST​(java.lang.Object payload, MediaType mediaType)
      Sets the request method to POST and sets the payload to the given value.
      static MutableRequest POST​(java.lang.String uri, java.lang.Object payload, MediaType mediaType)
      Returns a new MutableRequest with the given URI and a POST method.
      static MutableRequest POST​(java.lang.String uri, java.net.http.HttpRequest.BodyPublisher bodyPublisher)
      Returns a new MutableRequest with the given URI and a POST method.
      static <T> MutableRequest POST​(java.lang.String uri, T payload, TypeRef<T> typeRef, MediaType mediaType)
      Returns a new MutableRequest with the given URI and a POST method.
      MutableRequest POST​(java.net.http.HttpRequest.BodyPublisher bodyPublisher)  
      static MutableRequest POST​(java.net.URI uri, java.lang.Object payload, MediaType mediaType)
      Returns a new MutableRequest with the given URI and a POST method.
      static MutableRequest POST​(java.net.URI uri, java.net.http.HttpRequest.BodyPublisher bodyPublisher)
      Returns a new MutableRequest with the given URI and a POST method.
      static <T> MutableRequest POST​(java.net.URI uri, T payload, TypeRef<T> typeRef, MediaType mediaType)
      Returns a new MutableRequest with the given URI and a POST method.
      <T> MutableRequest POST​(T payload, TypeRef<T> typeRef, MediaType mediaType)
      Sets the request method to POST and sets the payload to the given value with an explicitly specified type.
      MutableRequest PUT​(java.lang.Object payload, MediaType mediaType)
      Sets the request method to PUT and sets the payload to the given value.
      static MutableRequest PUT​(java.lang.String uri, java.lang.Object payload, MediaType mediaType)
      Returns a new MutableRequest with the given URI and a PUT method.
      static MutableRequest PUT​(java.lang.String uri, java.net.http.HttpRequest.BodyPublisher bodyPublisher)
      Returns a new MutableRequest with the given URI and a PUT method.
      static <T> MutableRequest PUT​(java.lang.String uri, T payload, TypeRef<T> typeRef, MediaType mediaType)
      Returns a new MutableRequest with the given URI and a PUT method.
      MutableRequest PUT​(java.net.http.HttpRequest.BodyPublisher bodyPublisher)  
      static MutableRequest PUT​(java.net.URI uri, java.lang.Object payload, MediaType mediaType)
      Returns a new MutableRequest with the given URI and a PUT method.
      static MutableRequest PUT​(java.net.URI uri, java.net.http.HttpRequest.BodyPublisher bodyPublisher)
      Returns a new MutableRequest with the given URI and a PUT method.
      static <T> MutableRequest PUT​(java.net.URI uri, T payload, TypeRef<T> typeRef, MediaType mediaType)
      Returns a new MutableRequest with the given URI and a PUT method.
      <T> MutableRequest PUT​(T payload, TypeRef<T> typeRef, MediaType mediaType)
      Sets the request method to PUT and sets the payload to the given value with an explicitly specified type.
      MutableRequest removeHeader​(java.lang.String name)
      Removes any header associated with the given name.
      MutableRequest removeHeaders()
      Removes all headers added so far.
      MutableRequest removeHeadersIf​(java.util.function.BiPredicate<java.lang.String,​java.lang.String> filter)
      Removes all headers matched by the given predicate.
      MutableRequest removeTag​(TypeRef<?> typeRef)
      Removes the tag associated with the given type.
      MutableRequest removeTag​(java.lang.Class<?> type)
      Removes the tag associated with the given type.
      MutableRequest setHeader​(java.lang.String name, java.lang.String value)
      Sets the header represented by the given name to the given value, overwriting the previous value (if any).
      MutableRequest setHeader​(java.lang.String name, java.util.List<java.lang.String> values)
      Sets the header represented by the given name to the given values, overwriting the previous value (if any).
      MutableRequest setHeaderIfAbsent​(java.lang.String name, java.lang.String value)
      Sets the header represented by the given name to the given value, only if there was no header with the given name.
      MutableRequest setHeaderIfAbsent​(java.lang.String name, java.util.List<java.lang.String> values)
      Sets the header represented by the given name to the given values, only if there was no header with the given name.
      <T> MutableRequest tag​(TypeRef<T> typeRef, T value)
      Adds a tag mapped to the given type.
      <T> MutableRequest tag​(java.lang.Class<T> type, T value)
      Adds a tag mapped to the given type.
      MutableRequest tag​(java.lang.Object value)
      Adds a tag mapped to the given object's runtime type.
      java.util.Optional<java.time.Duration> timeout()  
      MutableRequest timeout​(java.time.Duration timeout)  
      TaggableRequest toImmutableRequest()
      Returns an immutable copy of this request.
      java.lang.String toString()  
      java.net.URI uri()
      MutableRequest uri​(java.lang.String uri)
      Sets this request's URI.
      MutableRequest uri​(java.net.URI uri)
      Sets this request's URI.
      java.util.Optional<java.net.http.HttpClient.Version> version()  
      MutableRequest version​(java.net.http.HttpClient.Version version)  

      • Methods inherited from class java.net.http.HttpRequest

        equals, hashCode, newBuilder, newBuilder

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    • Method Detail

      • uri

        @CanIgnoreReturnValue
public MutableRequest uri​(java.lang.String uri)
        Sets this request's URI. Can be relative or without a host or a scheme.
        Throws:
        java.lang.IllegalArgumentException - if the uri's syntax is invalid

      • cacheControl

        @CanIgnoreReturnValue
public MutableRequest cacheControl​(CacheControl cacheControl)
        Sets the Cache-Control header to the given value.

      • apply

        @CanIgnoreReturnValue
public MutableRequest apply​(java.util.function.Consumer<? super MutableRequest> consumer)
        Calls the given consumer against this request.

      • bodyPublisher

        public java.util.Optional<java.net.http.HttpRequest.BodyPublisher> bodyPublisher()
        Specified by:
        bodyPublisher in class java.net.http.HttpRequest

      • adapterCodec

        public java.util.Optional<AdapterCodec> adapterCodec()
        Returns the AdapterCodec to be used for resolving this request's payload.

      • method

        public java.lang.String method()
        Specified by:
        method in class java.net.http.HttpRequest

      • timeout

        public java.util.Optional<java.time.Duration> timeout()
        Specified by:
        timeout in class java.net.http.HttpRequest

      • expectContinue

        public boolean expectContinue()
        Specified by:
        expectContinue in class java.net.http.HttpRequest

      • uri

        public java.net.URI uri()

        An empty URI (without a scheme, path or a host) is returned if no URI was previously set.

        Specified by:
        uri in class java.net.http.HttpRequest

      • version

        public java.util.Optional<java.net.http.HttpClient.Version> version()
        Specified by:
        version in class java.net.http.HttpRequest

      • headers

        public java.net.http.HttpHeaders headers()
        Specified by:
        headers in class java.net.http.HttpRequest

      • uri

        @CanIgnoreReturnValue
public MutableRequest uri​(java.net.URI uri)
        Sets this request's URI. Can be relative or without a host or a scheme.
        Specified by:
        uri in interface java.net.http.HttpRequest.Builder
        Specified by:
        uri in interface TaggableRequest.Builder

      • version

        @CanIgnoreReturnValue
public MutableRequest version​(java.net.http.HttpClient.Version version)
        Specified by:
        version in interface java.net.http.HttpRequest.Builder
        Specified by:
        version in interface TaggableRequest.Builder

      • headers

        @CanIgnoreReturnValue
public MutableRequest headers​(java.lang.String... headers)
        Description copied from interface: HeadersAccumulator
        Adds each of the given header name-value pairs. The pairs must be appended to each other in the given array, where each name is followed by a corresponding value.
        Specified by:
        headers in interface HeadersAccumulator<MutableRequest>
        Specified by:
        headers in interface java.net.http.HttpRequest.Builder
        Specified by:
        headers in interface TaggableRequest.Builder

      • timeout

        @CanIgnoreReturnValue
public MutableRequest timeout​(java.time.Duration timeout)
        Specified by:
        timeout in interface java.net.http.HttpRequest.Builder
        Specified by:
        timeout in interface TaggableRequest.Builder

      • POST

        @CanIgnoreReturnValue
public MutableRequest POST​(java.net.http.HttpRequest.BodyPublisher bodyPublisher)
        Specified by:
        POST in interface java.net.http.HttpRequest.Builder
        Specified by:
        POST in interface TaggableRequest.Builder

      • POST

        @CanIgnoreReturnValue
public MutableRequest POST​(java.lang.Object payload,
                           MediaType mediaType)
        Sets the request method to POST and sets the payload to the given value. The media type defines the format used for resolving the payload into a BodyPublisher.

      • POST

        @CanIgnoreReturnValue
public <T> MutableRequest POST​(T payload,
                               TypeRef<T> typeRef,
                               MediaType mediaType)
        Sets the request method to POST and sets the payload to the given value with an explicitly specified type. The media type defines the format used for resolving the payload into a BodyPublisher.

      • PUT

        @CanIgnoreReturnValue
public MutableRequest PUT​(java.net.http.HttpRequest.BodyPublisher bodyPublisher)
        Specified by:
        PUT in interface java.net.http.HttpRequest.Builder
        Specified by:
        PUT in interface TaggableRequest.Builder

      • PUT

        @CanIgnoreReturnValue
public MutableRequest PUT​(java.lang.Object payload,
                          MediaType mediaType)
        Sets the request method to PUT and sets the payload to the given value. The media type defines the format used for resolving the payload into a BodyPublisher.

      • PUT

        @CanIgnoreReturnValue
public <T> MutableRequest PUT​(T payload,
                              TypeRef<T> typeRef,
                              MediaType mediaType)
        Sets the request method to PUT and sets the payload to the given value with an explicitly specified type. The media type defines the format used for resolving the payload into a BodyPublisher.

      • PATCH

        @CanIgnoreReturnValue
public MutableRequest PATCH​(java.net.http.HttpRequest.BodyPublisher bodyPublisher)
        Sets the request method to PATCH and sets the body publisher to the given value.

      • PATCH

        @CanIgnoreReturnValue
public MutableRequest PATCH​(java.lang.Object payload,
                            MediaType mediaType)
        Sets the request method to PATCH and sets the payload to the given value. The media type defines the format used for resolving the payload into a BodyPublisher.

      • PATCH

        @CanIgnoreReturnValue
public <T> MutableRequest PATCH​(T payload,
                                TypeRef<T> typeRef,
                                MediaType mediaType)
        Sets the request method to PATCH and sets the payload to the given value with an explicitly specified type. The media type defines the format used for resolving the payload into a BodyPublisher.

      • method

        @CanIgnoreReturnValue
public MutableRequest method​(java.lang.String method,
                             java.net.http.HttpRequest.BodyPublisher bodyPublisher)
        Specified by:
        method in interface java.net.http.HttpRequest.Builder
        Specified by:
        method in interface TaggableRequest.Builder

      • method

        @CanIgnoreReturnValue
public MutableRequest method​(java.lang.String method,
                             java.lang.Object payload,
                             MediaType mediaType)
        Sets the request method and sets the payload to the given value. The media type defines the format used for resolving this payload into a BodyPublisher.

      • method

        @CanIgnoreReturnValue
public <T> MutableRequest method​(java.lang.String method,
                                 T payload,
                                 TypeRef<T> typeRef,
                                 MediaType mediaType)
        Sets the request method and sets the payload to the given value with an explicitly specified type. The media type defines the format used for resolving this payload into a BodyPublisher.

      • toImmutableRequest

        public TaggableRequest toImmutableRequest()
        Returns an immutable copy of this request.

      • copy

        public MutableRequest copy()
        Returns a copy of this request that is independent of this instance.
        Specified by:
        copy in interface java.net.http.HttpRequest.Builder
        Specified by:
        copy in interface TaggableRequest.Builder

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • mimeBody

        public java.util.Optional<com.github.mizosoft.methanol.MimeBody> mimeBody()

      • copyOf

        public static MutableRequest copyOf​(java.net.http.HttpRequest other)
        Returns a new MutableRequest that is a copy of the given request.

      • create

        public static MutableRequest create()
        Returns a new MutableRequest.

      • create

        public static MutableRequest create​(java.lang.String uri)
        Returns a new MutableRequest with the given URI and a default GET method.

      • create

        public static MutableRequest create​(java.net.URI uri)
        Returns a new MutableRequest with the given URI and a default GET method.

      • GET

        public static MutableRequest GET​(java.lang.String uri)
        Returns a new MutableRequest with the given URI and a GET method.

      • GET

        public static MutableRequest GET​(java.net.URI uri)
        Returns a new MutableRequest with the given URI and a GET method.

      • HEAD

        public static MutableRequest HEAD​(java.lang.String uri)
        Returns a new MutableRequest with the given URI and a HEAD method.

      • HEAD

        public static MutableRequest HEAD​(java.net.URI uri)
        Returns a new MutableRequest with the given URI and a HEAD method.

      • DELETE

        public static MutableRequest DELETE​(java.lang.String uri)
        Returns a new MutableRequest with the given URI and a DELETE method.

      • DELETE

        public static MutableRequest DELETE​(java.net.URI uri)
        Returns a new MutableRequest with the given URI and a DELETE method.

      • POST

        public static MutableRequest POST​(java.lang.String uri,
                                  java.net.http.HttpRequest.BodyPublisher bodyPublisher)
        Returns a new MutableRequest with the given URI and a POST method.

      • POST

        public static MutableRequest POST​(java.net.URI uri,
                                  java.net.http.HttpRequest.BodyPublisher bodyPublisher)
        Returns a new MutableRequest with the given URI and a POST method.

      • POST

        public static MutableRequest POST​(java.lang.String uri,
                                  java.lang.Object payload,
                                  MediaType mediaType)
        Returns a new MutableRequest with the given URI and a POST method.

      • POST

        public static MutableRequest POST​(java.net.URI uri,
                                  java.lang.Object payload,
                                  MediaType mediaType)
        Returns a new MutableRequest with the given URI and a POST method.

      • POST

        public static <T> MutableRequest POST​(java.lang.String uri,
                                      T payload,
                                      TypeRef<T> typeRef,
                                      MediaType mediaType)
        Returns a new MutableRequest with the given URI and a POST method.

      • POST

        public static <T> MutableRequest POST​(java.net.URI uri,
                                      T payload,
                                      TypeRef<T> typeRef,
                                      MediaType mediaType)
        Returns a new MutableRequest with the given URI and a POST method.

      • PUT

        public static MutableRequest PUT​(java.lang.String uri,
                                 java.net.http.HttpRequest.BodyPublisher bodyPublisher)
        Returns a new MutableRequest with the given URI and a PUT method.

      • PUT

        public static MutableRequest PUT​(java.net.URI uri,
                                 java.net.http.HttpRequest.BodyPublisher bodyPublisher)
        Returns a new MutableRequest with the given URI and a PUT method.

      • PUT

        public static MutableRequest PUT​(java.lang.String uri,
                                 java.lang.Object payload,
                                 MediaType mediaType)
        Returns a new MutableRequest with the given URI and a PUT method.

      • PUT

        public static MutableRequest PUT​(java.net.URI uri,
                                 java.lang.Object payload,
                                 MediaType mediaType)
        Returns a new MutableRequest with the given URI and a PUT method.

      • PUT

        public static <T> MutableRequest PUT​(java.lang.String uri,
                                     T payload,
                                     TypeRef<T> typeRef,
                                     MediaType mediaType)
        Returns a new MutableRequest with the given URI and a PUT method.

      • PUT

        public static <T> MutableRequest PUT​(java.net.URI uri,
                                     T payload,
                                     TypeRef<T> typeRef,
                                     MediaType mediaType)
        Returns a new MutableRequest with the given URI and a PUT method.

      • PATCH

        public static MutableRequest PATCH​(java.lang.String uri,
                                   java.net.http.HttpRequest.BodyPublisher bodyPublisher)
        Returns a new MutableRequest with the given URI and a PATCH method.

      • PATCH

        public static MutableRequest PATCH​(java.net.URI uri,
                                   java.net.http.HttpRequest.BodyPublisher bodyPublisher)
        Returns a new MutableRequest with the given URI and a PATCH method.

      • PATCH

        public static MutableRequest PATCH​(java.lang.String uri,
                                   java.lang.Object payload,
                                   MediaType mediaType)
        Returns a new MutableRequest with the given URI and a PATCH method.

      • PATCH

        public static MutableRequest PATCH​(java.net.URI uri,
                                   java.lang.Object payload,
                                   MediaType mediaType)
        Returns a new MutableRequest with the given URI and a PATCH method.

      • PATCH

        public static <T> MutableRequest PATCH​(java.lang.String uri,
                                       T payload,
                                       TypeRef<T> typeRef,
                                       MediaType mediaType)
        Returns a new MutableRequest with the given URI and a PATCH method.

      • PATCH

        public static <T> MutableRequest PATCH​(java.net.URI uri,
                                       T payload,
                                       TypeRef<T> typeRef,
                                       MediaType mediaType)
        Returns a new MutableRequest with the given URI and a PATCH method.