Package ru.vyarus.guicey.gsp.app

Class ServerPagesAppBundle.AppBuilder

java.lang.Object
ru.vyarus.guicey.gsp.app.ServerPagesAppBundle.AppBuilder
Enclosing class:
ServerPagesAppBundle
public static class ServerPagesAppBundle.AppBuilder extends Object
Server pages application bundle builder.

  • Constructor Details

  • Method Details

    • mapViews

      public ServerPagesAppBundle.AppBuilder mapViews(String prefix)
      Specify default mapping prefix for views rest resources. If not declared, application name will be used as mapping prefix.

      For example, if you specify "com.mycompany/app1" as prefix then all registered rest resources, starting from this path will be mapped to gsp application (could be called relatively to application root).

      Only one prefix may be declared: error will be thrown on duplicate declaration.

      Parameters:
      prefix - rest prefix to map as root views
      Returns:
      builder instance for chained calls
      See Also:

    • mapViews

      public ServerPagesAppBundle.AppBuilder mapViews(String subUrl, String prefix)
      Map view rest to sub url, using different prefix than default. This way it is possible to use view rest, not started with default prefix. Direct template handler will also be applied to this prefix (to support direct template rendering).

      Only one prefix may be applied to one url (error will be thrown on duplicate registration)! But other mappings are possible for larger sub url (partially overlapping).

      Additional views could also be mapped through extension registration: ServerPagesBundle.extendApp(String).

      Pay attention that additional asset locations may be required (attachAssets(String, String), because only templates relative to view class will be correctly resolved, but direct templates may fail to resolve.

      Parameters:
      subUrl - sub url to map views to
      prefix - rest prefix to map as root views
      Returns:
      builder instance for chained calls

    • requireRenderers

      public ServerPagesAppBundle.AppBuilder requireRenderers(String... names)
      Specifies required template types (view renderes) for application. This setting is optional and used only for immediate application startup failing when no required renderer is configured in global server pages bundle (ServerPagesBundle.builder()).

      Without declaring required renderer, application will simply serve template files "as is" when no appropriate renderer found (because template file will not be recognized as template).

      Renderer name is a renderer configuration key, defined in ViewRenderer.getConfigurationKey().

      Parameters:
      names - required renderer names
      Returns:
      builder instance for chained calls

    • spaRouting

      public ServerPagesAppBundle.AppBuilder spaRouting()
      Shortcut for spaRouting(String) with default regexp.
      Returns:
      builder instance for chained calls

    • spaRouting

      public ServerPagesAppBundle.AppBuilder spaRouting(String noRedirectRegex)
      Enable single page application html5 routing support.
      Parameters:
      noRedirectRegex - regex to match all cases when redirection not needed
      Returns:
      builder instance for chained calls
      See Also:
      • for more info how it works
      • for more info about regexp

    • indexPage

      public ServerPagesAppBundle.AppBuilder indexPage(String name)
      Declares index page (served for "/" calls). Index page may also be a template. If index view is handled with a rest then simply leave as "" (default): resource on path "{restPath}/{appMapping}/" will be used as root page.

      Pay attention that index is not set by default to "index.html" because most likely it would be some template handled with rest resource (and so it would be too often necessary to override default).

      Parameters:
      name - index file name (by default "")
      Returns:
      builder instance for chained calls

    • errorPage

      public ServerPagesAppBundle.AppBuilder errorPage(String path)
      Default error page (shown in case of exceptions and for all error return codes (>=400)).
      Parameters:
      path - either path to static resource (inside registered classpath path) or resource url (without app name prefix)
      Returns:
      builder instance for chained calls
      See Also:

    • errorPage

      public ServerPagesAppBundle.AppBuilder errorPage(int code, String path)
      Show special page instead of response with specified status code. Errors are intercepted both for assets and template rendering. For templates, jersey request listener used to intercept actual exceptions (to be able to access actual exception inside error page). Default dropwizard exception mapper will log error (as for usual rest).

      Error pages should use ErrorTemplateView as (base) model class in order to get access to context exception. It is not required, if error object itself not required during rendering.

      NOTE that error page is returned only if original request accept html response and otherwise no error page will be shown. Intention here is to show human readable errors only for humans.

      IMPORTANT: GSP errors mechanism override ExceptionMapper and dropwizard-view ErrorEntityWriter mechanisms because exception is detected before them and request is redirected to error page. Both ExceptionMapper and EntityWriter would be called, but their result will be ignored (still, ExceptionMapper is useful for errors logging). This was done to avoid influence of global ExceptionMapper's to be sure custom error page used. It is possible to ignore GSP error mechanism for exact rest methods by using ManualErrorHandling annotation.

      Parameters:
      code - error code to map page onto
      path - either path to static resource (inside registered classpath path) or resource url (without app name prefix)
      Returns:
      builder instance for chained calls
      See Also:

    • attachAssets

      public ServerPagesAppBundle.AppBuilder attachAssets(String path)
      Add additional assets location. Useful if you need to serve files from multiple folders. From usage perspective, files from all registered resource paths are "copied" into one directory and application could reference everything from "there".

      It is the same as separate extension registration with ServerPagesBundle.extendApp(String).

      NOTE: extended paths are used in priority so some file exists on the same path, extended path will "override" primary location.

      Parameters:
      path - assets classpath path (may be in form of package (dot-separated))
      Returns:
      builder instance for chained calls
      See Also:

    • attachAssets

      public ServerPagesAppBundle.AppBuilder attachAssets(String subUrl, String path)
      Essentially the same as attachAssets(String), but attach classpath assets to application sub url. As with root assets, multiple packages could be attached to url. Registration order is important: in case if multiple packages contains the same file, file from the latest registered package will be used.

      Example usage: suppose you need to serve fonts from some 3rd party jar, so you need to map this package to sub url with attachAssetsForUrl("/fonts/", "com.some.package.with.fonts"). After that all assets from registered package will be accessible by this url (e.g /fonts/myfont.ttf).

      Parameters:
      subUrl - sub url to serve assets from
      path - assets classpath paths (may be in form of package (dot-separated))
      Returns:
      builder instance for chained calls

    • attachWebjars

      public ServerPagesAppBundle.AppBuilder attachWebjars()
      Shortcut for #attachAssets("META-INF/resources/webjars/")). Useful if you want to use resources from webjars. All webjars package resources under the same path (e.g. META-INF/resources/webjars/jquery/3.4.1/dist/jquery.min.js), so after enabling webjars support you can reference any resource from webjar (in classpath) (e.g. as <script src="jquery/3.4.1/dist/jquery.min.js">).
      Returns:
      builder instance for chained calls

    • filePattern

      public ServerPagesAppBundle.AppBuilder filePattern(String regex)
      Differentiation of template call from static resource is based on fact: static resources have extensions. So when "/something/some.ext" is requested and extension is not supported template extension then it's direct asset. In case when you have static files without extension, you can include them directly into detection regexp (using regex or (|) syntax).

      Pattern must return detected file name as first matched group (so direct template could be detected). Pattern is searched (find) inside path, not matched (so simple patterns will also work).

      Parameters:
      regex - regex for file request detection and file name extraction
      Returns:
      builder instance for chained calls
      See Also:

    • viewsConfigurationModifier

      public ServerPagesAppBundle.AppBuilder viewsConfigurationModifier(String name, ViewRendererConfigurationModifier modifier)
      Dropwizard views configuration modification. Views configuration could be bound only in global server pages support bundle (ServerPagesBundle.ViewsBuilder.viewsConfiguration(io.dropwizard.views.common.ViewConfigurable)). But it's often required to "tune" template engine specifically for application. This method allows global views configuration modification for exact server pages application.

      The main use case is configuration of the exact template engine. For example, in case of freemarker this could be used to apply auto includes: 

       .viewsConfigurationModifier("freemarker", config -> config
                         // expose master template
                         .put("auto_include", "/com/my/app/ui/master.ftl"))

      Note that configuration object is still global (because dropwizard views support is global) and so multiple server pages applications could modify configuration. For example, if multiple applications will declare auto includes (example above) then only one include will be actually used. Use ServerPagesBundle.ViewsBuilder.printViewsConfiguration() to see the final view configuration.

      Parameters:
      name - renderer name (e.g. freemarker, mustache, etc.)
      modifier - modification callback
      Returns:
      builder instance for chained calls

    • build

      public ServerPagesAppBundle build()
      Returns:
      configured dropwizard bundle instance