Package net.shibboleth.shared.spring.velocity

# Class VelocityEngineFactory

java.lang.Object
net.shibboleth.shared.spring.velocity.VelocityEngineFactory

Direct Known Subclasses:
  `VelocityConfigurer`, `VelocityEngineFactoryBean`

public class VelocityEngineFactory extends Object
Factory that configures a VelocityEngine. Can be used standalone, but typically you will either use `VelocityEngineFactoryBean` for preparing a VelocityEngine as bean reference, or `VelocityConfigurer` for web views.

The optional "configLocation" property sets the location of the Velocity properties file, within the current application. Velocity properties can be overridden via "velocityProperties", or even completely specified locally, avoiding the need for an external properties file.

The "resourceLoaderPath" property can be used to specify the Velocity resource loader path via Spring's Resource abstraction, possibly relative to the Spring application context.

The simplest way to use this class is to specify a `"resourceLoaderPath"`; the VelocityEngine typically then does not need any further configuration.

Since:
  6.0.0
See Also:
  - `setConfigLocation(org.springframework.core.io.Resource)`
  - `setVelocityProperties(java.util.Properties)`
  - `setResourceLoaderPath(java.lang.String)`
  - `createVelocityEngine()`
  - `VelocityEngineFactoryBean`
  - `VelocityConfigurer`
  - `VelocityEngine`

## Field Summary

Fields
Modifier and Type
Field
Description
`private Resource`
`configLocation`
Source of configuration.
`private final org.slf4j.Logger`
`log`
Class logger.
`private boolean`
`preferFileSystemAccess`
Whether to favor file system lookup first.
`private ResourceLoader`
`resourceLoader`
Resource loader.
`private String`
`resourceLoaderPath`
Path to load resources from.
`private final Map<String,Object>`
`velocityProperties`
Configuration properties.

## Constructor Summary

Constructors
Constructor
Description
`VelocityEngineFactory()`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`org.apache.velocity.app.VelocityEngine`
`createVelocityEngine()`
Prepare the VelocityEngine instance and return it.
`protected void`
`initSpringResourceLoader(org.apache.velocity.app.VelocityEngine velocityEngine, String path)`
Initialize a SpringResourceLoader for the given VelocityEngine.
`protected void`
`initVelocityResourceLoader(org.apache.velocity.app.VelocityEngine velocityEngine, String loaderPath)`
Initialize a Velocity resource loader for the given VelocityEngine: either a standard Velocity FileResourceLoader or a SpringResourceLoader.
`protected org.apache.velocity.app.VelocityEngine`
`newVelocityEngine()`
Return a new VelocityEngine.
`protected void`
`postProcessVelocityEngine(org.apache.velocity.app.VelocityEngine velocityEngine)`
To be implemented by subclasses that want to perform custom post-processing of the VelocityEngine after the FactoryBean performed its default configuration (but before VelocityEngine.init).
`void`
`setConfigLocation(Resource location)`
Set the location of the Velocity config file.
`void`
`setPreferFileSystemAccess(boolean flag)`
Set whether to prefer file system access for template loading.
`void`
`setResourceLoader(ResourceLoader loader)`
Set the Spring ResourceLoader to use for loading Velocity template files.
`void`
`setResourceLoaderPath(String paths)`
Set the Velocity resource loader path via a Spring resource location.
`void`
`setVelocityProperties(Properties props)`
Set Velocity properties, like "file.resource.loader.path".
`void`
`setVelocityPropertiesMap(Map<String,Object> map)`
Set Velocity properties as Map, to allow for non-String values like "ds.resource.loader.instance".

### Methods inherited from class java.lang.Object

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

## Field Details

### log

@Nonnull private final org.slf4j.Logger log
Class logger.

### configLocation

@Nullable private Resource configLocation
Source of configuration.

### velocityProperties

@Nonnull @NullableElements private final Map<String,Object> velocityProperties
Configuration properties.

### resourceLoaderPath

@Nullable private String resourceLoaderPath
Path to load resources from.

### resourceLoader

@Nullable private ResourceLoader resourceLoader
Resource loader.

### preferFileSystemAccess

private boolean preferFileSystemAccess
Whether to favor file system lookup first.

## Constructor Details

### VelocityEngineFactory

public VelocityEngineFactory()
Constructor.

## Method Details

### setConfigLocation

public void setConfigLocation(@Nullable Resource location)
Set the location of the Velocity config file.

Alternatively, you can specify all properties locally.

Parameters:
  `location` - configuration resource
See Also:
  - `setVelocityProperties(java.util.Properties)`
  - `setResourceLoaderPath(java.lang.String)`

### setVelocityProperties

public void setVelocityProperties(@Nullable Properties props)
Set Velocity properties, like "file.resource.loader.path".

Can be used to override values in a Velocity config file, or to specify all necessary properties locally.

Note that the Velocity resource loader path also be set to any Spring resource location via the "resourceLoaderPath" property. Setting it here is just necessary when using a non-file-based resource loader.

Parameters:
  `props` - additional properties
See Also:
  - `setVelocityPropertiesMap(java.util.Map<java.lang.String, java.lang.Object>)`
  - `setConfigLocation(org.springframework.core.io.Resource)`
  - `setResourceLoaderPath(java.lang.String)`

### setVelocityPropertiesMap

public void setVelocityPropertiesMap(@Nullable @NullableElements Map<String,Object> map)
Set Velocity properties as Map, to allow for non-String values like "ds.resource.loader.instance".

Parameters:
  `map` - properties as map
See Also:
  - `setVelocityProperties(java.util.Properties)`

### setResourceLoaderPath

public void setResourceLoaderPath(@Nullable String paths)
Set the Velocity resource loader path via a Spring resource location.

Accepts multiple locations in Velocity's comma-separated path style.

When populated via a String, standard URLs like "file:" and "classpath:" pseudo URLs are supported, as understood by ResourceLoader. Allows for relative paths when running in an ApplicationContext.

Will define a path for the default Velocity resource loader with the name "file". If the specified resource cannot be resolved to a `java.io.File`, a generic SpringResourceLoader will be used under the name "spring", without modification detection.

Note that resource caching will be enabled in any case. With the file resource loader, the last-modified timestamp will be checked on access to detect changes. With SpringResourceLoader, the resource will be cached forever (for example for class path resources).

To specify a modification check interval for files, use Velocity's standard "file.resource.loader.modificationCheckInterval" property. By default, the file timestamp is checked on every access (which is surprisingly fast). Of course, this just applies when loading resources from the file system.

To enforce the use of SpringResourceLoader, i.e. to not resolve a path as file system resource in any case, turn off the "preferFileSystemAccess" flag. See the latter's javadoc for details.

Parameters:
  `paths` - comma-separated paths
See Also:
  - `setResourceLoader(org.springframework.core.io.ResourceLoader)`
  - `setVelocityProperties(java.util.Properties)`
  - `setPreferFileSystemAccess(boolean)`
  - `SpringResourceLoader`
  - `FileResourceLoader`

### setResourceLoader

public void setResourceLoader(@Nullable ResourceLoader loader)
Set the Spring ResourceLoader to use for loading Velocity template files.

The default is DefaultResourceLoader. Will get overridden by the ApplicationContext if running in a context.

Parameters:
  `loader` - resource loader
See Also:
  - `DefaultResourceLoader`
  - `ApplicationContext`

### setPreferFileSystemAccess

public void setPreferFileSystemAccess(boolean flag)
Set whether to prefer file system access for template loading.

File system access enables hot detection of template changes.

If this is enabled, VelocityEngineFactory will try to resolve the specified "resourceLoaderPath" as file system resource (which will work for expanded class path resources and ServletContext resources too).

Default is "true". Turn this off to always load via SpringResourceLoader (i.e. as stream, without hot detection of template changes), which might be necessary if some of your templates reside in an expanded classes directory while others reside in jar files.

Parameters:
  `flag` - flag to set
See Also:
  - `setResourceLoaderPath(java.lang.String)`

### createVelocityEngine

@Nonnull public org.apache.velocity.app.VelocityEngine createVelocityEngine() throws IOException, org.apache.velocity.exception.VelocityException
Prepare the VelocityEngine instance and return it.

Returns:
  the VelocityEngine instance
Throws:
  `IOException` - if the config file wasn't found
  `org.apache.velocity.exception.VelocityException` - on Velocity initialization failure

### newVelocityEngine

@Nonnull protected org.apache.velocity.app.VelocityEngine newVelocityEngine() throws IOException, org.apache.velocity.exception.VelocityException
Return a new VelocityEngine.

Subclasses can override this for custom initialization, or for using a mock object for testing.

Called by `createVelocityEngine()`.

Returns:
  the VelocityEngine instance
Throws:
  `IOException` - if a config file wasn't found
  `org.apache.velocity.exception.VelocityException` - on Velocity initialization failure
See Also:
  - `createVelocityEngine()`

### initVelocityResourceLoader

protected void initVelocityResourceLoader(@Nonnull org.apache.velocity.app.VelocityEngine velocityEngine, @Nullable String loaderPath)
Initialize a Velocity resource loader for the given VelocityEngine: either a standard Velocity FileResourceLoader or a SpringResourceLoader.

Parameters:
  `velocityEngine` - the VelocityEngine to configure
  `loaderPath` - the path to load Velocity resources from
See Also:
  - `FileResourceLoader`
  - `SpringResourceLoader`
  - `initSpringResourceLoader(org.apache.velocity.app.VelocityEngine, java.lang.String)`
  - `createVelocityEngine()`

### initSpringResourceLoader

protected void initSpringResourceLoader(@Nonnull org.apache.velocity.app.VelocityEngine velocityEngine, @Nullable String path)
Initialize a SpringResourceLoader for the given VelocityEngine.

Called by `initVelocityResourceLoader`.

Parameters:
  `velocityEngine` - the VelocityEngine to configure
  `path` - the path to load Velocity resources from
See Also:
  - `SpringResourceLoader`
  - `initVelocityResourceLoader(org.apache.velocity.app.VelocityEngine, java.lang.String)`

### postProcessVelocityEngine

protected void postProcessVelocityEngine(@Nonnull org.apache.velocity.app.VelocityEngine velocityEngine) throws IOException, org.apache.velocity.exception.VelocityException
To be implemented by subclasses that want to perform custom post-processing of the VelocityEngine after the FactoryBean performed its default configuration (but before VelocityEngine.init).

Parameters:
  `velocityEngine` - the current VelocityEngine
Throws:
  `IOException` - if a config file wasn't found
  `org.apache.velocity.exception.VelocityException` - on Velocity initialization failure
See Also:
  - `createVelocityEngine()`
  - `VelocityEngine.init()`