Package ru.vyarus.dropwizard.guice.url

Class AppUrlBuilder

java.lang.Object
ru.vyarus.dropwizard.guice.url.AppUrlBuilder
public class AppUrlBuilder extends Object
General utility for building absolute application urls (counting current server configuration). This might be used for views, when (especially when proxy is used) it is often required to build absolute urls. Also, could be usd for resource redirections (but, in this case, RestPathBuilder could be used directly).

The default server creates two contexts: main (including rest) on 8080 and admin context on 8081. For simple server, there would be only one context where admin would be available on sub-url "/admin".

Url-related configurations:

  • server.applicationContextPath - main context path
  • server.rootPath - rest mapping url (main context path is also applied for rest)
  • server.adminContextPath - admin context path

By default, class would create "localhost" based urls (because there is no way to know server host). To build for a particular host use forHost(String) - this way server ports will be applied.

Application could also be behind a proxy (like apache) which hides real server port. In this case use forProxy(String) - server port would not be applied. Also, apache might be configured to serve application for a sub-path like "http://myhost.com/myapp/" - use this as a proxy url to build correct application urls.

Since:
26.09.2025
See Also:

  • Constructor Details

    • AppUrlBuilder

      @Inject public AppUrlBuilder(io.dropwizard.core.setup.Environment environment)
      Default constructor for "localhost"-based urls. It would be possible to create specialized builders with forHost(String) or forProxy(String) methods.

      Note: method annotated with Inject to be able to obtain builder directly from guice context.

      Parameters:
      environment - environment instance

    • AppUrlBuilder

      public AppUrlBuilder(Supplier<io.dropwizard.core.setup.Environment> environment)
      Special constructor for instance creation before application startup.
      Parameters:
      environment - environment supplier

    • AppUrlBuilder

      protected AppUrlBuilder(Supplier<io.dropwizard.core.setup.Environment> environment, String host, boolean proxied)
      Create an app url builder.
      Parameters:
      environment - environment object
      host - required host
      proxied - true if server is proxied (port already declared in host)

  • Method Details

    • forHost

      public AppUrlBuilder forHost(String host)
      Create builder instance for specific host. The host must contain protocol and the host name like "https://myhost.com" and builder will append correct port and build urls relatively.
      Parameters:
      host - application host (and protocol)
      Returns:
      builder instance

    • forProxy

      public AppUrlBuilder forProxy(String proxy)
      Create builder instance for proxied application. In this case, real application port is not used (most commonly, apache would redirect port 80 into application port). Also, apache could be configured to serve application from a sub-path like "http://myhost.com/myapp/" (provided host myst point to the application root).
      Parameters:
      proxy - proxied host (and protocol)
      Returns:
      builder instance

    • root

      public String root(String path, Object... args)
      Build url relative to application root ("/"). No server configurations applied in this case.

      Warning: don't mix root urls with the main context urls as application main context could differ.

      To get root url: #root("/"),

      Parameters:
      path - target path, relative to application root (could contain String.format() placeholders: %s)
      args - variables for path placeholders (String.format() arguments)
      Returns:
      application path url

    • rest

      public String rest(String path, Object... args)
      Build url relative to application rest mapping. Configured main context path server.applicationContextPath and rest path server.rootPath would be prepended automatically.

      To get rest root url: #rest("/"),

      Parameters:
      path - target path, relative to rest root (could contain String.format() placeholders: %s)
      args - variables for path placeholders (String.format() arguments)
      Returns:
      application resource url
      See Also:

    • rest

      public <K> RestPathBuilder<K> rest(Class<K> resource)
      Build url relative to application rest mapping. Configured main context path server.applicationContextPath and rest path server.rootPath would be prepended automatically.

      Resource path is applied from resource Path annotation. Resource method path could be declared with a method call: RestPathBuilder.method(ru.vyarus.dropwizard.guice.url.util.Caller) (in this case all non-null arguments mapped as query and path params would be applied automatically). If resource-method-based declaration not used, then it might be required to provide manually values for declared path params (ResourceParamsBuilder.pathParam(String, Object)) and (optionally) apply query params.

      Example: rest(MyResource.class).method(res -> res.doGet("abc", 12).build()), where public Response doGet(@PathParam("par1") String par1, @QueryParam("qp") int qp and so path param "par1" and query param "qp" would be registered automatically (assuming path param used in resource path).

      If target method is in sub-resource, use RestPathBuilder.subResource(String, Class, Object...) to append its path and switch context class.

      Direct resource class and method usage allows to get refactoring-safe urls.

      Type Parameters:
      K - resource type
      Parameters:
      resource - resource class
      Returns:
      resource path builder

    • rest

      public <K> RestPathBuilder<K> rest(Consumer<jakarta.ws.rs.core.UriBuilder> path, Class<K> resource)
      Manual rest path building. Useful for complex cases with matrix params in the middle.
      Type Parameters:
      K - resource type
      Parameters:
      path - path builder
      resource - target resource class
      Returns:
      resource path builder

    • app

      public String app(String path, Object... args)
      Build url relative to the main context (server.applicationContextPath).

      To get main context root url: #main("/"),

      Parameters:
      path - target path, relative to the main context (could contain String.format() placeholders: %s)
      args - variables for path placeholders (String.format() arguments)
      Returns:
      application path url

    • admin

      public String admin(String path, Object... args)
      Build url relative to the admin context (server.adminContextPath).

      To get admin context root url: #admin("/"),

      Parameters:
      path - target path, relative to the admin context (could contain String.format() placeholders: %s)
      args - variables for path placeholders (String.format() arguments)
      Returns:
      application path url

    • getAppPort

      public int getAppPort()
      Get main application context port.
      Returns:
      the actual port the connector is listening to, or -1 if it has not been opened, or -2 if it has been closed.

    • getAdminPort

      public int getAdminPort()
      Get admin application context port.
      Returns:
      the actual port the connector is listening to, or -1 if it has not been opened, or -2 if it has been closed.

    • getRestContextPath

      public String getRestContextPath()
      Rest context is configured with server.rootPath and it is "/" by default. Also, rest is mapped under the main context, so if main context mapping changed with server.applicationContextPath it must also be counted. The returned path counts both and so is relative to the server root.
      Returns:
      rest context (with a context path), relative to the server root path

    • getAppContextPath

      public String getAppContextPath()
      Main context is configured with server.applicationContextPath and it is "/" by default.
      Returns:
      main context (with a context path), relative to the server root path

    • getAdminContextPath

      public String getAdminContextPath()
      Admin context is configured with server.adminContextPath and it is "/" by default ("/admin" for simple server). Note that by default, admin is on different port.
      Returns:
      main context (with a context path), relative to the server root path