Package com.tccc.kos.commons.util.net

Class UriBuilder

java.lang.Object
com.tccc.kos.commons.util.net.UriBuilder
public class UriBuilder extends Object
General-purpose URI builder class.

It can parse an exiting URI and modify it, or construct a blank URI from scratch.

Details

Most aspects are typical, but there are two significant features to note:
  • secure flag : In the event that the URI you want to generate is "http" vs "https" (or "ws" vs "wss"), but you don't want to have external logic to select the correct scheme string, simply use any version of the scheme and then use the secure flag to have it set correctly in the final URI.
  • variables : If a path contains a macro, such as {name}, then it will be replaced with the corresponding variable value. This is an easy way to inject variables into path segments. For example: 
     builder.setPath("/users/{userId}/").setVar("userId", 1234);  // results in a path of "/users/1234/"

Example #1 (starting from blank)

 
  URI uri = new UriBuilder()
      .setScheme("http")
      .setHost("example.com")
      .setPort(12345)
      .setSecure(true)                // changes the scheme from "http" to "https"
      .setPath("/path/{var1}/page.html")
      .setVar("var1", "to")           // causes variable substitution to take place
      .setFragment("fragment")
      .addParam("param1", "value1")
      .addParam("param2", "value 2")  // note that the space character is encoded
      .addParam("param3", null)       // just the parameter without an associated value
      .toURI();
  assertThat(uri.toString(), equalTo("https://example.com:12345/path/to/page.html#fragment?param1=value1&param2=value+2&param3");

Example #2 (starting from an existing URI string)

 
  URI uri = new UriBuilder("https://mysite.com:443/path/to/page")
      .setSecure(false)
      .setPort(null)
      .addParam("param1", "value1")
      .toURI();
  assertThat(uri.toString(), equalTo("http://mysite.com/path/to/page?param1=value1");
Since:
1.0
Version:
2022-10-05
See Also:

  • Constructor Details

    • UriBuilder

      public UriBuilder()
      Constructs an empty URI builder.

    • UriBuilder

      public UriBuilder(String str)
      Constructs a URI builder initialized from the specified string.
      Parameters:
      str - the initial URI for the builder

    • UriBuilder

      public UriBuilder(URI uri)
      Creates a URI builder initialized from the specified URI.
      Parameters:
      uri - the initial URI for the builder

  • Method Details

    • setSecure

      public UriBuilder setSecure(Boolean secure)
      Sets the secure flag.

      If this flag is set to either true or false , then the configured scheme will be converted to the form that matches it. For example:

      • If this flag is true , then "http" becomes "https" and "ws" becomes "wss"
      • If this flag is false , then "https" becomes "http" and "wss" becomes "ws"
      • If this flag is null , then no change is made to the scheme
      Parameters:
      secure - true enables security, false disables it, null indicates "no change"

    • setScheme

      public UriBuilder setScheme(String scheme)
      Sets the scheme of the URI.

      If "http/https" or "ws/wss", then the actual scheme can be controlled using the setSecure() method, in cases where computing the correct form of the scheme is inconvenient.

      Parameters:
      scheme - the scheme [http|https|ws|wss] of the URI

    • setHost

      public UriBuilder setHost(String host)
      Sets the host of the URI.
      Parameters:
      host - the host of the URI

    • setPort

      public UriBuilder setPort(Integer port)
      Sets the port number of the URI. Use null to remove the explicit port number.
      Parameters:
      port - the port number of the URI

    • setPath

      public UriBuilder setPath(String path)
      Sets the path for the URI.

      This removes all existing path segments before setting the specified path. The path can contain multiple segments such as "foo/bar", as well as macro expansions such as "users/{userId}".

      Parameters:
      path - the path of the URI

    • setPaths

      public UriBuilder setPaths(String... paths)
      Sets the path for the URI.

      This removes all existing path segements and replaces then with the specified path. Each path can contain multiple segments such as "foo/bar", as well as macro expansions such as "users/{userId}".

      Parameters:
      paths - the new path segments of the URI

    • setPaths

      public UriBuilder setPaths(List<String> paths)
      Sets the path for the URI. This will remove all existing paths and replace with the specified path. Each path can contain multiple segments such as "foo/bar" as well as macro expansions such as "users/{userId}"
      Parameters:
      paths - the new paths

    • addPath

      public UriBuilder addPath(String path)
      Adds a path to the URI. The path can contain multiple segments such as "foo/bar" as well as macro expansions such as "users/{userId}"
      Parameters:
      path - the path to add

    • addPaths

      public UriBuilder addPaths(String... paths)
      Adds paths to the URI. The paths can contain multiple segments such as "foo/bar" as well as macro expansions such as "users/{userId}"
      Parameters:
      paths - the paths to add

    • addPaths

      public UriBuilder addPaths(List<String> paths)
      Adds paths to the URI. The paths can contain multiple segments such as "foo/bar" as well as macro expansions such as "users/{userId}"
      Parameters:
      paths - the paths to add

    • setVar

      public UriBuilder setVar(String name, Object val)
      Replaces the {name} macro in the path with the specified value. This replaces every instance of the macro name in the path. If any macros exists without variables, then exception is thrown when toURI() is called.
      Parameters:
      name - name of the variable
      val - value of the variable

    • removeAllParams

      public UriBuilder removeAllParams()
      Removes all parameters from the URI.

    • removeParam

      public UriBuilder removeParam(String name)
      Removes all instances of the specified parameter from the URI.
      Parameters:
      name - the name of the parameter to remove

    • setParams

      public UriBuilder setParams(List<UriParam> params)
      Replaces all existing parameters with the new list of parameters.
      Parameters:
      params - new parameter list

    • addParams

      public UriBuilder addParams(List<UriParam> params)
      Adds the specified parameters to the URI.
      Parameters:
      params - the parameters to add

    • setParam

      public UriBuilder setParam(UriParam param)
      Removes all instances of the given parameter and replaces it with the new parameter.
      Parameters:
      param - the replacement parameter

    • setParam

      public UriBuilder setParam(String name, String value)
      Removes all instances of the given parameter and replaces it with the new parameter.
      Parameters:
      name - the parameter name
      value - the parmaeter value

    • addParam

      public UriBuilder addParam(UriParam param)
      Adds the specified parameter to the URI.
      Parameters:
      param - the parameter to add

    • addParam

      public UriBuilder addParam(String name, String value)
      Adds the specified parameter to the URI.
      Parameters:
      name - the parameter name
      value - the parameter value

    • setFragment

      public UriBuilder setFragment(String fragment)
      Sets the fragment for the URI.
      Parameters:
      fragment - the fragment

    • toURI

      public URI toURI()
      Returns a URI from the current builder configuration.

    • toString

      public String toString()
      Equivalent to calling toURI().toString() .
      Overrides:
      toString in class Object

    • getScheme

      public String getScheme()

    • getHost

      public String getHost()

    • getPort

      public Integer getPort()

    • getFragment

      public String getFragment()