com.unboundid.directory.sdk.ds.api
Class Task

java.lang.Object
  com.unboundid.directory.sdk.ds.api.Task

All Implemented Interfaces:

Configurable, ExampleUsageProvider, UnboundIDExtension

@Extensible
@DirectoryServerExtension
@DirectoryProxyServerExtension(appliesToLocalContent=true,
                               appliesToRemoteContent=false)
@SynchronizationServerExtension(appliesToLocalContent=true,
                                appliesToSynchronizedContent=false)
@ThreadSafety(level=INTERFACE_THREADSAFE)
public abstract class Task
extends java.lang.Object
implements UnboundIDExtension, ExampleUsageProvider

This class defines an API that must be implemented by extensions which may be used as administrative tasks. Administrative tasks have the ability to perform arbitrary processing within the server whenever a particular kind of entry is added, and that processing can be performed immediately or at some specified time in the future. The server must be configured as follows to allow creation of third-party tasks:

   dsconfig set-global-configuration-prop
     --add allowed-task:com.unboundid.directory.sdk.extensions.ThirdPartyTask
 

Tasks may then be scheduled by adding an entry below "cn=Scheduled Tasks,cn=tasks" with a format like the following:

   dn:  ds-task-id=TASKID,cn=Scheduled Tasks,cn=tasks
   objectClass: top
   objectClass: ds-task
   objectClass: ds-third-party-task
   ds-task-id: TASKID
   ds-task-class-name: com.unboundid.directory.sdk.extensions.ThirdPartyTask
   ds-third-party-task-java-class: com.example.ExampleTask
   ds-third-party-task-argument: name=value
 

In this example, TASKID should be replaced with a string that uniquely identifies the task. The value of the ds-third-party-task-java-class attribute should contain the fully-qualified name of the non-abstract Java class that extends this com.unboundid.directory.sdk.api.Task class, and the ds-third-party-task-argument values (if any) should reflect the set of arguments allowed for the task as per the defineConfigArguments(com.unboundid.util.args.ArgumentParser) method.

Alternately, the com.unboundid.ldap.sdk.unboundidds.tasks.ThirdPartyTask class included in the Commercial Edition of the UnboundID LDAP SDK for Java may be used to schedule and interact with these kinds of tasks. See the documentation for the Commercial Edition of the LDAP SDK for more information on using the UnboundID LDAP SDK for Java to schedule and interact with administrative tasks.

See Also:

ScriptedTask

Constructor Summary

Task()
Creates a new instance of this task.

Method Summary

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.
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.
abstract java.lang.String	getTaskName() Retrieves a human-readable name that may be used for this task.
void	initializeTask(DirectoryServerContext serverContext, com.unboundid.util.args.ArgumentParser parser) Initializes this task.
void	interruptTask(TaskReturnState interruptState, java.lang.String interruptReason) Attempts to interrupt the execution of this task.
boolean	isInterruptible() Indicates whether this task may be interrupted before it has completed (e.g., canceled by an administrator or aborted at server shutdown).
abstract TaskReturnState	runTask(TaskContext taskContext) Performs the appropriate processing for this task.

Methods inherited from class java.lang.Object

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

Constructor Detail

Task

public Task()

Creates a new instance of this task. All task implementations must include a default constructor, but any initialization should generally be done in the initializeTask 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(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.

initializeTask

public void initializeTask(DirectoryServerContext serverContext,
                           com.unboundid.util.args.ArgumentParser parser)
                    throws com.unboundid.ldap.sdk.LDAPException

Initializes this task.

Parameters:

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

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

Throws:

com.unboundid.ldap.sdk.LDAPException - If a problem occurs while initializing this task.

getTaskName

public abstract java.lang.String getTaskName()

Retrieves a human-readable name that may be used for this task.

Returns:

A human-readable name that may be used for this task.

runTask

public abstract TaskReturnState runTask(TaskContext taskContext)

Performs the appropriate processing for this task.

Parameters:

taskContext - Information about the task to be run.

Returns:

Information about the state of the task after processing has completed.

isInterruptible

public boolean isInterruptible()

Indicates whether this task may be interrupted before it has completed (e.g., canceled by an administrator or aborted at server shutdown). It is particularly important that potentially long-running tasks be interruptible so that they do not impede server shutdown or consume excessive resources.

Returns:

true if this task may be interrupted before it has completed, or false if it cannot be interrupted.

interruptTask

public void interruptTask(TaskReturnState interruptState,
                          java.lang.String interruptReason)

Attempts to interrupt the execution of this task. This should only be called if the isInterruptible() method returns true.

Parameters:

interruptState - The return state that should be used for the task if it is successfully interrupted.

interruptReason - A message that provides a reason that the task has been interrupted.

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.