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 * Copyright 2010-2012 UnboundID Corp.
026 */
027 package com.unboundid.directory.sdk.ds.scripting;
028
029
030
031 import com.unboundid.directory.sdk.common.internal.Configurable;
032 import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
033 import com.unboundid.directory.sdk.ds.types.DirectoryServerContext;
034 import com.unboundid.directory.sdk.ds.types.TaskContext;
035 import com.unboundid.directory.sdk.ds.types.TaskReturnState;
036 import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension;
037 import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension;
038 import com.unboundid.ldap.sdk.LDAPException;
039 import com.unboundid.util.Extensible;
040 import com.unboundid.util.ThreadSafety;
041 import com.unboundid.util.ThreadSafetyLevel;
042 import com.unboundid.util.args.ArgumentException;
043 import 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)
090 public 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 }