Task.java revision a23343e9e4e0b555b1bcfa99a7455e0e28117a3d
0N/A * The contents of this file are subject to the terms of the 0N/A * Common Development and Distribution License, Version 1.0 only 0N/A * (the "License"). You may not use this file except in compliance 0N/A * See the License for the specific language governing permissions 0N/A * and limitations under the License. 0N/A * When distributing Covered Code, include this CDDL HEADER in each 0N/A * If applicable, add the following below this CDDL HEADER, with the 0N/A * fields enclosed by brackets "[]" replaced with your own identifying 1472N/A * Portions Copyright [yyyy] [name of copyright owner] 0N/A * Copyright 2006-2009 Sun Microsystems, Inc. 0N/A * Portions Copyright 2014-2015 ForgeRock AS 0N/A * This class defines a task that may be executed by the task backend within the 0N/A /** The DN for the task entry. */ 0N/A /** The entry that actually defines this task. */ 0N/A * The action to take if one of the dependencies for this task does not 0N/A * complete successfully. 0N/A /** The counter used for log messages associated with this task. */ 0N/A /** The task IDs of other tasks on which this task is dependent. */ 0N/A * A set of log messages generated by this task. 0N/A * TODO: convert from String to LocalizableMessage objects. 0N/A * Since these are stored in an entry we would need 0N/A * to adopt some way for writing message to string in such 0N/A * a way that the information could be reparsed from its 0N/A * The set of e-mail addresses of the users to notify when the task is done 0N/A * running, regardless of whether it completes successfully. 0N/A * The set of e-mail addresses of the users to notify if the task does not 0N/A * complete successfully for some reason. 0N/A /** The time that processing actually started for this task. */ 0N/A /** The time that actual processing ended for this task. */ /** The time that this task was scheduled to start processing. */ /** The operation used to create this task in the server. */ /** The ID of the recurring task with which this task is associated. */ /** The unique ID assigned to this task. */ /** The task backend with which this task is associated. */ /** The current state of this task. */ /** The task state that may be set when the task is interrupted. */ /** The scheduler with which this task is associated. */ * Returns the server context. * @return the server context. * Gets a message that identifies this type of task suitable for * presentation to humans in monitoring tools. // NOTE: this method is invoked via reflection. If you rename // it be sure to modify the calls. * Given an attribute type name returns and locale sensitive * @param name of an attribute type associated with the object * class that represents this entry in the directory * @return LocalizableMessage display name // Subclasses that are schedulable from the task interface should override this // NOTE: this method is invoked via reflection. If you rename // it be sure to modify the calls. * Performs generic initialization for this task based on the information in * the provided task entry. * @param taskScheduler The scheduler with which this task is associated. * @param taskEntry The entry containing the task configuration. * @throws InitializationException If a problem occurs while performing the // Get the task ID and recurring task ID values. At least one of them must // be provided. If it's a recurring task and there is no task ID, then // generate one on the fly. // Get the current state from the task. If there is none, then assume it's // Get the scheduled start time for the task, if there is one. It may be // in either UTC time (a date followed by a 'Z') or in the local time zone // (not followed by a 'Z'). // Get the actual start time for the task, if there is one. // Get the completion time for the task, if there is one. // Get information about any dependencies that the task might have. // Get the information about the e-mail addresses to use for notification // Get the log messages for the task. * Retrieves the single value for the requested attribute as a string. * @param attributeName The name of the attribute for which to retrieve the * @param isRequired Indicates whether the attribute is required to have * @return The value for the requested attribute, or <CODE>null</CODE> if it * is not present in the entry and is not required. * @throws InitializationException If the requested attribute is not present * in the entry but is required, or if there * are multiple instances of the requested * attribute in the entry with different * sets of options, or if there are multiple * values for the requested attribute. * Retrieves the values for the requested attribute as a list of strings. * @param attributeName The name of the attribute for which to retrieve the * @return The list of values for the requested attribute, or an empty list * if the attribute does not exist or does not have any values. * @throws InitializationException If there are multiple instances of the * requested attribute in the entry with * different sets of options. * Retrieves the DN of the entry containing the definition for this task. * @return The DN of the entry containing the definition for this task. * Retrieves the entry containing the definition for this task. * @return The entry containing the definition for this task. * Retrieves the operation used to create this task in the server. Note that * this will only be available when the task is first added to the scheduler, * and it should only be accessed from within the {@code initializeTask} * method (and even that method should not depend on it always being * available, since it will not be available if the server is restarted and * the task needs to be reinitialized). * @return The operation used to create this task in the server, or * {@code null} if it is not available. * Specifies the operation used to create this task in the server. * @param operation The operation used to create this task in the server. * Retrieves the unique identifier assigned to this task. * @return The unique identifier assigned to this task. * Retrieves the unique identifier assigned to the recurring task that is * associated with this task, if there is one. * @return The unique identifier assigned to the recurring task that is * associated with this task, or <CODE>null</CODE> if it is not * associated with any recurring task. * Retrieves the current state for this task. * @return The current state for this task. * Indicates whether or not this task is an iteration of * @return boolean where true indicates that this task is * recurring, false otherwise. * Indicates whether or not this task has been cancelled. * @return boolean where true indicates that this task was * cancelled either before or during execution * Sets the state for this task and updates the associated task entry as * necessary. It does not automatically persist the updated task information * @param taskState The new state to use for the task. // We only need to grab the entry-level lock if we don't already hold the // broader scheduler lock. * Sets a state for this task that is the result of a call to * {@link #interruptTask(TaskState, LocalizableMessage)}. * It may take this task some time to actually cancel to that * actual state may differ until quiescence. * @param state for this task once it has canceled whatever it is doing * Gets the interrupt state for this task that was set as a * result of a call to {@link #interruptTask(TaskState, LocalizableMessage)}. * @return interrupt state for this task * Returns a state for this task after processing has completed. * If the task was interrupted with a call to * {@link #interruptTask(TaskState, LocalizableMessage)} * then that method's interruptState is returned here. Otherwise * this method returns TaskState.COMPLETED_SUCCESSFULLY. It is * assumed that if there were errors during task processing that * task state will have been derived in some other way. * @return state for this task after processing has completed * Replaces an attribute values of the task entry. * @param name The name of the attribute that must be replaced. * @param value The value that must replace the previous values of the * @throws DirectoryException When an error occurs. // We only need to grab the entry-level lock if we don't already hold the // broader scheduler lock. * Retrieves the scheduled start time for this task, if there is one. The * value returned will be in the same format as the return value for * <CODE>System.currentTimeMillis()</CODE>. Any value representing a time in * the past, or any negative value, should be taken to mean that the task * should be considered eligible for immediate execution. * @return The scheduled start time for this task. * Retrieves the time that this task actually started running, if it has * started. The value returned will be in the same format as the return value * for <CODE>System.currentTimeMillis()</CODE>. * @return The time that this task actually started running, or -1 if it has * Sets the actual start time for this task and updates the associated task * entry as necessary. It does not automatically persist the updated task * @param actualStartTime The actual start time to use for this task. // We only need to grab the entry-level lock if we don't already hold the // broader scheduler lock. * Retrieves the time that this task completed all of its associated * processing (regardless of whether it was successful), if it has completed. * The value returned will be in the same format as the return value for * <CODE>System.currentTimeMillis()</CODE>. * @return The time that this task actually completed running, or -1 if it * Sets the completion time for this task and updates the associated task * entry as necessary. It does not automatically persist the updated task * @param completionTime The completion time to use for this task. // We only need to grab the entry-level lock if we don't already hold the // broader scheduler lock. * Retrieves the set of task IDs for any tasks on which this task is * dependent. This list must not be directly modified by the caller. * @return The set of task IDs for any tasks on which this task is dependent. * Retrieves the action that should be taken if any of the dependencies for * this task do not complete successfully. * @return The action that should be taken if any of the dependencies for * this task do not complete successfully. * Retrieves the set of e-mail addresses for the users that should receive a * notification message when processing for this task has completed. This * notification will be sent to these users regardless of whether the task * completed successfully. This list must not be directly modified by the * @return The set of e-mail addresses for the users that should receive a * notification message when processing for this task has * Retrieves the set of e-mail addresses for the users that should receive a * notification message if processing for this task does not complete * successfully. This list must not be directly modified by the caller. * @return The set of e-mail addresses for the users that should receive a * notification message if processing for this task does not complete * Retrieves the set of messages that were logged by this task. This list * must not be directly modified by the caller. * @return The set of messages that were logged by this task. // TODO: a better job or recreating the message * Adds a log message to the set of messages logged by this task. This method * should not be called directly by tasks, but rather will be called * indirectly through the {@code ErrorLog.logError} methods. It does not * automatically persist the updated task information to disk. * the severity of message. * Adds a log message to the set of messages logged by this task. This method * should not be called directly by tasks, but rather will be called * indirectly through the {@code ErrorLog.logError} methods. It does not * automatically persist the updated task information to disk. * the severity of message. * the exception to log. May be {@code null}. // We cannot do task logging if the schema is either destroyed or // not initialized eg during in-core restart from Restart task. // Bailing out if there is no schema available saves us from NPE. // We only need to grab the entry-level lock if we don't already hold the // broader scheduler lock. * Compares this task with the provided task for the purposes of ordering in a * sorted list. Any completed task will always be ordered before an * uncompleted task. If both tasks are completed, then they will be ordered * by completion time. If both tasks are uncompleted, then a running task * will always be ordered before one that has not started. If both are * running, then they will be ordered by actual start time. If neither have * started, then they will be ordered by scheduled start time. If all else * fails, they will be ordered lexicographically by task ID. * @param task The task to compare with this task. * @return A negative value if the provided task should come before this * task, a positive value if the provided task should come after this * task, or zero if there is no difference with regard to their // They have both completed, so order by completion time. // They have the same completion time, so order by task ID. // Completed tasks are always ordered before those that haven't // Completed tasks are always ordered before those that haven't completed. // They are both running, so order by actual start time. // They have the same actual start time, so order by task ID. // Running tasks are always ordered before those that haven't started. // Running tasks are always ordered before those that haven't started. // Neither task has started, so order by scheduled start time, or if nothing * Begins execution for this task. This is a wrapper around the * <CODE>runTask</CODE> method that performs the appropriate set-up and * tear-down. It should only be invoked by a task thread. * @return The final state to use for the task. * If appropriate, send an e-mail message with information about the * @throws MessagingException If a problem occurs while attempting to send * Performs any task-specific initialization that may be required before * processing can start. This default implementation does not do anything, * but subclasses may override it as necessary. This method will be called at * the time the task is scheduled, and therefore any failure in this method * will be returned to the client. * @throws DirectoryException If a problem occurs during initialization that * should be returned to the client. // No action is performed by default. * Performs the actual core processing for this task. This method should not * return until all processing associated with this task has completed. * @return The final state to use for the task. * Performs any necessary processing to prematurely interrupt the execution of * this task. By default no action is performed, but if it is feasible to * gracefully interrupt a task, then subclasses should override this method to * Implementations of this method are exprected to call * {@link #setTaskInterruptState(TaskState)} if the interruption is accepted * @param interruptState The state to use for the task if it is * successfully interrupted. * @param interruptReason A human-readable explanation for the cancellation. // No action is performed by default. // NOTE: if you implement this make sure to override isInterruptable * Indicates whether or not this task is interruptable or not. * @return boolean where true indicates that this task can be interrupted.