Class EndpointUrl

java.lang.Object
software.amazon.awssdk.endpoints.EndpointUrl
@SdkPublicApi public final class EndpointUrl extends Object
A lightweight, immutable representation of a resolved endpoint URL that stores pre-parsed components (scheme, host, port, path) as strings, avoiding the cost of URI construction.

Three factory methods are provided:

  • Method Details

    • fromString

      public static EndpointUrl fromString(String url)
      Parse a URL string into its components without constructing a URI.

      Performs minimal string splitting only. The original URL string is retained for faithful URI reconstruction via toUri(). Path, query and fragment components (if present) MUST already be url encoded.

      Expected format: scheme://[userinfo@]host[:port][/encodedPath][?query][#fragment]

      Component extraction matches URI for well-formed URLs:

      • Userinfo is excluded from host(), matching URI.getHost(). It remains part of the string returned by toUri(), matching URI.toString().
      • A trailing ':' with no digits (e.g. https://example.com:) yields a port of -1, matching URI.getPort().
      • An IPv6 literal is stored with its enclosing brackets (e.g. [::1]).
      Parameters:
      url - the URL string to parse
      Returns:
      a new EndpointUrl with pre-parsed components
      Throws:
      IllegalArgumentException - if the URL has no scheme, has a non-numeric or out-of-range port, has more than one ':' separating host and port, or has an unterminated IPv6 literal

    • fromComponents

      public static EndpointUrl fromComponents(String scheme, String host, int port, String encodedPath)
      Create an EndpointUrl from individual components.

      Used internally (e.g., by addHostPrefix and codegen) to avoid re-parsing. The rawUrl field is null in this case, so toUri() reconstructs the URI from components. No query or fragment is included.

      Equivalence contract: For any valid endpoint URL string s with no query or fragment, fromComponents(scheme, host, port, path) MUST produce an EndpointUrl that equals fromString(scheme + "://" + host + (port >= 0 ? ":" + port : "") + path). The codegen relies on this equivalence — see EndpointUrlCodeEmitter.

      Parameters:
      scheme - the URL scheme (e.g., "https")
      host - the hostname (e.g., "s3.us-east-1.amazonaws.com")
      port - the port number, or -1 if not specified
      encodedPath - the encoded path (e.g., "/bucket/key"), or empty string if no path
      Returns:
      a new EndpointUrl

    • fromComponents

      public static EndpointUrl fromComponents(String scheme, String host, int port, String encodedPath, String queryAndFragment)
      Create an EndpointUrl from individual components, including query and fragment.

      This overload is used when reconstructing an EndpointUrl with modifications (e.g., host prefix) while preserving the original query and fragment components.

      Parameters:
      scheme - the URL scheme (e.g., "https")
      host - the hostname (e.g., "s3.us-east-1.amazonaws.com")
      port - the port number, or -1 if not specified
      encodedPath - the encoded path (e.g., "/bucket/key"), or empty string if no path
      queryAndFragment - the query and fragment string (e.g., "?key=value#section"), or empty string if none
      Returns:
      a new EndpointUrl

    • fromUri

      public static EndpointUrl fromUri(URI uri)
      Create an EndpointUrl from an existing URI.

      The URI field is pre-populated, so toUri() returns the original URI instance without any additional construction.

      Parameters:
      uri - the URI to create from
      Returns:
      a new EndpointUrl with components extracted from the URI

    • scheme

      public String scheme()
      Returns the URL scheme (e.g., "https").

    • host

      public String host()
      Returns the hostname (e.g., "s3.us-east-1.amazonaws.com").

    • port

      public int port()
      Returns the port number, or -1 if not explicitly specified.

    • encodedPath

      public String encodedPath()
      Returns the encoded path (e.g., "/bucket/key"), or an empty string if no path is present.

    • queryAndFragment

      public String queryAndFragment()
      Returns the query and fragment portion of the URL (e.g., "?key=value#section"), or an empty string if neither is present.

    • toUri

      public URI toUri()
      Returns the URI representation. Lazily constructed on first call using double-checked locking.

      When created via fromString(String), uses the original URL string for faithful reconstruction. When created via fromComponents(String, String, int, String) reconstructs from components (no query/fragment). When created via fromUri(URI), returns the original URI instance.

      Returns:
      the URI representation of this endpoint URL

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object