Package com.unboundid.directory.sdk.ds.api

Class 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

      Constructors 
      Constructor Description
      Task()
      Creates a new instance of this task.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      void defineConfigArguments​(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, 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

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

      • initializeTask

        public void initializeTask​(DirectoryServerContext serverContext,
                           ArgumentParser parser)
                    throws 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:
        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.