VelocityContextProvider (UnboundID Server SDK)

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 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()

Constructors
Constructor and Description
`VelocityContextProvider()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`ResultCode`	`applyConfiguration(VelocityContextProviderConfig config, 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(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, ArgumentParser parser)` Initializes this Velocity context provider.
`boolean`	`isConfigurationAcceptable(VelocityContextProviderConfig config, 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(ArgumentParser parser)
                           throws 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:
    
    ArgumentException - If a problem is encountered while updating the provided argument parser.
  - initializeVelocityContextProvider
```
public void initializeVelocityContextProvider(ServerContext serverContext,
                                              VelocityContextProviderConfig config,
                                              ArgumentParser parser)
                                       throws 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:
    
    LDAPException - If a problem occurs while initializing this context provider.
  - isConfigurationAcceptable
```
public boolean isConfigurationAcceptable(VelocityContextProviderConfig config,
                                         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 ResultCode applyConfiguration(VelocityContextProviderConfig config,
                                     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.

Class VelocityContextProvider

Configuring Velocity Context Providers

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

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

Constructor Detail

VelocityContextProvider

Method Detail

getExtensionName

getExtensionDescription

defineConfigArguments

initializeVelocityContextProvider

isConfigurationAcceptable

applyConfiguration

finalizeVelocityContextProvider

handleDelete

handleGet

handleHead

handleOptions

handlePatch

handlePost

handlePut

handleTrace

handleAdditionalMethod

updateContext

getNamedObject

setNamedObject

getNamedObject

setNamedObject