ru.vyarus.guicey.gsp.app.asset

Class AssetLookup

java.lang.Object

ru.vyarus.guicey.gsp.app.asset.AssetLookup

All Implemented Interfaces:

java.io.Serializable

public class AssetLookup
extends java.lang.Object
implements java.io.Serializable

GSP application assets resolution (for exact application with all its extensions).

Assets stored in classpath. Multiple classpath locations could be mapped for assets (overriding default location). Some assets could be mapped into exact urls (with ability to override too).

Also, assets may be resolved through special class loaders. Possible example is attaching additional folders as resource folder using custom class loader.

WARNING: custom class loader will be automatically supported for static resources, but template engine may not be able to resolve template. For example, freemarker use class loader of resource class serving view, so if resource class and view template are in the same class loader then it will work. For sure direct template rendering (without custom resource class) will not work. Freemarker may be configured to support all cases by using custom template loader, activated with global bundle shortcut ServerPagesBundle.ViewsBuilder.enableFreemarkerCustomClassLoadersSupport(). Mustache is impossible to configure properly (with current mustache views renderer). The problem with view implementations is that they accept only path to template for rendering and will lookup it by default only in application classloader.

Overall, lookup performs two operations: lookup classpath path by url (probably using extra mapping) and resource loading itself. First phase obviously performs lookup too (duplicates second phase), but separate phases are still required to be able to lookup templates directly (using proper class loader).

Since:

26.11.2019

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AssetLookup.AssetLocation Represent resolved asset location: actual classpath path (absolute) and target class loader (where resource found).

Constructor Summary

Constructors

Constructor and Description
AssetLookup(java.lang.String primaryLocation, com.google.common.collect.Multimap<java.lang.String,java.lang.String> locations, com.google.common.collect.Multimap<java.lang.String,java.lang.ClassLoader> loaders)

Method Summary

Modifier and Type	Method and Description
com.google.common.collect.Multimap<java.lang.String,java.lang.ClassLoader>	getLoaders() Returned map contains not only custom class loaders but also default class loader (this is important to grant proper resource override sequence).
com.google.common.collect.Multimap<java.lang.String,java.lang.String>	getLocations()
java.util.Set<java.lang.ClassLoader>	getMatchingLoaders(java.lang.String assetPath) NOTE: method will return not only custom class loaders but also default application loader (AssetSources.DEFAULT_LOADER) because otherwise it will be impossible to preserve intended loading order.
java.util.List<java.lang.String>	getMatchingLocations(java.lang.String url) Supposed to be used for error reporting.
java.lang.String	getPrimaryLocation()
java.lang.String	getRelativePath(java.lang.String path) Checks if provided path is an absolute path into primary location and returns relative url instead.
java.net.URL	load(java.lang.String assetPath) Loads asset from classpath.
AssetLookup.AssetLocation	lookup(java.lang.String path) General lookup mechanism (used by lookupUrl(String) and lookupPath(String) shortcuts.
java.lang.String	lookupPath(java.lang.String url) Same as lookupUrl(String) but returns resolved absolute location in classpath (may be in custom class loader).
java.net.URL	lookupUrl(java.lang.String url) Lookup asset in classpath by path (relative to application root).

Methods inherited from class java.lang.Object

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

Constructor Detail

AssetLookup

public AssetLookup(java.lang.String primaryLocation,
                   com.google.common.collect.Multimap<java.lang.String,java.lang.String> locations,
                   com.google.common.collect.Multimap<java.lang.String,java.lang.ClassLoader> loaders)

Method Detail

getPrimaryLocation

public java.lang.String getPrimaryLocation()

Returns:

main application assets classpath path

getLocations

public com.google.common.collect.Multimap<java.lang.String,java.lang.String> getLocations()

Returns:

assets mapping paths

getLoaders

public com.google.common.collect.Multimap<java.lang.String,java.lang.ClassLoader> getLoaders()

Returned map contains not only custom class loaders but also default class loader (this is important to grant proper resource override sequence). Default class loader is AssetSources.DEFAULT_LOADER.

Returns:

classpath paths mapping to class loaders

getRelativePath

public java.lang.String getRelativePath(java.lang.String path)

Checks if provided path is an absolute path into primary location and returns relative url instead. It cuts off application url prefix in order to resolve proper path under all registered locations. For example, if application registered for "/app/*" then incoming resource request may be "/app/css/style.css", but actual resource path is "css/style.css" which we will look under classpath (classpath locations also registered by root locations so if app declared its resources under "com.foo.app" package then resource will be searched as "com.foo.app.css/style.css" (the same for all extended locations).

Parameters:

path - possibly absolute path

Returns:

relative path (without primary location part if detected)

lookupUrl

public java.net.URL lookupUrl(java.lang.String url)

Lookup asset in classpath by path (relative to application root). Assets, registered to exact path processed in priority. For example, if assets registered for '/foo/bar/' path then path '/foo/bar/sample.css' will be checked first in path-specific assets. Multiple asset packages copuld be configured on each path: assets checked in registration-reverse order to grant regitstration order priority (resources from package, registered later are prioritized).

Url may contain application mapping url (so be url relative to server root): getRelativePath(String) will be used to cut off mapping prefix.

Parameters:

url - path to find asset for

Returns:

matched asset or null if not found

lookupPath

public java.lang.String lookupPath(java.lang.String url)

Same as lookupUrl(String) but returns resolved absolute location in classpath (may be in custom class loader). This has to be used for templates resolution (views) which does not support direct file specification. It is assumed that later such path will be loaded with load(String) which will find proper class loader (again).

Url may contain application mapping url (so be url relative to server root): getRelativePath(String) will be used to cut off mapping prefix.

Parameters:

url - path to find asset for

Returns:

matched absolute classpath path or null if not found

load

public java.net.URL load(java.lang.String assetPath)

Loads asset from classpath. Will select proper class loader if custom class loaders used. It is assumed to mainly load paths after lookupPath(String), but may be used as general loading mechanism.

Will check first if provided path is already an absolute classpath location (assumed to be resolved with lookupPath(String)) and if nothing found perform full relative matching with lookupUrl(String) (kind of fallback mechanism).

Parameters:

assetPath - exact classpath path

Returns:

found resource or null

lookup

public AssetLookup.AssetLocation lookup(java.lang.String path)

General lookup mechanism (used by lookupUrl(String) and lookupPath(String) shortcuts.

Lookup asset in classpath by path (relative to application root). Assets, registered to exact path processed in priority. For example, if assets registered for '/foo/bar/' path then path '/foo/bar/sample.css' will be checked first in path-specific assets. Multiple asset packages could be configured on each path: assets checked in registration-reverse order to grant regitstration order priority (resources from package, registered later are prioritized).

Parameters:

path - path to find asset for

Returns:

matched location or null if not found

getMatchingLocations

public java.util.List<java.lang.String> getMatchingLocations(java.lang.String url)

Supposed to be used for error reporting. Return locations in package notion.

Parameters:

url - url relative to application root

Returns:

matching classpath locations (where resource may be found)

getMatchingLoaders

public java.util.Set<java.lang.ClassLoader> getMatchingLoaders(java.lang.String assetPath)

NOTE: method will return not only custom class loaders but also default application loader (AssetSources.DEFAULT_LOADER) because otherwise it will be impossible to preserve intended loading order.

It may return empty set ONLY if requested absolute path is outside of any registered asset locations (incorrect usage).

Parameters:

assetPath - classpath path (absolute!)

Returns:

set (to avoid default classloader duplicates) of custom class loaders