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.api;
028
029
030
031 import java.util.Collections;
032 import java.util.List;
033 import java.util.Map;
034
035 import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider;
036 import com.unboundid.directory.sdk.common.internal.UnboundIDExtension;
037 import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
038 import com.unboundid.directory.sdk.ds.types.DirectoryServerContext;
039 import com.unboundid.directory.sdk.ds.types.TaskContext;
040 import com.unboundid.directory.sdk.ds.types.TaskReturnState;
041 import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension;
042 import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension;
043 import com.unboundid.ldap.sdk.LDAPException;
044 import com.unboundid.util.Extensible;
045 import com.unboundid.util.ThreadSafety;
046 import com.unboundid.util.ThreadSafetyLevel;
047 import com.unboundid.util.args.ArgumentException;
048 import com.unboundid.util.args.ArgumentParser;
049
050
051
052 /**
053 * This class defines an API that must be implemented by extensions which
054 * may be used as administrative tasks. Administrative tasks have the ability
055 * to perform arbitrary processing within the server whenever a particular kind
056 * of entry is added, and that processing can be performed immediately or at
057 * some specified time in the future. Tasks may be scheduled by adding an entry
058 * below "cn=Scheduled Tasks,cn=tasks" with a format like the following:
059 * <PRE>
060 * dn: ds-task-id=TASKID,cn=Scheduled Tasks,cn=tasks
061 * objectClass: top
062 * objectClass: ds-task
063 * objectClass: ds-third-party-task
064 * ds-task-id: TASKID
065 * ds-task-class-name: com.unboundid.directory.sdk.extensions.ThirdPartyTask
066 * ds-third-party-task-java-class: com.example.ExampleTask
067 * ds-third-party-task-argument: name=value
068 * </PRE>
069 * In this example, TASKID should be replaced with a string that uniquely
070 * identifies the task. The value of the ds-third-party-task-java-class
071 * attribute should contain the fully-qualified name of the non-abstract Java
072 * class that extends this com.unboundid.directory.sdk.api.Task class, and the
073 * ds-third-party-task-argument values (if any) should reflect the set of
074 * arguments allowed for the task as per the {@link #defineConfigArguments}
075 * method.
076 * <BR><BR>
077 * Alternately, the com.unboundid.ldap.sdk.unboundidds.tasks.ThirdPartyTask
078 * class included in the Commercial Edition of the UnboundID LDAP SDK for Java
079 * may be used to schedule and interact with these kinds of tasks. See the
080 * documentation for the Commercial Edition of the LDAP SDK for more
081 * information on using the UnboundID LDAP SDK for Java to schedule and interact
082 * with administrative tasks.
083 *
084 * @see com.unboundid.directory.sdk.ds.scripting.ScriptedTask
085 */
086 @Extensible()
087 @DirectoryServerExtension()
088 @DirectoryProxyServerExtension(appliesToLocalContent=true,
089 appliesToRemoteContent=false)
090 @SynchronizationServerExtension(appliesToLocalContent=true,
091 appliesToSynchronizedContent=false)
092 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
093 public abstract class Task
094 implements UnboundIDExtension, ExampleUsageProvider
095 {
096 /**
097 * Creates a new instance of this task. All task implementations must include
098 * a default constructor, but any initialization should generally be done in
099 * the {@code initializeTask} method.
100 */
101 public Task()
102 {
103 // No implementation is required.
104 }
105
106
107
108 /**
109 * {@inheritDoc}
110 */
111 public abstract String getExtensionName();
112
113
114
115 /**
116 * {@inheritDoc}
117 */
118 public abstract String[] getExtensionDescription();
119
120
121
122 /**
123 * {@inheritDoc}
124 */
125 public void defineConfigArguments(final ArgumentParser parser)
126 throws ArgumentException
127 {
128 // No arguments will be allowed by default.
129 }
130
131
132
133 /**
134 * Initializes this task.
135 *
136 * @param serverContext A handle to the server context for the server in
137 * which this task is running.
138 * @param parser The argument parser which has been initialized from
139 * the configuration for this task.
140 *
141 * @throws LDAPException If a problem occurs while initializing this task.
142 */
143 public void initializeTask(final DirectoryServerContext serverContext,
144 final ArgumentParser parser)
145 throws LDAPException
146 {
147 // No initialization will be performed by default.
148 }
149
150
151
152 /**
153 * Retrieves a human-readable name that may be used for this task.
154 *
155 * @return A human-readable name that may be used for this task.
156 */
157 public abstract String getTaskName();
158
159
160
161 /**
162 * Performs the appropriate processing for this task.
163 *
164 * @param taskContext Information about the task to be run.
165 *
166 * @return Information about the state of the task after processing has
167 * completed.
168 */
169 public abstract TaskReturnState runTask(final TaskContext taskContext);
170
171
172
173 /**
174 * Indicates whether this task may be interrupted before it has completed
175 * (e.g., canceled by an administrator or aborted at server shutdown). It is
176 * particularly important that potentially long-running tasks be interruptible
177 * so that they do not impede server shutdown or consume excessive resources.
178 *
179 * @return {@code true} if this task may be interrupted before it has
180 * completed, or {@code false} if it cannot be interrupted.
181 */
182 public boolean isInterruptible()
183 {
184 return false;
185 }
186
187
188
189 /**
190 * Attempts to interrupt the execution of this task. This should only be
191 * called if the {@link #isInterruptible} method returns {@code true}.
192 *
193 * @param interruptState The return state that should be used for the task
194 * if it is successfully interrupted.
195 * @param interruptReason A message that provides a reason that the task has
196 * been interrupted.
197 */
198 public void interruptTask(final TaskReturnState interruptState,
199 final String interruptReason)
200 {
201 // No action is performed by default.
202 }
203
204
205
206 /**
207 * {@inheritDoc}
208 */
209 public Map<List<String>,String> getExamplesArgumentSets()
210 {
211 return Collections.emptyMap();
212 }
213 }