com.unboundid.directory.sdk.broker.api

Class PolicyObligation

java.lang.Object

com.unboundid.directory.sdk.broker.api.PolicyObligation

All Implemented Interfaces:

Configurable, ExampleUsageProvider, UnboundIDExtension

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

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

Configuring Policy Obligation

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

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

where "{name}" is the name to use for the policy obligation instance, "{class-name}" is the fully-qualified name of the Java class that extends com.unboundid.directory.sdk.broker.api.PolicyObligation, "{policy-name}" and {rule-name}" identify the policy and policy rule, respectively, that will contain this obligation expression. {name=jexlExpression} pairs specified using obligation-arguments identify arguments whose value may be specified or computed during policy evaluation before being passed into this obligation implementation. "{index}" is an integer from 1 to 9999 that is used to determine the order in which this type of obligation should be invoked relative to other obligations that may be returned from the same policy evaluation. "{name=value}" pairs specified using extension-arguments are constant-valued arguments that are provided to the obligation implementation at initialization time. If multiple obligation arguments should be provided at each invocation, then the "--set obligation-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
PolicyObligation() 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	finalizePolicyObligation() Performs any cleanup which may be necessary when this policy obligation 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	initializePolicyObligation(BrokerContext serverContext, PolicyObligationConfig config, com.unboundid.util.args.ArgumentParser parser) Initializes this Policy Obligation implementation.
com.unboundid.scim2.common.GenericScimResource	onScimCreate(ObligationContext context, com.unboundid.scim2.common.GenericScimResource resource) This method is invoked if this obligation is returned from policy during a SCIM create operation.
void	onScimDelete(ObligationContext context) This method is invoked if this obligation is returned from policy during a SCIM delete operation.
com.unboundid.scim2.common.messages.PatchRequest	onScimModify(ObligationContext context, com.unboundid.scim2.common.messages.PatchRequest patchRequest) This method is invoked if this obligation is returned from policy during a SCIM PATCH or PUT operation.
com.unboundid.scim2.common.GenericScimResource	onScimRetrieve(ObligationContext context, com.unboundid.scim2.common.GenericScimResource resource) This method is invoked if this obligation is returned from policy during a SCIM retrieve operation.
java.lang.String	onScimSearch(ObligationContext context, java.lang.String filter) This method is invoked if this obligation is returned from policy prior to a SCIM search operation.

Methods inherited from class java.lang.Object

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

Constructor Detail

PolicyObligation

public PolicyObligation()

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.

initializePolicyObligation

public void initializePolicyObligation(BrokerContext serverContext,
                                       PolicyObligationConfig config,
                                       com.unboundid.util.args.ArgumentParser parser)
                                throws java.lang.Exception

Initializes this Policy Obligation implementation.

Parameters:

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

config - The general configuration for this policy obligation.

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

Throws:

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

finalizePolicyObligation

public void finalizePolicyObligation()

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

onScimCreate

public com.unboundid.scim2.common.GenericScimResource onScimCreate(ObligationContext context,
                                                                   com.unboundid.scim2.common.GenericScimResource resource)
                                                            throws NotFulfilledException,
                                                                   com.unboundid.scim2.common.exceptions.ScimException

This method is invoked if this obligation is returned from policy during a SCIM create operation. The method is invoked before the new resource has been saved to the data store.

Parameters:

context - ObligationContext containing any arguments passed from policy.

resource - The resource to be created.

Returns:

The (possibly modified) resource to be created.

Throws:

NotFulfilledException - thrown if the obligation cannot be fulfilled. Will abort the SCIM create operation and will cause an unauthorized response to be returned to the caller.

com.unboundid.scim2.common.exceptions.ScimException - thrown if an internal error occurs.

onScimDelete

public void onScimDelete(ObligationContext context)
                  throws NotFulfilledException,
                         com.unboundid.scim2.common.exceptions.ScimException

This method is invoked if this obligation is returned from policy during a SCIM delete operation. The method is invoked before the deletion is committed to the data store.

Parameters:

context - ObligationContext containing any arguments passed from policy.

Throws:

NotFulfilledException - thrown if the obligation cannot be fulfilled. Will abort the SCIM delete operation and will cause an unauthorized response to be returned to the caller.

com.unboundid.scim2.common.exceptions.ScimException - thrown if an internal error occurs.

onScimModify

public com.unboundid.scim2.common.messages.PatchRequest onScimModify(ObligationContext context,
                                                                     com.unboundid.scim2.common.messages.PatchRequest patchRequest)
                                                              throws NotFulfilledException,
                                                                     com.unboundid.scim2.common.exceptions.ScimException

This method is invoked if this obligation is returned from policy during a SCIM PATCH or PUT operation. The method is invoked before the modified resource has been saved to the data store.

Parameters:

context - ObligationContext containing any arguments passed from policy.

patchRequest - A normalized SCIM patch request describing the requested modifications. A "normalized" patch request in this context means that the patch will have the following characteristics: For add and remove operations, sub-attributes will always appear in the value portion rather than in the path. Paths referencing core attributes will not contain the schema URN. Operations without a path will be broken down into separate operations for each attribute originally referenced in the value portion.

Returns:

The (possibly modified) patch request.

Throws:

NotFulfilledException - thrown if the obligation cannot be fulfilled. Will abort the SCIM modify operation and will cause an unauthorized response to be returned to the caller.

com.unboundid.scim2.common.exceptions.ScimException - thrown if an internal error occurs.

onScimRetrieve

public com.unboundid.scim2.common.GenericScimResource onScimRetrieve(ObligationContext context,
                                                                     com.unboundid.scim2.common.GenericScimResource resource)
                                                              throws NotFulfilledException,
                                                                     com.unboundid.scim2.common.exceptions.ScimException

This method is invoked if this obligation is returned from policy during a SCIM retrieve operation. The method is invoked before the resource is added to the SCIM response.

Parameters:

context - ObligationContext containing any arguments passed from policy.

resource - The resource to be returned to the client.

Returns:

The (possibly modified) resource to be returned.

Throws:

NotFulfilledException - thrown if the obligation cannot be fulfilled. Will abort the SCIM retrieve operation and will cause an unauthorized response to be returned to the caller.

com.unboundid.scim2.common.exceptions.ScimException - thrown if an internal error occurs.

onScimSearch

public java.lang.String onScimSearch(ObligationContext context,
                                     java.lang.String filter)
                              throws NotFulfilledException,
                                     com.unboundid.scim2.common.exceptions.ScimException

This method is invoked if this obligation is returned from policy prior to a SCIM search operation. The method is invoked before the search is executed.

Parameters:

context - ObligationContext containing any arguments passed from policy.

filter - The SCIM search filter requested by the client, or null if no filter was specified.

Returns:

The (possibly modified) SCIM search filter.

Throws:

NotFulfilledException - thrown if the obligation cannot be fulfilled. Will abort the SCIM search operation and will cause an unauthorized response to be returned to the caller.

com.unboundid.scim2.common.exceptions.ScimException - thrown if an internal error occurs.