Package com.unboundid.directory.sdk.common.api

Class 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.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method 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

    • Method Detail

      • 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.