com.unboundid.directory.sdk.proxy.api

Class ProxyTransformation

java.lang.Object

com.unboundid.directory.sdk.proxy.api.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 Summary

Constructors

Constructor and Description
ProxyTransformation() Creates a new instance of this proxy transformation.

Method Summary

Modifier and Type	Method and Description
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.
void	defineConfigArguments(ArgumentParser parser) Updates the provided argument parser to define any configuration arguments which may be used by this extension.
void	finalizeProxyTransformation() Performs any cleanup which may be necessary when this proxy transformation is to be taken out of service.
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.
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.
void	initializeProxyTransformation(ProxyServerContext serverContext, ProxyTransformationConfig config, ArgumentParser parser) Initializes this proxy transformation.
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.
java.lang.String	toString() Retrieves a string representation of this proxy transformation.
abstract void	toString(java.lang.StringBuilder buffer) Appends a string representation of this proxy transformation to the provided buffer.
AddRequest	transformAddRequest(ProxyOperationContext operationContext, AddRequest addRequest) Applies any necessary transformation to the provided add request.
LDAPResult	transformAddResult(ProxyOperationContext operationContext, ReadOnlyAddRequest addRequest, LDAPResult addResult) Applies any necessary transformation to the provided add result.
BindRequest	transformBindRequest(ProxyOperationContext operationContext, BindRequest bindRequest) Applies any necessary transformation to the provided bind request.
BindResult	transformBindResult(ProxyOperationContext operationContext, BindRequest bindRequest, BindResult bindResult) Applies any necessary transformation to the provided bind request.
CompareRequest	transformCompareRequest(ProxyOperationContext operationContext, CompareRequest compareRequest) Applies any necessary transformation to the provided compare request.
LDAPResult	transformCompareResult(ProxyOperationContext operationContext, ReadOnlyCompareRequest compareRequest, LDAPResult compareResult) Applies any necessary transformation to the provided compare result.
DeleteRequest	transformDeleteRequest(ProxyOperationContext operationContext, DeleteRequest deleteRequest) Applies any necessary transformation to the provided delete request.
LDAPResult	transformDeleteResult(ProxyOperationContext operationContext, ReadOnlyDeleteRequest deleteRequest, LDAPResult deleteResult) Applies any necessary transformation to the provided delete result.
ModifyDNRequest	transformModifyDNRequest(ProxyOperationContext operationContext, ModifyDNRequest modifyDNRequest) Applies any necessary transformation to the provided modify DN request.
LDAPResult	transformModifyDNResult(ProxyOperationContext operationContext, ReadOnlyModifyDNRequest modifyDNRequest, LDAPResult modifyDNResult) Applies any necessary transformation to the provided modify DN result.
ModifyRequest	transformModifyRequest(ProxyOperationContext operationContext, ModifyRequest modifyRequest) Applies any necessary transformation to the provided modify request.
LDAPResult	transformModifyResult(ProxyOperationContext operationContext, ReadOnlyModifyRequest modifyRequest, LDAPResult modifyResult) Applies any necessary transformation to the provided modify result.
SearchRequest	transformSearchRequest(ProxyOperationContext operationContext, SearchRequest searchRequest) Applies any necessary transformation to the provided search request.
SearchResult	transformSearchResult(ProxyOperationContext operationContext, ReadOnlySearchRequest searchRequest, SearchResult searchResult, SearchResultProvider resultProvider) Applies any necessary transformation to the provided search result.
SearchResultEntry	transformSearchResultEntry(ProxyOperationContext operationContext, ReadOnlySearchRequest searchRequest, SearchResultEntry searchEntry) Applies any necessary transformation to the provided search result entry.
SearchResultReference	transformSearchResultReference(ProxyOperationContext operationContext, ReadOnlySearchRequest searchRequest, SearchResultReference searchReference) Applies any necessary transformation to the provided search result reference.

Methods inherited from class java.lang.Object

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

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

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.

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.