com.unboundid.directory.sdk.common.api
Class VelocityContextProvider

java.lang.Object
  com.unboundid.directory.sdk.common.api.VelocityContextProvider

All Implemented Interfaces:

Configurable, ExampleUsageProvider, Reconfigurable<VelocityContextProviderConfig>, UnboundIDExtension

@Extensible
@DirectoryServerExtension
@DirectoryProxyServerExtension(appliesToLocalContent=true,
                               appliesToRemoteContent=false)
@SynchronizationServerExtension(appliesToLocalContent=true,
                                appliesToSynchronizedContent=false)
@MetricsEngineExtension
@IdentityBrokerExtension
@ThreadSafety(level=INTERFACE_THREADSAFE)
public abstract class VelocityContextProvider
extends java.lang.Object
implements UnboundIDExtension, Reconfigurable<VelocityContextProviderConfig>, ExampleUsageProvider

This class defines an API that must be implemented by extensions which contribute content to server pages authored as Velocity templates. These pages are rendered by the Velocity HTTP Servlet Extension included with the server. During rendering of a Velocity page, the template is merged with a 'context' that provides values for variables, properties, and method references in the template.

A context provider can be restricted to contributing content for certain pages by specifying one or more included or excluded views names. A view name is the URL request path to to a template that does not include the HTTP servlet extension's base context path, nor a starting path separator. So for example if a template was accessible by the URL http://localhost:8080/view/path/to/template the view name would be 'path/to/template'.

Configuring Velocity Context Providers

In order to configure a Velocity context provider created using this API, use a command like:

      dsconfig create-virtual-attribute \
           --extension-name "{extension}" \
           --provider-name "{provider}" \
           --type third-party \
           --set enabled:true \
           --set "extension-class:{class-name}" \
           --set "extension-argument:{name=value}"
 

where "{extension}" is the name of the Velocity HTTP servlet extension, ("Velocity" by default) "{provider}" is the name to use for the Velocity context provider instance, "{class-name}" is the fully-qualified name of the Java class that extends com.unboundid.directory.sdk.common.api.VelocityContextProvider, and "{name=value}" represents name-value pairs for any arguments to provide to the virtual attribute provider. If multiple arguments should be provided to the virtual attribute provider, then the "--set extension-argument:{name=value}" option should be provided multiple times.

Constructor Summary

VelocityContextProvider()

Method Summary

com.unboundid.ldap.sdk.ResultCode	applyConfiguration(VelocityContextProviderConfig config, com.unboundid.util.args.ArgumentParser parser, java.util.List<java.lang.String> adminActionsRequired, java.util.List<java.lang.String> messages) Attempts to apply the configuration from the provided argument parser to this extension.
void	defineConfigArguments(com.unboundid.util.args.ArgumentParser parser) Updates the provided argument parser to define any configuration arguments which may be used by this extension.
void	finalizeVelocityContextProvider() Performs any cleanup which may be necessary when this virtual attribute provider is to be taken out of service.
abstract java.lang.String[]	getExtensionDescription() Retrieves a human-readable description for this extension.
abstract java.lang.String	getExtensionName() Retrieves a human-readable name for this extension.
protected <T> T	getNamedObject(java.lang.String name, javax.servlet.http.HttpServletRequest request) Gets an object from the current user session or servlet context depending on the object scope currently configured for this provider.
static <T> T	getNamedObject(java.lang.String name, javax.servlet.http.HttpServletRequest request, VelocityContextProviderConfig.ObjectScope scope) Gets an object from the current user session or servlet context depending on the object scope currently configured for this provider.
void	initializeVelocityContextProvider(ServerContext serverContext, VelocityContextProviderConfig config, com.unboundid.util.args.ArgumentParser parser) Initializes this Velocity context provider.
boolean	isConfigurationAcceptable(VelocityContextProviderConfig config, com.unboundid.util.args.ArgumentParser parser, java.util.List<java.lang.String> unacceptableReasons) Indicates whether the configuration represented by the provided argument parser is acceptable for use by this extension.
protected void	setNamedObject(java.lang.String name, java.lang.Object object, javax.servlet.http.HttpServletRequest request) Stores an object in current user request, session or servlet context depending on the object scope currently configured for this provider.
static void	setNamedObject(java.lang.String name, java.lang.Object object, javax.servlet.http.HttpServletRequest request, VelocityContextProviderConfig.ObjectScope scope) Stores an object in current user request, session or servlet context depending on the object scope currently configured for this provider.
abstract void	updateContext(VelocityContext context, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Return an object to be placed into a Velocity context for rending a template.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.unboundid.directory.sdk.common.internal.ExampleUsageProvider

getExamplesArgumentSets

Constructor Detail

VelocityContextProvider

public VelocityContextProvider()

Method Detail

getExtensionName

public abstract java.lang.String getExtensionName()

Retrieves a human-readable name for this extension.

Specified by:

getExtensionName in interface UnboundIDExtension

Returns:

A human-readable name for this extension.

getExtensionDescription

public abstract java.lang.String[] getExtensionDescription()

Retrieves a human-readable description for this extension. Each element of the array that is returned will be considered a separate paragraph in generated documentation.

Specified by:

getExtensionDescription in interface UnboundIDExtension

Returns:

A human-readable description for this extension, or null or an empty array if no description should be available.

defineConfigArguments

public void defineConfigArguments(com.unboundid.util.args.ArgumentParser parser)
                           throws com.unboundid.util.args.ArgumentException

Updates the provided argument parser to define any configuration arguments which may be used by this extension. The argument parser may also be updated to define relationships between arguments (e.g., to specify required, exclusive, or dependent argument sets).

Specified by:

defineConfigArguments in interface Configurable

Parameters:

parser - The argument parser to be updated with the configuration arguments which may be used by this extension.

Throws:

com.unboundid.util.args.ArgumentException - If a problem is encountered while updating the provided argument parser.

initializeVelocityContextProvider

public void initializeVelocityContextProvider(ServerContext serverContext,
                                              VelocityContextProviderConfig config,
                                              com.unboundid.util.args.ArgumentParser parser)
                                       throws com.unboundid.ldap.sdk.LDAPException

Initializes this Velocity context provider.

Parameters:

serverContext - A handle to the server context for the server in which this extension is running.

config - The general configuration for this Velocity context provider.

parser - The argument parser which has been initialized from the configuration for this Velocity context provider.

Throws:

com.unboundid.ldap.sdk.LDAPException - If a problem occurs while initializing this context provider.

isConfigurationAcceptable

public boolean isConfigurationAcceptable(VelocityContextProviderConfig config,
                                         com.unboundid.util.args.ArgumentParser parser,
                                         java.util.List<java.lang.String> unacceptableReasons)

Indicates whether the configuration represented by the provided argument parser is acceptable for use by this extension. The parser will have been used to parse any configuration available for this extension, and any automatic validation will have been performed. This method may be used to perform any more complex validation which cannot be performed automatically by the argument parser.

Specified by:

isConfigurationAcceptable in interface Reconfigurable<VelocityContextProviderConfig>

Parameters:

config - The general configuration for this extension.

parser - The argument parser that has been used to parse the proposed configuration for this extension.

unacceptableReasons - A list to which messages may be added to provide additional information about why the provided configuration is not acceptable.

Returns:

true if the configuration in the provided argument parser appears to be acceptable, or false if not.

applyConfiguration

public com.unboundid.ldap.sdk.ResultCode applyConfiguration(VelocityContextProviderConfig config,
                                                            com.unboundid.util.args.ArgumentParser parser,
                                                            java.util.List<java.lang.String> adminActionsRequired,
                                                            java.util.List<java.lang.String> messages)

Attempts to apply the configuration from the provided argument parser to this extension.

Specified by:

applyConfiguration in interface Reconfigurable<VelocityContextProviderConfig>

Parameters:

config - The general configuration for this extension.

parser - The argument parser that has been used to parse the new configuration for this extension.

adminActionsRequired - A list to which messages may be added to provide additional information about any additional administrative actions that may be required to apply some of the configuration changes.

messages - A list to which messages may be added to provide additional information about the processing performed by this method.

Returns:

A result code providing information about the result of applying the configuration change. A result of SUCCESS should be used to indicate that all processing completed successfully. Any other result will indicate that a problem occurred during processing.

finalizeVelocityContextProvider

public void finalizeVelocityContextProvider()

Performs any cleanup which may be necessary when this virtual attribute provider is to be taken out of service.

updateContext

public abstract void updateContext(VelocityContext context,
                                   javax.servlet.http.HttpServletRequest request,
                                   javax.servlet.http.HttpServletResponse response)

Return an object to be placed into a Velocity context for rending a template.

Parameters:

context - to update.

request - for the the view implemented by a template.

response - to the client.

getNamedObject

protected <T> T getNamedObject(java.lang.String name,
                               javax.servlet.http.HttpServletRequest request)

Gets an object from the current user session or servlet context depending on the object scope currently configured for this provider. This method can be used as a convenience for providers the maintain a set of context objects for a particular scope.

Type Parameters:

T - the type of object to return. If an object exists in the current scope with the given name but is not of type T this method returns null

Parameters:

name - of the object.

request - current user request.

Returns:

the named object or null if no object exists by the provided name or an input parameter is (@code null}.

setNamedObject

protected void setNamedObject(java.lang.String name,
                              java.lang.Object object,
                              javax.servlet.http.HttpServletRequest request)

Stores an object in current user request, session or servlet context depending on the object scope currently configured for this provider. This method can be used as a convenience for providers the maintain a set of context objects for a particular scope.

Parameters:

name - of the object.

object - to store.

request - current user request.

getNamedObject

public static <T> T getNamedObject(java.lang.String name,
                                   javax.servlet.http.HttpServletRequest request,
                                   VelocityContextProviderConfig.ObjectScope scope)

Gets an object from the current user session or servlet context depending on the object scope currently configured for this provider. This method can be used as a convenience for providers the maintain a set of context objects for a particular scope.

Type Parameters:

T - the type of object to return. If an object exists in the current scope with the given name but is not of type T this method returns null

Parameters:

name - of the object.

request - current user request.

scope - from which to retrieve the object.

Returns:

the named object or null if no object exists by the provided name or an input parameter is (@code null}.

setNamedObject

public static void setNamedObject(java.lang.String name,
                                  java.lang.Object object,
                                  javax.servlet.http.HttpServletRequest request,
                                  VelocityContextProviderConfig.ObjectScope scope)

Stores an object in current user request, session or servlet context depending on the object scope currently configured for this provider. This method can be used as a convenience for providers the maintain a set of context objects for a particular scope.

Parameters:

name - of the object.

object - to store.

request - current user request.

scope - in which to set the object.