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