BackgroundTask (Commons)

java.lang.Object
- com.lf.commons.task.BackgroundTask

All Implemented Interfaces:

ConfigurableUnit
```
public class BackgroundTask
extends java.lang.Object
implements ConfigurableUnit
```
Simple data holding class for tasks executed by the background task manager (not cron!).
Background tasks are special runnable objects executed by separate threads to allow the user to do some work in the background (e.g. searching files, generating digests etc.). In order to fully support also CLI applications rather than GUI applications it is necessary for task runnables to run silently without creating any dialogs. Implementations should always check out the GraphicsEnvironment.isHeadless() method before any dialogs are shown.

Since:

1.6

Version:

$Revision: 1.31 $, $Date: 2012/12/28 11:44:25 $

Author:

Axel Schwolow

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`MESSAGE_TYPE_ERR` Represents a message for `System.err`.
`static java.lang.String`	`MESSAGE_TYPE_OUT` Represents a message for `System.out`.
`static int`	`STATUS_CANCELLED` Status for the task, cancelled by user.
`static int`	`STATUS_ERROR` Status for the task, finished with errors.
`static int`	`STATUS_INACTIVE` Status for the task, not started yet.
`static int`	`STATUS_INFO` Status for the task, finished with success but with notices.
`static int`	`STATUS_INTERRUPTED` Status for the task, interrupted programmatically (e.g. to prevent OutOfMemoryError).
`static int`	`STATUS_OK` Status for the task, finished with success.
`static int`	`STATUS_RUNNING` Status for the task, currently running.
`static int`	`STATUS_TIMEOUT` Status for the task, cancelled by timeout.
`static int`	`STATUS_WARNING` Status for the task, finished with warnings.
`protected java.util.Vector<TaskListener>`	`taskListeners` Container holding the external task listeners.

Constructor Summary

Constructors
Constructor and Description
`BackgroundTask()` Constructor method for i18n purposes only.
`BackgroundTask(java.lang.Runnable task, java.lang.String title, java.lang.String desc, java.lang.String threadName, int priority, boolean cancelAllowed, boolean exclusive, int exclusiveTimeout, boolean indeterminate, javax.swing.Icon icon, boolean autoClose, boolean canRestart, boolean keepFinished, boolean autoBackground, java.lang.String helpID, boolean logmessages)` Constructor settings the initial values.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addTaskListener(TaskListener listener)` Adds a listener reacting on task completions.
`static float`	`calculateProgress(long min, long max, long value)` Convenience method to calculate the progress as percentile (0%-100%).
`boolean`	`canRestart()` Can the task be restarted by the task manager?
`void`	`configureUnit(java.lang.String id, Configuration config)` Restores values from persistent data stores.
`boolean`	`equals(BackgroundTask tocheck)` Checks wether a given `BackgroundTask` instance is equal to this.
`protected void`	`finalize()` Clean-up method to help the gc.
`java.lang.String`	`getDescription()` Getter for description.
`java.util.Date`	`getEndDate()` Getter for time the task finished.
`int`	`getExclusiveTimeout()` Getter for the exclusive mode timeout.
`java.lang.String`	`getHelpID()` Provides the link to the help system of the application.
`javax.swing.Icon`	`getIcon()` Getter for the icon representing the task.
`java.lang.String`	`getMessage()` Getter for current message.
`java.util.Vector<java.lang.String[]>`	`getMessages()` Getter for logged messages (optional).
`int`	`getPriority()` Getter for priority.
`float`	`getProgress()` Getter for current progress value in the range between 0% and 100%.
`java.util.Date`	`getStartDate()` Getter for start time.
`int`	`getStatus()` Getter for current status.
`java.lang.Runnable`	`getTask()` Getter for task.
`TaskDialog`	`getTaskDialog()` Provides the reference for the task dialog (not set when executed from command line).
`TaskListener[]`	`getTaskListeners()` Provides the optional listeners reacting on task completions.
`java.lang.String`	`getThreadName()` Getter for thread name.
`java.lang.String`	`getTitle()` Getter for dialog title.
`boolean`	`hasFinished()` Has this task being finished?
`boolean`	`isAutoBackground()` Getter for auto-backgrounding feature used by the task dialog.
`boolean`	`isAutoClose()` Getter for auto-close feature used by the task dialog.
`boolean`	`isCancelAllowed()` Getter for cancel capability.
`boolean`	`isExclusive()` Getter for exclusive mode.
`boolean`	`isIndeterminate()` Getter for indeterminate mode.
`boolean`	`isInterrupted()` Getter for current interruption state.
`boolean`	`isKeepFinished()` Keep the task within the task manager when finished?
`boolean`	`isUnitRegistered()` Is the instance currently being configured?
`void`	`removeTaskListener(TaskListener listener)` Removes a listener reacting on task completions.
`void`	`resetProgress()` Setter for current progress to the initial start value 0
`void`	`setAutoBackground(boolean enabled)` Setter for auto-backgrounding feature used by the task dialog.
`void`	`setAutoClose(boolean enabled)` Setter for auto-close feature used by the task dialog.
`void`	`setEndDate(java.util.Date endDate)` Setter for time the task finished.
`void`	`setInterrupted(boolean interrupted)` Setter for current interruption state.
`void`	`setKeepFinished(boolean keepfinished)` Setter for current keep finished state.
`void`	`setMessage(java.lang.String message)` Setter for current message.
`void`	`setMessage(java.lang.String message, java.lang.String type)` Setter for current message.
`void`	`setMessages(java.util.Vector<java.lang.String[]> messages)` Overrides the internally used message container with shared instance.
`void`	`setProgress(float progress)` Setter for current progress value in the range between 0% and 100%.
`void`	`setProgress(long min, long max, long value)` Convenience method to set the progress by calculating the percentile.
`void`	`setStartDate(java.util.Date startDate)` Setter for start time.
`void`	`setStatus(int status)` Setter for current status.
`void`	`setStatusAndMessage(int status, java.lang.String message)` Convenience method to set both message and status.
`void`	`setTaskDialog(TaskDialog dialog)` Sets the reference for the task dialog (not set when executed from command line).
`void`	`storeUnit(java.lang.String id, Configuration config)` Stores the current configuration values persistently.
`java.lang.String`	`toString()` Overrides method `java.lang.Object.toString`.
`void`	`unitRegistered(ApplicationModel model, java.lang.String id)` Informs the configurable unit that it was registered with a model.
`void`	`unitUnregistered(ApplicationModel model, java.lang.String id)` Informs the configurable unit that it was unregistered with a model.
`void`	`unregisterUnit()` Is the instance currently being configured?

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

- Field Detail
  - STATUS_INACTIVE
```
public static final int STATUS_INACTIVE
```
    Status for the task, not started yet.
    
    See Also:
    Constant Field Values
  - STATUS_RUNNING
```
public static final int STATUS_RUNNING
```
    Status for the task, currently running.
    
    See Also:
    Constant Field Values
  - STATUS_OK
```
public static final int STATUS_OK
```
    Status for the task, finished with success.
    
    See Also:
    Constant Field Values
  - STATUS_INFO
```
public static final int STATUS_INFO
```
    Status for the task, finished with success but with notices.
    
    See Also:
    Constant Field Values
  - STATUS_WARNING
```
public static final int STATUS_WARNING
```
    Status for the task, finished with warnings.
    
    See Also:
    Constant Field Values
  - STATUS_ERROR
```
public static final int STATUS_ERROR
```
    Status for the task, finished with errors.
    
    See Also:
    Constant Field Values
  - STATUS_CANCELLED
```
public static final int STATUS_CANCELLED
```
    Status for the task, cancelled by user.
    
    See Also:
    Constant Field Values
  - STATUS_TIMEOUT
```
public static final int STATUS_TIMEOUT
```
    Status for the task, cancelled by timeout.
    
    See Also:
    Constant Field Values
  - STATUS_INTERRUPTED
```
public static final int STATUS_INTERRUPTED
```
    Status for the task, interrupted programmatically (e.g. to prevent OutOfMemoryError).
    
    See Also:
    Constant Field Values
  - MESSAGE_TYPE_OUT
```
public static final java.lang.String MESSAGE_TYPE_OUT
```
    Represents a message for System.out.
    
    See Also:
    Constant Field Values
  - MESSAGE_TYPE_ERR
```
public static final java.lang.String MESSAGE_TYPE_ERR
```
    Represents a message for System.err.
    
    See Also:
    Constant Field Values
  - taskListeners
```
protected java.util.Vector<TaskListener> taskListeners
```
    Container holding the external task listeners.
- Constructor Detail
  - BackgroundTask
```
public BackgroundTask()
               throws java.lang.InstantiationException
```
    Constructor method for i18n purposes only.
    Can only be used if beans design time is set (e.g. by external tools like the I18NExtractor).
    
    Throws:
    
    java.lang.InstantiationException - Error indication
    Since:
    
    1.6
  - BackgroundTask
```
public BackgroundTask(java.lang.Runnable task,
              java.lang.String title,
              java.lang.String desc,
              java.lang.String threadName,
              int priority,
              boolean cancelAllowed,
              boolean exclusive,
              int exclusiveTimeout,
              boolean indeterminate,
              javax.swing.Icon icon,
              boolean autoClose,
              boolean canRestart,
              boolean keepFinished,
              boolean autoBackground,
              java.lang.String helpID,
              boolean logmessages)
```
    Constructor settings the initial values.
    
    Parameters:
    task - The task itself (required)
    title - The short title used for the task dialog, may be null
    desc - The more detailed description of the task e.g. used as task dialog subtitle, may be null
    threadName - The desired name of the task thread, may be null
    priority - Thread priority used by the manager to execute the task
    cancelAllowed - May the task be cancelled by the user?
    exclusive - Must the task be executed exclusively (<= 0 deactivates)?
    exclusiveTimeout - Exclusive task times out after a while (seconds)?
    indeterminate - Can the progress value be monitored or not?
    icon - The icon representing the task, may be null
    autoClose - Activate the auto-closing feature?
    canRestart - Can the task be restarted by the task manager?
    keepFinished - Keep the task within the task manager when finished?
    autoBackground - Activate the auto-backgrounding feature?
    helpID - Identifier to call the help system (optional)
    logmessages - Shall messages be logged sequentially (optional)?
    
    Throws:
    
    java.lang.NullPointerException - If the task is null
    
    java.lang.IllegalArgumentException - If at least one of the parameters is invalid
    Since:
    
    1.6
- Method Detail
  - finalize
```
protected void finalize()
                 throws java.lang.Throwable
```
    Clean-up method to help the gc.
    
    Overrides:
    
    finalize in class java.lang.Object
    
    Throws:
    
    java.lang.Throwable - Error indication
    Since:
    
    1.6
  - toString
```
public java.lang.String toString()
```
    Overrides method java.lang.Object.toString.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    The identifer for the represented object or empty string
    Since:
    
    1.6
  - equals
```
public boolean equals(BackgroundTask tocheck)
```
    Checks wether a given BackgroundTask instance is equal to this.
    
    Parameters:
    tocheck - The instance to be compared
    
    Returns:
    The BackgroundTask instance to check for equality
    Since:
    
    1.6
  - getTask
```
public java.lang.Runnable getTask()
```
    Getter for task.
    
    Returns:
    The task
    Since:
    
    1.6
  - getTitle
```
public java.lang.String getTitle()
```
    Getter for dialog title.
    
    Returns:
    The dialog title
    Since:
    
    1.6
  - getDescription
```
public java.lang.String getDescription()
```
    Getter for description.
    
    Returns:
    The description
    Since:
    
    1.6
  - getThreadName
```
public java.lang.String getThreadName()
```
    Getter for thread name.
    
    Returns:
    The thread name
    Since:
    
    1.6
  - getPriority
```
public int getPriority()
```
    Getter for priority.
    
    Returns:
    The priority
    Since:
    
    1.6
  - isCancelAllowed
```
public boolean isCancelAllowed()
```
    Getter for cancel capability.
    
    Returns:
    The cancel capability
    Since:
    
    1.6
  - isExclusive
```
public boolean isExclusive()
```
    Getter for exclusive mode.
    
    Returns:
    The exclusive mode
    Since:
    
    1.6
  - getExclusiveTimeout
```
public int getExclusiveTimeout()
```
    Getter for the exclusive mode timeout.
    
    Returns:
    The exclusive mode timeout
    Since:
    
    1.6
  - isIndeterminate
```
public boolean isIndeterminate()
```
    Getter for indeterminate mode.
    
    Returns:
    The indeterminate mode
    Since:
    
    1.6
  - isAutoClose
```
public boolean isAutoClose()
```
    Getter for auto-close feature used by the task dialog.
    
    Returns:
    The auto-close feature
    Since:
    
    1.6
  - setAutoClose
```
public void setAutoClose(boolean enabled)
```
    Setter for auto-close feature used by the task dialog.
    
    Parameters:
    enabled - The auto-close feature
    Since:
    
    1.6
  - isAutoBackground
```
public boolean isAutoBackground()
```
    Getter for auto-backgrounding feature used by the task dialog.
    
    Returns:
    The auto-backgrounding feature
    Since:
    
    1.6
  - setAutoBackground
```
public void setAutoBackground(boolean enabled)
```
    Setter for auto-backgrounding feature used by the task dialog.
    
    Parameters:
    enabled - The auto-backgrounding feature
    Since:
    
    1.6
  - getStartDate
```
public java.util.Date getStartDate()
```
    Getter for start time.
    
    Returns:
    The start time
    Since:
    
    1.6
  - setStartDate
```
public void setStartDate(java.util.Date startDate)
```
    Setter for start time.
    
    Parameters:
    startDate - The start time
    Since:
    
    1.6
  - getEndDate
```
public java.util.Date getEndDate()
```
    Getter for time the task finished.
    
    Returns:
    The time the task finished
    Since:
    
    1.6
  - setEndDate
```
public void setEndDate(java.util.Date endDate)
```
    Setter for time the task finished.
    
    Parameters:
    endDate - The time the task finished
    Since:
    
    1.6
  - getProgress
```
public float getProgress()
```
    Getter for current progress value in the range between 0% and 100%.
    
    Returns:
    The current progress
    Since:
    
    1.6
  - setProgress
```
public void setProgress(float progress)
```
    Setter for current progress value in the range between 0% and 100%.
    Invalid progress values are not set. Progress can only increase.
    
    Parameters:
    progress - The current progress
    Since:
    
    1.6
  - resetProgress
```
public void resetProgress()
```
    Setter for current progress to the initial start value 0
    
    Since:
    
    1.6
  - setProgress
```
public void setProgress(long min,
               long max,
               long value)
```
    Convenience method to set the progress by calculating the percentile.
    The background task progress is left untouched if the percentile could not be calculated due to an invalid range or value.
    
    Parameters:
    min - Minimum value
    max - Maximum value
    value - The current value
    
    Throws:
    
    java.lang.IllegalArgumentException - If parameters are invalid (e.g. max < min)
    Since:
    
    1.6
  - calculateProgress
```
public static float calculateProgress(long min,
                      long max,
                      long value)
```
    Convenience method to calculate the progress as percentile (0%-100%).
    
    Parameters:
    min - Minimum value
    max - Maximum value
    value - The current value
    
    Returns:
    The progress percentile
    
    Throws:
    
    java.lang.IllegalArgumentException - If parameters are invalid (e.g. max < min)
    Since:
    
    1.6
  - getMessage
```
public java.lang.String getMessage()
```
    Getter for current message.
    
    Returns:
    The current message, may be null
    Since:
    
    1.6
  - getMessages
```
public java.util.Vector<java.lang.String[]> getMessages()
```
    Getter for logged messages (optional).
    Message logging needs to be activated explicitely with the constructor's logmessages parameter.
    
    Returns:
    The current message log, null if not available
    Since:
    
    1.6
  - setMessages
```
public void setMessages(java.util.Vector<java.lang.String[]> messages)
```
    Overrides the internally used message container with shared instance.
    
    Parameters:
    messages - The message cache
    
    Throws:
    
    java.lang.NullPointerException - If a parameter is null
    Since:
    
    1.6
  - setMessage
```
public void setMessage(java.lang.String message)
```
    Setter for current message.
    Remember that the given message is printed directly without any linefeeds added!
    
    Parameters:
    message - The current message, may be null
    Since:
    
    1.6
  - setMessage
```
public void setMessage(java.lang.String message,
              java.lang.String type)
```
    Setter for current message.
    Remember that the given message is printed directly without any linefeeds added!
    
    Parameters:
    message - The current message, may be null
    type - The message type (optional), defaults to MESSAGE_TYPE_OUT
    Since:
    
    1.6
  - setStatusAndMessage
```
public void setStatusAndMessage(int status,
                       java.lang.String message)
```
    Convenience method to set both message and status.
    Remember that the given message is printed directly without any linefeeds added!
    
    Parameters:
    status - The status
    message - The final message
    Since:
    
    1.6
  - getStatus
```
public int getStatus()
```
    Getter for current status.
    
    Returns:
    The current status
    Since:
    
    1.6
  - setStatus
```
public void setStatus(int status)
```
    Setter for current status.
    
    Parameters:
    status - The current status of the task
    
    Throws:
    
    java.lang.IllegalArgumentException - If the status is invalid
    Since:
    
    1.6
  - getIcon
```
public javax.swing.Icon getIcon()
```
    Getter for the icon representing the task.
    
    Returns:
    Icon representing the task
    Since:
    
    1.6
  - canRestart
```
public boolean canRestart()
```
    Can the task be restarted by the task manager?
    
    Returns:
    Restart supported?
    Since:
    
    1.6
  - isKeepFinished
```
public boolean isKeepFinished()
```
    Keep the task within the task manager when finished?
    
    Returns:
    Keep task?
    Since:
    
    1.6
  - setKeepFinished
```
public void setKeepFinished(boolean keepfinished)
```
    Setter for current keep finished state.
    
    Parameters:
    keepfinished - The current keep finished state
    Since:
    
    1.6
  - isInterrupted
```
public boolean isInterrupted()
```
    Getter for current interruption state.
    
    Returns:
    The current interruption state
    Since:
    
    1.6
  - setInterrupted
```
public void setInterrupted(boolean interrupted)
```
    Setter for current interruption state.
    
    Parameters:
    interrupted - The current interruption state
    Since:
    
    1.6
  - configureUnit
```
public void configureUnit(java.lang.String id,
                 Configuration config)
```
    Restores values from persistent data stores.
    
    Specified by:
    
    configureUnit in interface ConfigurableUnit
    
    Parameters:
    id - The unique identifier for the instance
    config - The configuration
    Since:
    
    1.6
  - storeUnit
```
public void storeUnit(java.lang.String id,
             Configuration config)
```
    Stores the current configuration values persistently.
    
    Specified by:
    
    storeUnit in interface ConfigurableUnit
    
    Parameters:
    id - The unique identifier for the instance
    config - The configuration
    Since:
    
    1.6
  - unitRegistered
```
public void unitRegistered(ApplicationModel model,
                  java.lang.String id)
```
    Informs the configurable unit that it was registered with a model.
    
    Specified by:
    
    unitRegistered in interface ConfigurableUnit
    
    Parameters:
    model - The application model
    id - The unique identifier for the instance
    Since:
    
    1.6
  - unitUnregistered
```
public void unitUnregistered(ApplicationModel model,
                    java.lang.String id)
```
    Informs the configurable unit that it was unregistered with a model.
    
    Specified by:
    
    unitUnregistered in interface ConfigurableUnit
    
    Parameters:
    model - The application model
    id - The unique identifier for the instance
    Since:
    
    1.6
  - isUnitRegistered
```
public boolean isUnitRegistered()
```
    Is the instance currently being configured?
    
    Returns:
    Configured?
    Since:
    
    1.6
  - unregisterUnit
```
public void unregisterUnit()
```
    Is the instance currently being configured?
    
    Since:
    
    1.6
  - addTaskListener
```
public void addTaskListener(TaskListener listener)
```
    Adds a listener reacting on task completions.
    
    Parameters:
    listener - The listener instance
    
    Throws:
    
    java.lang.NullPointerException - If parameter is null
    Since:
    
    1.6
  - removeTaskListener
```
public void removeTaskListener(TaskListener listener)
```
    Removes a listener reacting on task completions.
    
    Parameters:
    listener - The listener instance
    
    Throws:
    
    java.lang.NullPointerException - If parameter is null
    Since:
    
    1.6
  - getTaskListeners
```
public TaskListener[] getTaskListeners()
```
    Provides the optional listeners reacting on task completions.
    The listeners are normally called by the BackgroundTaskManager instance.
    
    Returns:
    The listener container, maybe empty
    
    Throws:
    
    java.lang.NullPointerException - If parameter is null
    Since:
    
    1.6
  - getHelpID
```
public java.lang.String getHelpID()
```
    Provides the link to the help system of the application.
    
    Returns:
    Identifier to call the help system, may be null
    Since:
    
    1.6
  - hasFinished
```
public boolean hasFinished()
```
    Has this task being finished?
    
    Returns:
    Finished?
    Since:
    
    1.6
  - setTaskDialog
```
public void setTaskDialog(TaskDialog dialog)
```
    Sets the reference for the task dialog (not set when executed from command line).
    
    Parameters:
    dialog - The dialog, may be null
    Since:
    
    1.6
  - getTaskDialog
```
public TaskDialog getTaskDialog()
```
    Provides the reference for the task dialog (not set when executed from command line).
    
    Returns:
    The dialog, may be null
    Since:
    
    1.6

Class BackgroundTask

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

STATUS_INACTIVE

STATUS_RUNNING

STATUS_OK

STATUS_INFO

STATUS_WARNING

STATUS_ERROR

STATUS_CANCELLED

STATUS_TIMEOUT

STATUS_INTERRUPTED

MESSAGE_TYPE_OUT

MESSAGE_TYPE_ERR

taskListeners

Constructor Detail

BackgroundTask

BackgroundTask

Method Detail

finalize

toString

equals

getTask

getTitle

getDescription

getThreadName

getPriority

isCancelAllowed

isExclusive

getExclusiveTimeout

isIndeterminate

isAutoClose

setAutoClose

isAutoBackground

setAutoBackground

getStartDate

setStartDate

getEndDate

setEndDate

getProgress

setProgress

resetProgress

setProgress

calculateProgress

getMessage

getMessages

setMessages

setMessage

setMessage

setStatusAndMessage

getStatus

setStatus

getIcon

canRestart

isKeepFinished

setKeepFinished

isInterrupted

setInterrupted

configureUnit

storeUnit

unitRegistered

unitUnregistered

isUnitRegistered

unregisterUnit

addTaskListener

removeTaskListener

getTaskListeners

getHelpID

hasFinished

setTaskDialog

getTaskDialog