com.unboundid.directory.sdk.broker.api

Class Advice

java.lang.Object

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

Constructors

Constructor and Description
Advice() No-args constructor.

Method Summary

Modifier and Type	Method and Description
abstract HttpRequestResponse	apply(PolicyRequestDetails requestDetails, java.util.List<? extends AdviceStatement> statements, HttpRequestResponse requestResponse) This method is invoked when the specified Advice type is returned by policy evaluation.
void	defineConfigArguments(ArgumentParser parser) Updates the provided argument parser to define any configuration arguments which may be used by this extension.
void	finalizeAdvice() Performs any cleanup which may be necessary when this advice 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	initializeAdvice(BrokerContext serverContext, AdviceConfig config, ArgumentParser parser) Initializes this Advice implementation.

Methods inherited from class java.lang.Object

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

Constructor Detail

Advice

public Advice()

No-args constructor.

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.

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.