Package com.unboundid.directory.sdk.proxy.api

Class ProxyTransformation

  • All Implemented Interfaces:
    Configurable, ExampleUsageProvider, Reconfigurable<ProxyTransformationConfig>, UnboundIDExtension
    @Extensible
@DirectoryProxyServerExtension(appliesToLocalContent=false,
                               appliesToRemoteContent=true)
@ThreadSafety(level=INTERFACE_THREADSAFE)
public abstract class ProxyTransformation
extends java.lang.Object
implements UnboundIDExtension, Reconfigurable<ProxyTransformationConfig>, ExampleUsageProvider
    This class defines an API that must be implemented by extensions which are used to transform requests and/or responses as they pass through the Directory Proxy Server. They may be used to alter the contents of any add, bind, compare, delete, modify, modify DN, or search request or result passing through the Directory Proxy Server, or they may cause a result to be returned to the client without it being forwarded to a backend server. In addition, transformations may be applied to search result entries and references to be returned to the client, or those entries and references may be silently dropped so that they are not returned.

    Configuring Proxy Transformations

    In order to configure a proxy transformation created using this API, use a command like: 
          dsconfig create-proxy-transformation \
           --transformation-name "{transformation-name}" \
           --type third-party \
           --set enabled:true \
           --set "extension-class:{class-name}" \
           --set "extension-argument:{name=value}"
    where "{transformation-name}" is the name to use for the proxy transformation instance, "{class-name}" is the fully-qualified name of the Java class that extends com.unboundid.directory.sdk.proxy.api.ProxyTransformation, and "{name=value}" represents name-value pairs for any arguments to provide to the proxy transformation. If multiple arguments should be provided to the proxy transformation, then the "--set extension-argument:{name=value}" option should be provided multiple times.
    See Also:
    ScriptedProxyTransformation

    • Constructor Detail

      • ProxyTransformation

        public ProxyTransformation()
        Creates a new instance of this proxy transformation. All proxy transformation implementations must include a default constructor, but any initialization should generally be done in the initializeProxyTransformation method.

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

      • initializeProxyTransformation

        public void initializeProxyTransformation​(ProxyServerContext serverContext,
                                          ProxyTransformationConfig config,
                                          ArgumentParser parser)
                                   throws LDAPException
        Initializes this proxy transformation.
        Parameters:
        serverContext - A handle to the server context for the Directory Proxy server in which this extension is running.
        config - The general configuration for this proxy transformation.
        parser - The argument parser which has been initialized from the configuration for this proxy transformation.
        Throws:
        LDAPException - If a problem occurs while initializing this proxy transformation.

      • isConfigurationAcceptable

        public boolean isConfigurationAcceptable​(ProxyTransformationConfig 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<ProxyTransformationConfig>
        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​(ProxyTransformationConfig 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<ProxyTransformationConfig>
        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.

      • finalizeProxyTransformation

        public void finalizeProxyTransformation()
        Performs any cleanup which may be necessary when this proxy transformation is to be taken out of service.

      • transformAddRequest

        public AddRequest transformAddRequest​(ProxyOperationContext operationContext,
                                      AddRequest addRequest)
                               throws LDAPException
        Applies any necessary transformation to the provided add request.
        Parameters:
        operationContext - Information about the operation being processed in the Directory Proxy Server.
        addRequest - The add request to be transformed.
        Returns:
        A new add request which has been transformed as necessary, or the original request if no transformation is required or the provided add request has been updated in place.
        Throws:
        LDAPException - If a problem is encountered while processing the transformation, or if the provided request should not be forwarded to a backend server.

      • transformAddResult

        public LDAPResult transformAddResult​(ProxyOperationContext operationContext,
                                     ReadOnlyAddRequest addRequest,
                                     LDAPResult addResult)
        Applies any necessary transformation to the provided add result.
        Parameters:
        operationContext - Information about the operation being processed in the Directory Proxy Server.
        addRequest - The add request that was processed.
        addResult - The add result to be transformed.
        Returns:
        A new add result which has been transformed as necessary, or the original result if no transformation is required or the provided add result has been updated in place.

      • transformBindRequest

        public BindRequest transformBindRequest​(ProxyOperationContext operationContext,
                                        BindRequest bindRequest)
                                 throws LDAPException
        Applies any necessary transformation to the provided bind request.
        Parameters:
        operationContext - Information about the operation being processed in the Directory Proxy Server.
        bindRequest - The bind request to be transformed.
        Returns:
        A new bind request which has been transformed as necessary, or the original request if no transformation is required.
        Throws:
        LDAPException - If a problem is encountered while processing the transformation, or if the provided request should not be forwarded to a backend server.

      • transformBindResult

        public BindResult transformBindResult​(ProxyOperationContext operationContext,
                                      BindRequest bindRequest,
                                      BindResult bindResult)
        Applies any necessary transformation to the provided bind request.
        Parameters:
        operationContext - Information about the operation being processed in the Directory Proxy Server.
        bindRequest - The bind request that was processed.
        bindResult - The bind result to be transformed.
        Returns:
        A new bind result which has been transformed as necessary, or the original result if no transformation is required.

      • transformCompareRequest

        public CompareRequest transformCompareRequest​(ProxyOperationContext operationContext,
                                              CompareRequest compareRequest)
                                       throws LDAPException
        Applies any necessary transformation to the provided compare request.
        Parameters:
        operationContext - Information about the operation being processed in the Directory Proxy Server.
        compareRequest - The compare request to be transformed.
        Returns:
        A new compare request which has been transformed as necessary, or the original request if no transformation is required or the provided compare request has been updated in place.
        Throws:
        LDAPException - If a problem is encountered while processing the transformation, or if the provided request should not be forwarded to a backend server.

      • transformCompareResult

        public LDAPResult transformCompareResult​(ProxyOperationContext operationContext,
                                         ReadOnlyCompareRequest compareRequest,
                                         LDAPResult compareResult)
        Applies any necessary transformation to the provided compare result.
        Parameters:
        operationContext - Information about the operation being processed in the Directory Proxy Server.
        compareRequest - The compare request that was processed.
        compareResult - The compare result to be transformed.
        Returns:
        A new compare result which has been transformed as necessary, or the original result if no transformation is required or the provided compare result has been updated in place.

      • transformDeleteRequest

        public DeleteRequest transformDeleteRequest​(ProxyOperationContext operationContext,
                                            DeleteRequest deleteRequest)
                                     throws LDAPException
        Applies any necessary transformation to the provided delete request.
        Parameters:
        operationContext - Information about the operation being processed in the Directory Proxy Server.
        deleteRequest - The delete request to be transformed.
        Returns:
        A new delete request which has been transformed as necessary, or the original request if no transformation is required or the provided delete request has been updated in place.
        Throws:
        LDAPException - If a problem is encountered while processing the transformation, or if the provided request should not be forwarded to a backend server.

      • transformDeleteResult

        public LDAPResult transformDeleteResult​(ProxyOperationContext operationContext,
                                        ReadOnlyDeleteRequest deleteRequest,
                                        LDAPResult deleteResult)
        Applies any necessary transformation to the provided delete result.
        Parameters:
        operationContext - Information about the operation being processed in the Directory Proxy Server.
        deleteRequest - The delete request that was processed.
        deleteResult - The delete result to be transformed.
        Returns:
        A new delete result which has been transformed as necessary, or the original result if no transformation is required or the provided delete result has been updated in place.

      • transformModifyRequest

        public ModifyRequest transformModifyRequest​(ProxyOperationContext operationContext,
                                            ModifyRequest modifyRequest)
                                     throws LDAPException
        Applies any necessary transformation to the provided modify request.
        Parameters:
        operationContext - Information about the operation being processed in the Directory Proxy Server.
        modifyRequest - The modify request to be transformed.
        Returns:
        A new modify request which has been transformed as necessary, or the original request if no transformation is required or the provided modify request has been updated in place.
        Throws:
        LDAPException - If a problem is encountered while processing the transformation, or if the provided request should not be forwarded to a backend server.

      • transformModifyResult

        public LDAPResult transformModifyResult​(ProxyOperationContext operationContext,
                                        ReadOnlyModifyRequest modifyRequest,
                                        LDAPResult modifyResult)
        Applies any necessary transformation to the provided modify result.
        Parameters:
        operationContext - Information about the operation being processed in the Directory Proxy Server.
        modifyRequest - The modify request that was processed.
        modifyResult - The modify result to be transformed.
        Returns:
        A new modify result which has been transformed as necessary, or the original result if no transformation is required or the provided modify result has been updated in place.

      • transformModifyDNRequest

        public ModifyDNRequest transformModifyDNRequest​(ProxyOperationContext operationContext,
                                                ModifyDNRequest modifyDNRequest)
                                         throws LDAPException
        Applies any necessary transformation to the provided modify DN request.
        Parameters:
        operationContext - Information about the operation being processed in the Directory Proxy Server.
        modifyDNRequest - The modify DN request to be transformed.
        Returns:
        A new modify DN request which has been transformed as necessary, or the original request if no transformation is required or the provided modify DN request has been updated in place.
        Throws:
        LDAPException - If a problem is encountered while processing the transformation, or if the provided request should not be forwarded to a backend server.

      • transformModifyDNResult

        public LDAPResult transformModifyDNResult​(ProxyOperationContext operationContext,
                                          ReadOnlyModifyDNRequest modifyDNRequest,
                                          LDAPResult modifyDNResult)
        Applies any necessary transformation to the provided modify DN result.
        Parameters:
        operationContext - Information about the operation being processed in the Directory Proxy Server.
        modifyDNRequest - The modify DN request that was processed.
        modifyDNResult - The modify DN result to be transformed.
        Returns:
        A new modify DN result which has been transformed as necessary, or the original result if no transformation is required or the provided modify DN result has been updated in place.

      • transformSearchRequest

        public SearchRequest transformSearchRequest​(ProxyOperationContext operationContext,
                                            SearchRequest searchRequest)
                                     throws LDAPException
        Applies any necessary transformation to the provided search request.
        Parameters:
        operationContext - Information about the operation being processed in the Directory Proxy Server.
        searchRequest - The search request to be transformed.
        Returns:
        A new search request which has been transformed as necessary, or the original request if no transformation is required or the provided search request has been updated in place.
        Throws:
        LDAPException - If a problem is encountered while processing the transformation, or if the provided request should not be forwarded to a backend server.

      • transformSearchResult

        public SearchResult transformSearchResult​(ProxyOperationContext operationContext,
                                          ReadOnlySearchRequest searchRequest,
                                          SearchResult searchResult,
                                          SearchResultProvider resultProvider)
        Applies any necessary transformation to the provided search result.
        Parameters:
        operationContext - Information about the operation being processed in the Directory Proxy Server.
        searchRequest - The search request that was processed.
        searchResult - The search result to be transformed.
        resultProvider - The search result provider which may be used to send additional search result entries and/or references to the client.
        Returns:
        A new search result which has been transformed as necessary, or the original result if no transformation is required or the provided search result has been updated in place.

      • transformSearchResultEntry

        public SearchResultEntry transformSearchResultEntry​(ProxyOperationContext operationContext,
                                                    ReadOnlySearchRequest searchRequest,
                                                    SearchResultEntry searchEntry)
        Applies any necessary transformation to the provided search result entry.
        Parameters:
        operationContext - Information about the operation being processed in the Directory Proxy Server.
        searchRequest - The search request that is being processed.
        searchEntry - The search result entry to be transformed.
        Returns:
        A new search result entry which has been transformed as necessary, the original search result entry if no transformation is required, or null if the entry should not be returned to the client.

      • transformSearchResultReference

        public SearchResultReference transformSearchResultReference​(ProxyOperationContext operationContext,
                                                            ReadOnlySearchRequest searchRequest,
                                                            SearchResultReference searchReference)
        Applies any necessary transformation to the provided search result reference.
        Parameters:
        operationContext - Information about the operation being processed in the Directory Proxy Server.
        searchRequest - The search request that is being processed.
        searchReference - The search result reference to be transformed.
        Returns:
        A new search result reference which has been transformed as necessary, the original search result reference if no transformation is required, or null if the reference should not be returned to the client.

      • toString

        public final java.lang.String toString()
        Retrieves a string representation of this proxy transformation.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A string representation of this proxy transformation.

      • toString

        public abstract void toString​(java.lang.StringBuilder buffer)
        Appends a string representation of this proxy transformation to the provided buffer.
        Parameters:
        buffer - The buffer to which the string representation should be appended.

      • getExamplesArgumentSets

        public java.util.Map<java.util.List<java.lang.String>,​java.lang.String> getExamplesArgumentSets()
        Retrieves a map containing examples of configurations that may be used for this extension. The map key should be a list of sample arguments, and the corresponding value should be a description of the behavior that will be exhibited by the extension when used with that configuration.
        Specified by:
        getExamplesArgumentSets in interface ExampleUsageProvider
        Returns:
        A map containing examples of configurations that may be used for this extension. It may be null or empty if there should not be any example argument sets.