Package com.unboundid.directory.sdk.broker.api

Class Advice

  • All Implemented Interfaces:
    Configurable, ExampleUsageProvider, UnboundIDExtension
    @Extensible
@BrokerExtension
@ThreadSafety(level=INTERFACE_THREADSAFE)
public abstract class Advice
extends java.lang.Object
implements UnboundIDExtension, ExampleUsageProvider
    This class defines an API that must be implemented by extensions that implement custom Advice for policies. This advice is invoked when policy evaluation results in this type of advice being returned to the Policy Enforcement Point.

    Configuring Advice

    In order to configure policy advice created using this API, use a command like: 
          dsconfig create-advice \
           --advice-name "{name}" \
           --type third-party \
           --set "advice-id:{advice-code}
           --set "extension-class:{class-name}" \
           --set "extension-argument:{name=value}" \
           --set "evaluation-order-index:{index}
    where "{name}" is a user-friendly name to use for the advice type, "{advice-code}" is a unique advice code that must match the "code" string returned from a policy invocation, and "{class-name}" is the fully-qualified name of the Java class that extends com.unboundid.directory.sdk.broker.api.Advice. "{index}" is an integer from 1 to 9999 that is used to determine the order in which this type of advice should be invoked relative to other advice that may be returned from the same policy evaluation. "{name=value}" pairs specified using extension-arguments are values that are provided to the advice implementation at initialization time. If multiple initialization arguments should be provided to the extension, then the "--set extension-argument:{name=value}" option should be provided multiple times.

    • Constructor Detail

      • Advice

        public Advice()
        No-args constructor.

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

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

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

      • initializeAdvice

        public void initializeAdvice​(BrokerContext serverContext,
                             AdviceConfig config,
                             ArgumentParser parser)
                      throws java.lang.Exception
        Initializes this Advice implementation.
        Parameters:
        serverContext - A handle to the server context for the server in which this extension is running.
        config - The general configuration for this Advice.
        parser - The argument parser which has been initialized from the configuration for this Advice.
        Throws:
        java.lang.Exception - If a problem occurs while initializing this Advice.

      • finalizeAdvice

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

      • apply

        public abstract HttpRequestResponse apply​(PolicyRequestDetails requestDetails,
                                          java.util.List<? extends AdviceStatement> statements,
                                          HttpRequestResponse requestResponse)
                                   throws NotFulfilledException
        This method is invoked when the specified Advice type is returned by policy evaluation.
        Parameters:
        requestDetails - Details of the authorization request that triggered the advice.
        statements - List of advice instances with payload and attributes containing advice details.
        requestResponse - HTTP Request or Response that may be examined or manipulated by the advice implementation. The resource details are dependent upon the API method that requested authorization and the type of request being authorized. As an example, for a create operation the request body may represent the resource the client is attempting to create, while for a retrieve operation the response body may represent the resource to be returned to the client.
        Returns:
        the (possibly modified) request or response.
        Throws:
        NotFulfilledException - if the advice cannot be successfully applied. If the advice is defined to be obligatory, throwing this exception will cause the requested operation to fail. If the advice is not obligatory, throwing this exception will cause an error to be logged, however the requested operation will not otherwise be impacted.