com.unboundid.directory.sdk.broker.api

Class PolicyAdvice

java.lang.Object

com.unboundid.directory.sdk.broker.api.PolicyAdvice

All Implemented Interfaces:

Configurable, ExampleUsageProvider, UnboundIDExtension

@Extensible
 @BrokerExtension
 @ThreadSafety(level=INTERFACE_THREADSAFE)
public abstract class PolicyAdvice
extends java.lang.Object
implements UnboundIDExtension, ExampleUsageProvider

This class defines an API that must be implemented by extensions that implement custom Policy Advice. This advice is invoked when policy evaluation results in this type of advice being returned to the Policy Enforcement Point.

Configuring Policy Advice

In order to configure policy advice created using this API, use a command like:

      dsconfig create-policy-advice \
           --advice-name "{name}" \
           --type third-party \
           --policy-name "{policy-name}" \
           --rule-name "{rule-name}" \
           --set "extension-class:{class-name}" \
           --set "extension-argument:{name=value}" \
           --set "advice-arguments:{name=jexlExpression}" \
           --set "evaluation-order-index:{index}
 

where "{name}" is the name to use for the policy advice instance, "{class-name}" is the fully-qualified name of the Java class that extends com.unboundid.directory.sdk.broker.api.PolicyAdvice, "{policy-name}" and {rule-name}" identify the policy and policy rule, respectively, that will contain this advice expression. {name=jexlExpression} pairs specified using advice-arguments identify arguments whose value may be specified or computed during policy evaluation before being passed into this advice implementation. "{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 advice arguments should be provided at each invocation, then the "--set advice-argument:{name=jexlExpression}" option should be provided multiple times. 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
PolicyAdvice() No-args constructor.

Method Summary

Modifier and Type	Method and Description
void	defineConfigArguments(com.unboundid.util.args.ArgumentParser parser) Updates the provided argument parser to define any configuration arguments which may be used by this extension.
void	finalizePolicyAdvice() Performs any cleanup which may be necessary when this policy 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	initializePolicyAdvice(BrokerContext serverContext, PolicyAdviceConfig adviceCfg, com.unboundid.util.args.ArgumentParser parser) Initializes this Policy Advice implementation.
com.unboundid.scim2.common.messages.ErrorResponse	onScimDeny(AdviceContext context, com.unboundid.scim2.common.messages.ErrorResponse errorInfo) This method is called if this advice is returned by policy when a SCIM request is denied.

Methods inherited from class java.lang.Object

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

Constructor Detail

PolicyAdvice

public PolicyAdvice()

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(com.unboundid.util.args.ArgumentParser parser)
                           throws com.unboundid.util.args.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:

com.unboundid.util.args.ArgumentException - If a problem is encountered while updating the provided argument parser.

initializePolicyAdvice

public void initializePolicyAdvice(BrokerContext serverContext,
                                   PolicyAdviceConfig adviceCfg,
                                   com.unboundid.util.args.ArgumentParser parser)
                            throws java.lang.Exception

Initializes this Policy Advice implementation.

Parameters:

serverContext - A handle to the server context for the server in which this extension is running.

adviceCfg - The general configuration for this policy advice.

parser - The argument parser which has been initialized from the configuration for this policy advice.

Throws:

java.lang.Exception - If a problem occurs while initializing this policy advice.

finalizePolicyAdvice

public void finalizePolicyAdvice()

Performs any cleanup which may be necessary when this policy advice is to be taken out of service.

onScimDeny

public com.unboundid.scim2.common.messages.ErrorResponse onScimDeny(AdviceContext context,
                                                                    com.unboundid.scim2.common.messages.ErrorResponse errorInfo)
                                                             throws com.unboundid.scim2.common.exceptions.ScimException

This method is called if this advice is returned by policy when a SCIM request is denied.

Parameters:

context - AdviceContext containing any arguments passed from policy.

errorInfo - the default error information that will be returned if nothing is done by the advice implementation.

Returns:

the modified error info

Throws:

com.unboundid.scim2.common.exceptions.ScimException - if an internal error occurs trying to generate the advice.