001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at
010 * docs/licenses/cddl.txt
011 * or http://www.opensource.org/licenses/cddl1.php.
012 * See the License for the specific language governing permissions
013 * and limitations under the License.
014 *
015 * When distributing Covered Code, include this CDDL HEADER in each
016 * file and include the License file at
017 * docs/licenses/cddl.txt.  If applicable,
018 * add the following below this CDDL HEADER, with the fields enclosed
019 * by brackets "[]" replaced with your own identifying information:
020 *      Portions Copyright [yyyy] [name of copyright owner]
021 *
022 * CDDL HEADER END
023 *
024 *
025 *      Portions Copyright 2010-2024 Ping Identity Corporation
026 */
027package com.unboundid.directory.sdk.ds.scripting;
028
029
030
031import com.unboundid.directory.sdk.common.internal.Configurable;
032import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
033import com.unboundid.directory.sdk.ds.types.DirectoryServerContext;
034import com.unboundid.directory.sdk.ds.types.TaskContext;
035import com.unboundid.directory.sdk.ds.types.TaskReturnState;
036import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension;
037import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension;
038import com.unboundid.ldap.sdk.LDAPException;
039import com.unboundid.util.Extensible;
040import com.unboundid.util.ThreadSafety;
041import com.unboundid.util.ThreadSafetyLevel;
042import com.unboundid.util.args.ArgumentException;
043import com.unboundid.util.args.ArgumentParser;
044
045
046
047/**
048 * This class defines an API that must be implemented by scripted extensions
049 * which may be used as administrative tasks.  Administrative tasks have the
050 * ability to perform arbitrary processing within the server whenever a
051 * particular kind of entry is added, and that processing can be performed
052 * immediately or at some specified time in the future.  Tasks may be scheduled
053 * by adding an entry below "cn=Scheduled Tasks,cn=tasks" with a format like
054 * the following:
055 * <PRE>
056 *   dn:  ds-task-id=TASKID,cn=Scheduled Tasks,cn=tasks
057 *   objectClass: top
058 *   objectClass: ds-task
059 *   objectClass: ds-groovy-scripted-task
060 *   ds-task-id: TASKID
061 *   ds-task-class-name: com.unboundid.directory.sdk.extensions.GroovyScrip
062 *    tedTask
063 *   ds-scripted-task-class: com.example.ExampleGroovyTask
064 *   ds-scripted-task-argument: name=value
065 * </PRE>
066 * In this example, TASKID should be replaced with a string that uniquely
067 * identifies the task.  The value of the ds-scripted-task-class attribute
068 * should contain the fully-qualified name of the non-abstract Groovy class that
069 * extends this com.unboundid.directory.sdk.scripting.ScriptedTask class, and
070 * the ds-scripted-task-argument values (if any) should reflect the set of
071 * arguments to be provided for the task.
072 * method.
073 * <BR><BR>
074 * Alternately, the com.unboundid.ldap.sdk.unboundidds.tasks.GroovyScriptedTask
075 * class included in the Commercial Edition of the UnboundID LDAP SDK for Java
076 * may be used to schedule and interact with these kinds of tasks.  See the
077 * documentation for the Commercial Edition of the LDAP SDK for more
078 * information on using the UnboundID LDAP SDK for Java to schedule and interact
079 * with administrative tasks.
080 *
081 * @see  com.unboundid.directory.sdk.ds.api.Task
082 */
083@Extensible()
084@DirectoryServerExtension()
085@DirectoryProxyServerExtension(appliesToLocalContent=true,
086     appliesToRemoteContent=false)
087@SynchronizationServerExtension(appliesToLocalContent=true,
088     appliesToSynchronizedContent=false)
089@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
090public abstract class ScriptedTask
091       implements Configurable
092{
093  /**
094   * Creates a new instance of this task.  All task implementations must include
095   * a default constructor, but any initialization should generally be done in
096   * the {@code initializeTask} method.
097   */
098  public ScriptedTask()
099  {
100    // No implementation is required.
101  }
102
103
104
105  /**
106   * {@inheritDoc}
107   */
108  public void defineConfigArguments(final ArgumentParser parser)
109         throws ArgumentException
110  {
111    // No arguments will be allowed by default.
112  }
113
114
115
116  /**
117   * Initializes this task.
118   *
119   * @param  serverContext  A handle to the server context for the server in
120   *                        which this extension is running.
121   * @param  parser         The argument parser which has been initialized from
122   *                        the configuration for this task.
123   *
124   * @throws  LDAPException  If a problem occurs while initializing this task.
125   */
126  public void initializeTask(final DirectoryServerContext serverContext,
127                             final ArgumentParser parser)
128         throws LDAPException
129  {
130    // No initialization will be performed by default.
131  }
132
133
134
135  /**
136   * Performs the appropriate processing for this task.
137   *
138   * @param  taskContext  Information about the task to be run.
139   *
140   * @return  Information about the state of the task after processing has
141   *          completed.
142   */
143  public abstract TaskReturnState runTask(final TaskContext taskContext);
144}