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
@BrokerExtension
@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'.

In addition to contributing content for views, a context provider can also be configured to add header fields to HTTP responses using the request-header configuration property. Header field values specified the by a context provider override values for identical fields names for which the Velocity HTTP Servlet Extension is configured to add to responses.

Context providers are restricted to servicing requests for the configured set of HTTP operations. By default, only the HTTP GET method is enabled though this can be changed by updating the http-method configuration property. Implementations should abide by the conventions mandated by the HTTP method specification. For example, an implementation that handles the GET method should be restricted to retrieval only and not introduce any persistent side-effects that would change the state of the server.

Configuring Velocity Context Providers

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

      dsconfig create-velocity-context-provider \
           --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

Constructors

Constructor and Description
VelocityContextProvider()

Method Summary

Methods

Modifier and Type	Method and Description
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	handleAdditionalMethod(VelocityContext context, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Handle an HTTP method not already handled by one of the other handleXXX methods.
void	handleDelete(VelocityContext context, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Handle an HTTP DELETE request.
void	handleGet(VelocityContext context, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Handle an HTTP GET request.
void	handleHead(VelocityContext context, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Handle an HTTP HEAD request.
void	handleOptions(VelocityContext context, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Handle an HTTP OPTIONS request.
void	handlePatch(VelocityContext context, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Handle an HTTP PATCH request.
void	handlePost(VelocityContext context, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Handle an HTTP POST request.
void	handlePut(VelocityContext context, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Handle an HTTP PUT request.
void	handleTrace(VelocityContext context, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Handle an HTTP TRACE request.
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.
void	updateContext(VelocityContext context, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) This method is called following a call to one of the handleXXX methods and may be used for logic that is independent of the HTTP operation requested.

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.

handleDelete

public void handleDelete(VelocityContext context,
                javax.servlet.http.HttpServletRequest request,
                javax.servlet.http.HttpServletResponse response)
                  throws java.io.IOException

Handle an HTTP DELETE request. Implementations should be idempotent in the sense that the side-effects of a single call to this method are the same as N > 0 identical requests.

Parameters:

context - to update.

request - for the view implemented by a template.

response - to the client.

Throws:

java.io.IOException - if the provider has a problem related to processing the response such as sending an error to the client.

handleGet

public void handleGet(VelocityContext context,
             javax.servlet.http.HttpServletRequest request,
             javax.servlet.http.HttpServletResponse response)
               throws java.io.IOException

Handle an HTTP GET request. Implementations should be restricted to retrieval operations only, ensuring there are no persistent side-effects generated by the server as a result of this method being called.

Parameters:

context - to update.

request - for the view implemented by a template.

response - to the client.

Throws:

java.io.IOException - if the provider has a problem related to processing the response such as sending an error to the client.

handleHead

public void handleHead(VelocityContext context,
              javax.servlet.http.HttpServletRequest request,
              javax.servlet.http.HttpServletResponse response)
                throws java.io.IOException

Handle an HTTP HEAD request. Implementations should be restricted to retrieval operations only, ensuring there are no persistent side-effects generated by the server as a result of this method being called.

Parameters:

context - to update.

request - for the view implemented by a template.

response - to the client.

Throws:

java.io.IOException - if the provider has a problem related to processing the response such as sending an error to the client.

handleOptions

public void handleOptions(VelocityContext context,
                 javax.servlet.http.HttpServletRequest request,
                 javax.servlet.http.HttpServletResponse response)
                   throws java.io.IOException

Handle an HTTP OPTIONS request. Implementations should ensure there are no persistent side-effects generated by the server as a result of this method being called.

Parameters:

context - to update.

request - for the view implemented by a template.

response - to the client.

Throws:

java.io.IOException - if the provider has a problem related to processing the response such as sending an error to the client.

handlePatch

public void handlePatch(VelocityContext context,
               javax.servlet.http.HttpServletRequest request,
               javax.servlet.http.HttpServletResponse response)
                 throws java.io.IOException

Handle an HTTP PATCH request.

Parameters:

context - to update.

request - for the view implemented by a template.

response - to the client.

Throws:

java.io.IOException - if the provider has a problem related to processing the response such as sending an error to the client.

handlePost

public void handlePost(VelocityContext context,
              javax.servlet.http.HttpServletRequest request,
              javax.servlet.http.HttpServletResponse response)
                throws java.io.IOException

Handle an HTTP POST request.

Parameters:

context - to update.

request - for the view implemented by a template.

response - to the client.

Throws:

java.io.IOException - if the provider has a problem related to processing the response such as sending an error to the client.

handlePut

public void handlePut(VelocityContext context,
             javax.servlet.http.HttpServletRequest request,
             javax.servlet.http.HttpServletResponse response)
               throws java.io.IOException

Handle an HTTP PUT request. Implementations should be idempotent in the sense that the side-effects of a single call to this method are the same as N > 0 identical requests.

Parameters:

context - to update.

request - for the view implemented by a template.

response - to the client.

Throws:

java.io.IOException - if the provider has a problem related to processing the response such as sending an error to the client.

handleTrace

public void handleTrace(VelocityContext context,
               javax.servlet.http.HttpServletRequest request,
               javax.servlet.http.HttpServletResponse response)
                 throws java.io.IOException

Handle an HTTP TRACE request. Implementations should ensure there are no persistent side-effects generated by the server as a result of this method being called.

Parameters:

context - to update.

request - for the view implemented by a template.

response - to the client.

Throws:

java.io.IOException - if the provider has a problem related to processing the response such as sending an error to the client.

handleAdditionalMethod

public void handleAdditionalMethod(VelocityContext context,
                          javax.servlet.http.HttpServletRequest request,
                          javax.servlet.http.HttpServletResponse response)
                            throws java.io.IOException

Handle an HTTP method not already handled by one of the other handleXXX methods. Implementations should check the value of the request's getMethod() method and take whatever action is necessary to fulfill the request before updating the context. Unexpected HTTP methods should result in the client sending an HTTP 405 Method Not Allowed response.

Parameters:

context - to update.

request - for the view implemented by a template.

response - to the client.

Throws:

java.io.IOException - if the provider has a problem related to processing the response such as sending an error to the client.

updateContext

public void updateContext(VelocityContext context,
                 javax.servlet.http.HttpServletRequest request,
                 javax.servlet.http.HttpServletResponse response)
                   throws java.io.IOException

This method is called following a call to one of the handleXXX methods and may be used for logic that is independent of the HTTP operation requested. HTTP method-specific code such as request attribute or form data processing should be restricted to the appropriate handleXXX method.

Parameters:

context - to update.

request - for the view implemented by a template.

response - to the client.

Throws:

java.io.IOException - if the provider has a problem related to processing the response such as sending an error 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.