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 java.lang.Object

Server pages application bundle builder.

Constructor Summary

Constructors

Constructor and Description
AppBuilder(boolean mainContext, java.lang.String name, java.lang.String path, java.lang.String uri)

Method Summary

Modifier and Type	Method and Description
ServerPagesAppBundle.AppBuilder	attachAssets(java.lang.String path) Add additional assets location.
ServerPagesAppBundle.AppBuilder	attachAssets(java.lang.String subUrl, java.lang.String path) Essentially the same as attachAssets(String), but attach classpath assets to application sub url.
ServerPagesAppBundle.AppBuilder	attachWebjars() Shortcut for #attachAssets("META-INF/resources/webjars/")).
ServerPagesAppBundle	build()
ServerPagesAppBundle.AppBuilder	errorPage(int code, java.lang.String path) Show special page instead of response with specified status code.
ServerPagesAppBundle.AppBuilder	errorPage(java.lang.String path) Default error page (shown in case of exceptions and for all error return codes (>=400)).
ServerPagesAppBundle.AppBuilder	filePattern(java.lang.String regex) Differentiation of template call from static resource is based on fact: static resources have extensions.
ServerPagesAppBundle.AppBuilder	indexPage(java.lang.String name) Declares index page (served for "/" calls).
ServerPagesAppBundle.AppBuilder	mapViews(java.lang.String prefix) Specify default mapping prefix for views rest resources.
ServerPagesAppBundle.AppBuilder	mapViews(java.lang.String subUrl, java.lang.String prefix) Map view rest to sub url, using different prefix than default.
ServerPagesAppBundle.AppBuilder	requireRenderers(java.lang.String... names) Specifies required template types (view renderes) for application.
ServerPagesAppBundle.AppBuilder	spaRouting() Shortcut for spaRouting(String) with default regexp.
ServerPagesAppBundle.AppBuilder	spaRouting(java.lang.String noRedirectRegex) Enable single page application html5 routing support.
ServerPagesAppBundle.AppBuilder	viewsConfigurationModifier(java.lang.String name, ViewRendererConfigurationModifier modifier) Dropwizard views configuration modification.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AppBuilder

public AppBuilder(boolean mainContext,
                  java.lang.String name,
                  java.lang.String path,
                  java.lang.String uri)

Method Detail

mapViews

public ServerPagesAppBundle.AppBuilder mapViews(java.lang.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:

for mapping other rest views on sub urls

mapViews

public ServerPagesAppBundle.AppBuilder mapViews(java.lang.String subUrl,
                                                java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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:

for registereing error page on exact return code

errorPage

public ServerPagesAppBundle.AppBuilder errorPage(int code,
                                                 java.lang.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:

for global errors page

attachAssets

public ServerPagesAppBundle.AppBuilder attachAssets(java.lang.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:

to register assets on specific sub url

attachAssets

public ServerPagesAppBundle.AppBuilder attachAssets(java.lang.String subUrl,
                                                    java.lang.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(java.lang.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:

default pattern

viewsConfigurationModifier

public ServerPagesAppBundle.AppBuilder viewsConfigurationModifier(java.lang.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.ViewConfigurable)). But its 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