Task (org.openidentityplatform.commons.parent 2.2.3 Documentation)

java.lang.Object
- com.persistit.Task

All Implemented Interfaces:

Runnable

Direct Known Subclasses:

BackupTask, IntegrityCheck, StatisticsTask, StreamLoader, StreamSaver, TaskCheck
```
public abstract class Task
extends Object
implements Runnable
```
Abstract superclass of classes that perform long-running utility operations, such as export, import and integrity check. Concrete classes should frequently call the poll() method to allow users to stop, suspend or view progress and should post all progress messages to the message log by calling postMessage(String, int).

Version:

1.0

Field Summary

Fields
Modifier and Type	Field and Description
`protected int`	`_culledMessageCount` Number of messages removed from the message log.
`protected String`	`_description` Description of this task
`protected long`	`_expirationTime` System time at which Task should terminate if not finished
`protected long`	`_finishTime` System time when finished
`protected Exception`	`_lastException` Most recently thrown Exception
`protected int`	`_maxMessageLogSize` Maximum number of messages to hold in the message log before automaticlly culling.
`protected ArrayList<String>`	`_messageLog` Collection of messages posted by the task.
`protected int`	`_messageLogVerbosity` Degree of verbosity
`protected PrintWriter`	`_messageWriter` An optional PrintWriter - if not null, `postMessage(String, int)` writes messages to it.
`protected String`	`_owner` Identifies the initiator or owne of this task
`protected Persistit`	`_persistit` The Persistit instance this Task runs against.
`protected long`	`_startTime` System time when started
`protected int`	`_state` State of the task.
`protected AtomicBoolean`	`_stop` By default, the `stop()` method sets this flag, and the `poll()` method throws a `TaskEndedException` to stop a running task.
`protected AtomicBoolean`	`_suspend` When set, the `poll()` method waits.
`protected long`	`_suspendedDuration` Total time during which this Task was suspended
`protected long`	`_taskId` Task ID for this task
`protected Thread`	`_thread` The Thread created to run this task.
`static int`	`DEFAULT_MAX_MESSAGE_LOG_SIZE` Default maximum number of messages held in the message log
`static int`	`LOG_NORMAL` Indicates normal level of message logging
`static int`	`LOG_VERBOSE` Indicates a more verbose level of message logging.
`static int`	`STATE_DONE` Status value indicates this `Task` finished normally.
`static int`	`STATE_ENDED` Status value indicates this `Task` was stopped by user intervention.
`static int`	`STATE_EXPIRED` Status value indicates this `Task`'s maximum elapsed time expired.
`static int`	`STATE_FAILED` Status value indicates this `Task` failed with an Exception.
`static String[]`	`STATE_NAMES`
`static int`	`STATE_NOT_STARTED` Status value indicates this `Task` has been set up but not yet started.
`static int`	`STATE_RUNNING` Status value indicates this `Task` is running.
`static int`	`STATE_SUSPENDED` Status value indicates this `Task` is suspended.

Constructor Summary

Constructors
Modifier Constructor and Description

protected Task()

protected Task(Persistit persistit)

Constructors
Modifier	Constructor and Description
`protected`	`Task()`
`protected`	`Task(Persistit persistit)`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`appendMessage(String fragment, int level)` Appends a String to the final message of the log.
`void`	`cullMessages(int to)` Remove all the messages up to, but not including the specified index.
`protected void`	`endMessage(int level)`
`int`	`getMessageLogSize()` Returns the number of messages available in the message log.
`int`	`getMessageLogVerbosity()` Returns the current verbosity level
`String[]`	`getMessages(int from)` Get all the messages, starting from a specified index.
`PrintWriter`	`getMessageWriter()` Returns the current `PrintWriter`, or `null` if there is none.
`long`	`getRemainingTime()` Indicates how much time remains (in milliseconds) until this `Task`'s maximum time has expired.
`abstract String`	`getStatus()` Returns a short String message describing the current state of this `Task`.
`String`	`getStatusDetail()` Returns a String message describing the current state of this `Task`, possibly in greater detail than `getStatus()`.
`boolean`	`isImmediate()`
`protected long`	`now()` Abbreviation for `System.currentTimeMillis()`.
`protected Tree[]`	`parseTreeList(String specification)` Parses a String that represents a list of Volume/Tree pairs.
`protected void`	`poll()` Tests whether this `Task` should stop or suspend.
`void`	`populateTaskStatus(Management.TaskStatus ts, boolean details, boolean clearMessages)` Copy status of this `Task` to a `Management.TaskStatus`.
`protected void`	`postMessage(String message, int level)` Posts a message (typically to denote progress, error or other interim information) to the message log.
`void`	`resume()` Request this task to resume.
`void`	`run()` Implementation of `Runnable`.
`protected abstract void`	`runTask()` Called by a newly created `Thread` to perform the task.
`void`	`setMaximumTime(long maxTime)` Set the maximum amount of wall-clock time this `Task` will be permitted to run.
`void`	`setMessageLogVerbosity(int verbosity)` Set verbosity level for selecting posted messages.
`void`	`setMessageWriter(PrintWriter pw)` Sets a `PrintWriter` to receive posted messages.
`void`	`setPersistit(Persistit persistit)` Set the Persistit instance to be accessed by this Task.
`void`	`setup(long taskId, String description, String owner, long maxTime, int verbosity)` Sets up a `Task`.
`void`	`start()` Start this Task
`void`	`stop()` Request this task to stop.
`void`	`suspend()` Request this task to suspend.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - STATE_NOT_STARTED
```
public static final int STATE_NOT_STARTED
```
    Status value indicates this Task has been set up but not yet started.
    
    See Also:
    
    Constant Field Values
  - STATE_RUNNING
```
public static final int STATE_RUNNING
```
    Status value indicates this Task is running.
    
    See Also:
    
    Constant Field Values
  - STATE_SUSPENDED
```
public static final int STATE_SUSPENDED
```
    Status value indicates this Task is suspended.
    
    See Also:
    
    Constant Field Values
  - STATE_DONE
```
public static final int STATE_DONE
```
    Status value indicates this Task finished normally.
    
    See Also:
    
    Constant Field Values
  - STATE_FAILED
```
public static final int STATE_FAILED
```
    Status value indicates this Task failed with an Exception.
    
    See Also:
    
    Constant Field Values
  - STATE_ENDED
```
public static final int STATE_ENDED
```
    Status value indicates this Task was stopped by user intervention.
    
    See Also:
    
    Constant Field Values
  - STATE_EXPIRED
```
public static final int STATE_EXPIRED
```
    Status value indicates this Task's maximum elapsed time expired.
    
    See Also:
    
    Constant Field Values
  - STATE_NAMES
```
public static final String[] STATE_NAMES
```
  - LOG_NORMAL
```
public static final int LOG_NORMAL
```
    Indicates normal level of message logging
    
    See Also:
    
    Constant Field Values
  - LOG_VERBOSE
```
public static final int LOG_VERBOSE
```
    Indicates a more verbose level of message logging.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_MAX_MESSAGE_LOG_SIZE
```
public static final int DEFAULT_MAX_MESSAGE_LOG_SIZE
```
    Default maximum number of messages held in the message log
    
    See Also:
    
    Constant Field Values
  - _persistit
```
protected Persistit _persistit
```
    The Persistit instance this Task runs against.
  - _taskId
```
protected long _taskId
```
    Task ID for this task
  - _description
```
protected String _description
```
    Description of this task
  - _owner
```
protected String _owner
```
    Identifies the initiator or owne of this task
  - _startTime
```
protected long _startTime
```
    System time when started
  - _finishTime
```
protected long _finishTime
```
    System time when finished
  - _expirationTime
```
protected long _expirationTime
```
    System time at which Task should terminate if not finished
  - _suspendedDuration
```
protected long _suspendedDuration
```
    Total time during which this Task was suspended
  - _stop
```
protected AtomicBoolean _stop
```
    By default, the stop() method sets this flag, and the poll() method throws a TaskEndedException to stop a running task.
  - _suspend
```
protected AtomicBoolean _suspend
```
    When set, the poll() method waits.
  - _lastException
```
protected Exception _lastException
```
    Most recently thrown Exception
  - _state
```
protected int _state
```
    State of the task.
  - _maxMessageLogSize
```
protected int _maxMessageLogSize
```
    Maximum number of messages to hold in the message log before automaticlly culling.
  - _culledMessageCount
```
protected int _culledMessageCount
```
    Number of messages removed from the message log.
  - _messageLogVerbosity
```
protected int _messageLogVerbosity
```
    Degree of verbosity
  - _messageLog
```
protected final ArrayList<String> _messageLog
```
    Collection of messages posted by the task. Note we are using JDK1.1 ArrayList to help port to J2ME.
  - _messageWriter
```
protected PrintWriter _messageWriter
```
    An optional PrintWriter - if not null, postMessage(String, int) writes messages to it.
  - _thread
```
protected Thread _thread
```
    The Thread created to run this task.
- Constructor Detail
  - Task
```
protected Task()
```
  - Task
```
protected Task(Persistit persistit)
```
- Method Detail
  - setPersistit
```
public void setPersistit(Persistit persistit)
```
    Set the Persistit instance to be accessed by this Task.
    
    Parameters:
    
    persistit -
  - runTask
```
protected abstract void runTask()
                         throws Exception
```
    Called by a newly created Thread to perform the task.
    
    Throws:
    
    Exception
  - poll
```
protected void poll()
```
    Tests whether this Task should stop or suspend. The concrete task implementation should call poll frequently. The default mechanism for stopping a task does not use the deprecated Thread.stop() method because it is unsafe. Instead, the task should call poll().
  - parseTreeList
```
protected Tree[] parseTreeList(String specification)
                        throws PersistitException
```
    Parses a String that represents a list of Volume/Tree pairs. Format: volumeName1,treeName1,treeName2;volumeName2,treeName1,treeName2,..
    
    Parameters:
    
    specification - The list of Volume/Tree pairs, specified as a String
    
    Returns:
    
    Array of Trees specified by the list.
    
    Throws:
    
    PersistitException
  - now
```
protected long now()
```
    Abbreviation for System.currentTimeMillis().
    
    Returns:
    
    Current system time
  - setup
```
public void setup(long taskId,
                  String description,
                  String owner,
                  long maxTime,
                  int verbosity)
           throws Exception
```
    Sets up a Task.
    
    Parameters:
    
    taskId - unique identifier for this task invocation
    
    description - Description of this task
    
    owner - Hostname and/or username
    
    maxTime - Maximum wall-clock duration, in milliseconds, that Task will be allowed to run
    
    verbosity - Level at which messages posted by the running task will be retained in the message log.
    
    Throws:
    
    Exception
  - start
```
public void start()
```
    Start this Task
    
    Throws:
    
    IllegalStateException - If this task has already been started
  - stop
```
public void stop()
```
    Request this task to stop. Note: a subclass could reimplement this using _thread.stop() if necessary.
  - suspend
```
public void suspend()
```
    Request this task to suspend. Note: a subclass could reimplement this using _thread.suspend() if necessary.
  - resume
```
public void resume()
```
    Request this task to resume. Note: a subclass could reimplement this using _thread.resume() if necessary.
  - setMaximumTime
```
public void setMaximumTime(long maxTime)
```
    Set the maximum amount of wall-clock time this Task will be permitted to run. If the Task is suspended, the amount of time spend in the suspended state is not counted toward this maximum.
    
    Parameters:
    
    maxTime - The time, in milliseconds
  - setMessageLogVerbosity
```
public void setMessageLogVerbosity(int verbosity)
```
    Set verbosity level for selecting posted messages. Current available values are LOG_NORMAL and LOG_VERBOSE.
    
    Parameters:
    
    verbosity - Verbosity
  - getMessageLogVerbosity
```
public int getMessageLogVerbosity()
```
    Returns the current verbosity level
    
    Returns:
    
    Current verbosity
  - setMessageWriter
```
public void setMessageWriter(PrintWriter pw)
```
    Sets a PrintWriter to receive posted messages.
    
    Parameters:
    
    pw - The PrintWriter
  - getMessageWriter
```
public PrintWriter getMessageWriter()
```
    Returns the current PrintWriter, or null if there is none.
    
    Returns:
    
    Current PrintWriter
  - getStatus
```
public abstract String getStatus()
```
    Returns a short String message describing the current state of this Task. It should convey a measurement of progress to the end-user.
    
    Returns:
    
    A description of this Task's current state
  - getStatusDetail
```
public String getStatusDetail()
```
    Returns a String message describing the current state of this Task, possibly in greater detail than getStatus(). The default implementation returns the same description as getStatus.
    
    Returns:
    
    A detailed description of this Task's current state.
  - getRemainingTime
```
public long getRemainingTime()
```
    Indicates how much time remains (in milliseconds) until this Task's maximum time has expired.
  - postMessage
```
protected void postMessage(String message,
                           int level)
```
    Posts a message (typically to denote progress, error or other interim information) to the message log.
    
    Parameters:
    
    message - The message
    
    level - Indicates the verbosity level. The message is posted only if the level of the message is below the current verbosity threshhold set through setMessageLogVerbosity(int).
  - endMessage
```
protected void endMessage(int level)
```
  - appendMessage
```
protected void appendMessage(String fragment,
                             int level)
```
    Appends a String to the final message of the log.
    
    Parameters:
    
    fragment - The message fragment to append
    
    level - Indicates the verbosity level. The message is posted only if the level of the message is below the current verbosity threshold set through setMessageLogVerbosity(int).
  - getMessageLogSize
```
public int getMessageLogSize()
```
    Returns the number of messages available in the message log.
    
    Returns:
    
    Number of messages
  - getMessages
```
public String[] getMessages(int from)
```
    Get all the messages, starting from a specified index.
    
    Parameters:
    
    from - The index
    
    Returns:
    
    The messages
  - cullMessages
```
public void cullMessages(int to)
```
    Remove all the messages up to, but not including the specified index.
    
    Parameters:
    
    to - Index of first message not to remove.
  - run
```
public void run()
```
    Implementation of Runnable.
    
    Specified by:
    
    run in interface Runnable
  - populateTaskStatus
```
public void populateTaskStatus(Management.TaskStatus ts,
                               boolean details,
                               boolean clearMessages)
```
    Copy status of this Task to a Management.TaskStatus.
    
    Parameters:
    
    ts - The TaskStatus
    
    details - true to include messages and status detail
    
    clearMessages - true to cull the messages being returned
  - isImmediate
```
public boolean isImmediate()
```

Class Task

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

STATE_NOT_STARTED

STATE_RUNNING

STATE_SUSPENDED

STATE_DONE

STATE_FAILED

STATE_ENDED

STATE_EXPIRED

STATE_NAMES

LOG_NORMAL

LOG_VERBOSE

DEFAULT_MAX_MESSAGE_LOG_SIZE

_persistit

_taskId

_description

_owner

_startTime

_finishTime

_expirationTime

_suspendedDuration

_stop

_suspend

_lastException

_state

_maxMessageLogSize

_culledMessageCount

_messageLogVerbosity

_messageLog

_messageWriter

_thread

Constructor Detail

Task

Task

Method Detail

setPersistit

runTask

poll

parseTreeList

now

setup

start

stop

suspend

resume

setMaximumTime

setMessageLogVerbosity

getMessageLogVerbosity

setMessageWriter

getMessageWriter

getStatus

getStatusDetail

getRemainingTime

postMessage

endMessage

appendMessage

getMessageLogSize

getMessages

cullMessages

run

populateTaskStatus

isImmediate