Package nl.colorize.util.http

Class URLLoader

java.lang.Object
nl.colorize.util.http.URLLoader
public class URLLoader extends Object
Cross-platform API for building HTTP requests, then sending those requests using a HTTP client suitable for the current platform.

Depending on the platform, this class will automatically choose between using HttpClient and HttpURLConnection. The former was introduced in Java 11 and supports HTTP/2. However, it is not yet fully supported across all platforms and environments. On such platforms, the legacy HTTP client is used instead.

The auto-detect mechanism can be overruled using the FORCE_LEGACY_HTTP_CLIENT_SYSTEM_PROPERTY system property. This is a global setting that affects all URLLoader instances. It is not possible to override the auto-detect mechanism on a per-request basis, since this would be akin to just using the preferred HTTP client directly.

This class only supports URL requests for the HTTP and HTTPS protocols. Other protocols, such as file:// URLs, are not supported.

Though the purpose of this class is to provide a consistent API on top of the two HTTP clients, the name is based on the Flash ActionScript class of the same name.

  • Field Details

    • FORCE_LEGACY_HTTP_CLIENT_SYSTEM_PROPERTY

      @Deprecated public static final String FORCE_LEGACY_HTTP_CLIENT_SYSTEM_PROPERTY
      Deprecated.
      Applications should prefer automatic detection, to avoid ending up with a HTTP client that is not actually supported on the current platform.
      System property to override the automatication HTTP client detection, and forces the usage of the classic HttpURLConnection when set to true.
      See Also:

  • Constructor Details

    • URLLoader

      public URLLoader(Method method, URI url, Charset encoding)
      Starts building a URL request. In addition to this constructor, this class also provides a number of factory methods.
      Throws:
      IllegalArgumentException - if the URL cannot be parsed into a valid HTTP or HTTPS URL.

    • URLLoader

      public URLLoader(Method method, String url, Charset encoding)
      Starts building a URL request. In addition to this constructor, this class also provides a number of factory methods.
      Throws:
      IllegalArgumentException - if the URL cannot be parsed into a valid HTTP or HTTPS URL.

  • Method Details

    • withPathComponent

      public URLLoader withPathComponent(String pathComponent)
      Appends the specified path component to the end of the URL. The path component is allowed to include a leading or trailing slash. Any other characters, including slashes, will be encoded.
      Throws:
      IllegalArgumentException - if the combination of the existing URL plus the new path component leads to an invalid URL.

    • withHeader

      public URLLoader withHeader(String name, String value, boolean replace)
      Adds the specified request header. If the replace option is true, this will replace any headers with the same name. If the option is false, it will simply add the new header, leaving any existing headers with the same name in place.

    • withHeader

      public URLLoader withHeader(String name, String value)
      Adds the specified header to the end of the request. Using this method is the equivalent of using withHeader(name, value, false.

    • withHeaders

      public URLLoader withHeaders(Map<String,String> headers)
      Adds the specified request headers. This method is the equivalent of using withHeader(name, value, false on all headers in the map.

    • withHeaders

      public URLLoader withHeaders(Headers additional)
      Adds the specified request headers. This method is the equivalent of using withHeader(name, value, false on all headers.

    • withBody

      public URLLoader withBody(String body, String contentType)
      Uses the specified request body and sets the Content-Type accordingly. See the withBody(PostData), withJSON(String), and withXML(String) convenience methods for common request body types.

    • withBody

      public URLLoader withBody(PostData data)
      Uses the specified form data as the request body, and changes the Content-Type header to "application/x-www-form-urlencoded".

    • withXML

      public URLLoader withXML(String xml)
      Uses the specified XML request body, and changes the Content-Type header to "text/xml".

    • withJSON

      public URLLoader withJSON(String json)
      Uses the specified JSON request body, and changes the Content-Type header to "application/json".

    • withQueryParam

      public URLLoader withQueryParam(String name, String value)

    • withBasicAuth

      public URLLoader withBasicAuth(String user, String password)
      Convenience method to add the HTTP basic authentication header to the request.

      Security note: Only use this method when sending requests to HTTP URLs. Do not use it for requests over plain HTTP, as the header can potentially be intercepted by anyone with network access.

    • withTimeout

      public URLLoader withTimeout(int timeout)

    • allowErrorStatus

      public URLLoader allowErrorStatus()
      Allows response error codes (HTTP status 4xx and 5xx). This allows the URLLoader to process the response for such a request, instead of throwing an exception.

    • disableCertificateValidation

      public URLLoader disableCertificateValidation()
      Disables SSL certificate validation performed for HTTPS connections, ignoring any errors or warnings that may occur while checking the certificate.

      Security note: Ignoring these errors and warnings means you can no longer assume communication to be secure. It is strongly recommended to correct the SSL certificate itself, rather than using HTTPS with an insecure certificate.

    • send

      public URLResponse send() throws IOException
      Sends the HTTP request and returns the response. This method will automatically select a suitable HTTP client for the current platform, as described in the class documentation.
      Throws:
      IOException - if the request failes, of if the request produces HTTP status 4xx (client error) or 5xx (server error). However, if allowErrorStatus() was used, no such exception will be thrown.

    • sendAsync

      public Future<URLResponse> sendAsync()
      Asynchronous version of send() that sends the request from a separate thread.

    • sendBackground

      public Subscribable<URLResponse> sendBackground()
      Starts a background thread that will send this request. Returns a Subscribable that can be used to subscribe to the response and/or errors.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • get

      public static URLLoader get(String url)
      Factory method that creates a GET request to the specified URL. The request will use the UTF-8 character encoding.

    • post

      public static URLLoader post(String url)
      Factory method that creates a POST request to the specified URL. The request will use the UTF-8 character encoding.

    • put

      public static URLLoader put(String url)
      Factory method that creates a PUT request to the specified URL. The request will use the UTF-8 character encoding.

    • delete

      public static URLLoader delete(String url)
      Factory method that creates a DELETE request to the specified URL. The request will use the UTF-8 character encoding.