java.lang.Object
- com.tagtraum.beatunes.analysis.Task

All Implemented Interfaces:

TaskFactory, TaskProcessListener, TaskRunListener, Matchable<PlayList.SubstringFilterProperty>, Cloneable

Direct Known Subclasses:

AudioAnalysisTask, AudioPumpAnalysisTask, SongAnalysisTask
```
@Entity
public class Task
extends Object
implements Matchable<PlayList.SubstringFilterProperty>, Cloneable, TaskFactory, TaskRunListener, TaskProcessListener
```
Provides the infrastructure for tasks that may contain other tasks.
To implement your own custom task, subclass AudioAnalysisTask or SongAnalysisTask, depending on whether you want to analyze audio data or just meta data. In any case, make sure you mark the class with the Entity annotation. This is essential - otherwise it does not get persisted and never shows up in the queue.
A task needs a TaskEditor - by default that's a class with the same name, but with "Editor" appended or an empty editor, in case that class is not found. If you want to instantiate a different editor, override createEditor().
In order to provide any behavior, you should override runBefore(Task). This is where you must do the heavy lifting, i.e. analyze audio or similar things.
If your task is capable of processing online reference data, also override TaskProcessListener.processBefore(Task) and call setUseOnlineResources(boolean) with the argument true. getReferenceSong() will provide available reference data.
In either case, you should always signal, whether what you did succeeded or not. You can do so with setSucceeded(boolean) and setSkipped(boolean).
To register your task with beaTunes you need to add an entry to your META-INF/plugin.xml.
If you need to store any configurations parameters persistently, you may manipulate the persistent property map using setProperty(String, String). Note that this should only occur at configuration time using a TaskEditor created with createEditor(). At runtime, you may read values using getProperty(String).

Author:

Hendrik Schreiber

See Also:

PluginManager, TaskEditor

Field Summary

Fields
Modifier and Type Field Description

protected boolean useOnlineResources

Constructor Summary

Constructors
Constructor Description

Task()

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`void`	`add(Task task)`
`void`	`addTaskProcessListener(TaskProcessListener taskProcessListener)`
`void`	`addTaskRunListener(TaskRunListener taskRunListener)`
`void`	`cancel()`	Asynchronously cancels this and all of its subtasks, if possible.
`void`	`clearProperties()`	Delete all properties.
`Task`	`createDeepCopy()`	This method creates a copy of the Task and its subtasks.
`TaskEditor<? extends Task>`	`createEditor()`	By default instantiates a class with the name `this.getClass().getName() + "Editor"`.
`Task`	`createTask()`
`boolean`	`deepRemove(Task task)`	Deep remove.
`boolean`	`equals(Object obj)`
`protected void`	`fetchCollections()`	Fetches any lazily initialized collections, if necessary.
`AnalysisProgress`	`getAnalysisProgress()`
`BeaTunes`	`getApplication()`
`AudioFileFormat`	`getAudioFileFormat()`
`Operation`	`getCurrentOperation()`
`Task[]`	`getDeepLeafs()`
`int`	`getDeepTaskCount(boolean onlyProgressRelevant)`	Counts this task and all its sub tasks.
`Task[]`	`getDeepTasks()`	All subtasks and their subtasks.
`String`	`getDescription()`	HTML or plain text description of this task.
`TaskEditor<? extends Task>`	`getEditor()`	Creates and initializes a `TaskEditor` with this task.
`long`	`getId()`
`protected MessagePanel`	`getMessagePanel()`	Convenience method for getting the analysis queue message panel.
`String`	`getName()`	HTML or plaintext name of this task.
`Task`	`getParent()`
`int`	`getPriority()`
`Map<String,String>`	`getProperties()`	Used for XML based persistence by beaTunes.
`String`	`getProperty(String propertyName)`	Returns property.
`Iterator<String>`	`getPropertyNames()`	Names of persistent properties.
`ReferenceSong`	`getReferenceSong()`
`AudioSong`	`getSong()`
`Long`	`getSongId()`
`Task`	`getTask(int index)`
`int`	`getTaskCount()`
`Task[]`	`getTasks()`	All subtasks without their subtasks.
`int`	`hashCode()`
`boolean`	`hasSucceeded()`	Indicates whether processing or running this task succeeded.
`boolean`	`isAvailable()`	Indicate, whether this task is actually available in the current configuration.
`boolean`	`isCancelled()`
`boolean`	`isDeepUseOnlineResources()`	Indicates whether this task or any of its sub-tasks want to use online resources.
`boolean`	`isFileExistedBeforeStart()`	Indicates whether the file (if any) associated with this song (`getSong()`) and task existed before processing started.
`boolean`	`isLeaf()`
`boolean`	`isPaused()`
`boolean`	`isProgressRelevant()`
`boolean`	`isUseOnlineResources()`	Indicates whether this task should use online resources.
`boolean`	`matches(Pattern[] patterns, PlayList.SubstringFilterProperty substringFilterProperty)`	True if this object matches all provided patters (logical AND).
`protected void`	`maybePause()`	Checks whether the task got paused or cancelled.
`void`	`process()`
`void`	`processAfter(Task task)`	Is executed after sub tasks are run.
`void`	`processBefore(Task task)`	Process online results with this task before other tasks are invoked.
`void`	`processFinally(Task task)`	Is executed after sub tasks are run regardless of whether those sub tasks succeeded or not.
`boolean`	`remove(Task task)`	Shallow remove.
`boolean`	`removeDeadLeaves()`	Removes any leaves that have succeeded (`hasSucceeded()`), were not skipped (!`wasSkipped()`) and used online resources (`useOnlineResources`).
`void`	`run()`	Calls `runBefore(Task)`, all the sub task's `run()` methods, and `runAfter(Task)`.
`void`	`runAfter(Task task)`	Is executed after sub tasks are run.
`void`	`runBefore(Task task)`	Is executed before sub tasks are run.
`void`	`runFinally(Task task)`	Is executed after sub tasks are run regardless of whether those sub tasks succeeded or not.
`void`	`setAnalysisProgress(AnalysisProgress analysisProgress)`
`void`	`setApplication(BeaTunes beaTunes)`
`void`	`setAudioFileFormat(AudioFileFormat audioFileFormat)`
`protected void`	`setAvailable(boolean available)`
`void`	`setCurrentOperation(Operation currentOperation)`
`void`	`setId(long id)`
`void`	`setParent(Task parent)`
`void`	`setPaused(boolean paused)`	Pauses ot resumes this and all of its sub tasks.
`void`	`setPriority(int priority)`	Subtasks with lower priority are executed first.
`void`	`setProgressRelevant(boolean progressRelevant)`
`void`	`setProperties(Map<String,String> properties)`	Used for XML based persistence by beaTunes.
`String`	`setProperty(String name, String value)`	Sets persistent property.
`void`	`setReferenceSong(ReferenceSong referenceSong)`
`protected void`	`setSkipped(boolean skipped)`	Indicates whether this task was skipped by either `runBefore(Task)` or `TaskProcessListener.processBefore(Task)` (or similar methods).
`void`	`setSong(AudioSong song)`	Sets the song associated with this task.
`void`	`setSongId(Long id)`
`protected void`	`setSucceeded(boolean succeeded)`	Indicates whether processing or running a task with `runBefore(Task)` or `TaskProcessListener.processBefore(Task)` (or similar methods) succeeded and led to the desired results, implying that it does not need to be processed any further.
`void`	`setUseOnlineResources(boolean useOnlineResources)`	Determines whether this task should use online resources.
`boolean`	`skip()`	Indicates, whether this task can be skipped.
`String`	`toString()`
`boolean`	`wasSkipped()`

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

- Field Detail
  - useOnlineResources
```
protected boolean useOnlineResources
```
- Constructor Detail
  - Task
```
public Task()
```
- Method Detail
  - addTaskProcessListener
```
public void addTaskProcessListener(TaskProcessListener taskProcessListener)
```
  - addTaskRunListener
```
public void addTaskRunListener(TaskRunListener taskRunListener)
```
  - hasSucceeded
```
public boolean hasSucceeded()
```
    Indicates whether processing or running this task succeeded.
    
    Returns:
    
    true or false
    
    See Also:
    
    setSucceeded(boolean)
  - setSucceeded
```
protected void setSucceeded(boolean succeeded)
```
    Indicates whether processing or running a task with runBefore(Task) or TaskProcessListener.processBefore(Task) (or similar methods) succeeded and led to the desired results, implying that it does not need to be processed any further. This method must be called by your implementation of runBefore(Task) or TaskProcessListener.processBefore(Task). It is not called automatically!
    
    Parameters:
    
    succeeded - true or false
    
    See Also:
    
    setSkipped(boolean), hasSucceeded()
  - wasSkipped
```
public boolean wasSkipped()
```
    Returns:
    
    true or false
    
    See Also:
    
    setSkipped(boolean)
  - setSkipped
```
protected void setSkipped(boolean skipped)
```
    Indicates whether this task was skipped by either runBefore(Task) or TaskProcessListener.processBefore(Task) (or similar methods). This method is not called automatically, but must be called by your implementation, whenever you decide to skip processing/running a task.
    
    Parameters:
    
    skipped - skipped
    
    See Also:
    
    skip(), wasSkipped(), setSucceeded(boolean)
  - isAvailable
```
public boolean isAvailable()
```
    Indicate, whether this task is actually available in the current configuration. A task may not be available for non-iTunes libraries.
    
    Returns:
    
    true or false
    
    See Also:
    
    MediaLibrary.getLibraryDescriptor()
  - setAvailable
```
protected void setAvailable(boolean available)
```
    Parameters:
    
    available - available
    
    See Also:
    
    isAvailable()
  - getEditor
```
public TaskEditor<? extends Task> getEditor()
```
    Creates and initializes a TaskEditor with this task.
    
    Returns:
    
    initialized editor
    
    See Also:
    
    TaskEditor.setTask(Task)
  - createEditor
```
public TaskEditor<? extends Task> createEditor()
```
    By default instantiates a class with the name this.getClass().getName() + "Editor". If that does not work (because the editor class does not exist), an EmptyTaskEditor is created. To create a meaningful editor for a configurable task, you must override this method.
    
    Returns:
    
    task editor for this task.
  - isUseOnlineResources
```
public boolean isUseOnlineResources()
```
    Indicates whether this task should use online resources. This persistent flag is typically set in the editor createEditor(). If it is set, its TaskProcessListener.processBefore(Task) method is called once online results are available.
    
    Returns:
    
    true or false (defaults to false)
    
    See Also:
    
    process()
  - setUseOnlineResources
```
public void setUseOnlineResources(boolean useOnlineResources)
```
    Determines whether this task should use online resources. This flag is persistent.
    
    Parameters:
    
    useOnlineResources - true or false
    
    See Also:
    
    isUseOnlineResources()
  - isDeepUseOnlineResources
```
public boolean isDeepUseOnlineResources()
```
    Indicates whether this task or any of its sub-tasks want to use online resources.
    
    Returns:
    
    true or false
  - cancel
```
public void cancel()
```
    Asynchronously cancels this and all of its subtasks, if possible.
  - getCurrentOperation
```
public Operation getCurrentOperation()
```
  - setCurrentOperation
```
public void setCurrentOperation(Operation currentOperation)
```
  - isCancelled
```
public boolean isCancelled()
```
  - isPaused
```
public boolean isPaused()
```
  - setPaused
```
public void setPaused(boolean paused)
```
    Pauses ot resumes this and all of its sub tasks.
    
    Parameters:
    
    paused - true or false
  - getApplication
```
public BeaTunes getApplication()
```
    Returns:
    
    this task's or its parent's beaTunes instance
  - setApplication
```
public void setApplication(BeaTunes beaTunes)
```
  - getAnalysisProgress
```
public AnalysisProgress getAnalysisProgress()
```
    Returns:
    
    this task's or its parent's AnalysisProgress instance
  - setAnalysisProgress
```
public void setAnalysisProgress(AnalysisProgress analysisProgress)
```
  - isProgressRelevant
```
public boolean isProgressRelevant()
```
    Returns:
    
    true if this task relevant for overall progress computations.
  - setProgressRelevant
```
public void setProgressRelevant(boolean progressRelevant)
```
    Parameters:
    
    progressRelevant - set this to true, if you want this task and its subtasks to be included in overall progress computations.
  - getSong
```
public AudioSong getSong()
```
    Returns:
    
    this task's or its parent's Song instance
  - setSong
```
public void setSong(AudioSong song)
```
    Sets the song associated with this task. At the same time the persistent id of this song will be registered using setSongId(Long).
    
    Parameters:
    
    song - song
  - setReferenceSong
```
public void setReferenceSong(ReferenceSong referenceSong)
```
  - getReferenceSong
```
public ReferenceSong getReferenceSong()
```
    Returns:
    
    this task's or its parent's ReferenceSong instance
  - isFileExistedBeforeStart
```
public boolean isFileExistedBeforeStart()
```
    Indicates whether the file (if any) associated with this song (getSong()) and task existed before processing started.
    
    Returns:
    
    true or false
  - fetchCollections
```
protected void fetchCollections()
```
    Fetches any lazily initialized collections, if necessary.
  - getSongId
```
public Long getSongId()
```
  - setSongId
```
public void setSongId(Long id)
```
  - getAudioFileFormat
```
public AudioFileFormat getAudioFileFormat()
```
    Returns:
    
    this task's or its parent's AudioFileFormat instance (if set)
  - setAudioFileFormat
```
public void setAudioFileFormat(AudioFileFormat audioFileFormat)
```
  - getParent
```
public Task getParent()
```
  - setParent
```
public void setParent(Task parent)
```
  - getTask
```
public Task getTask(int index)
```
    Parameters:
    
    index - index
    
    Returns:
    
    sub task
  - getTaskCount
```
public int getTaskCount()
```
    Returns:
    
    number of (sub)tasks contained in this task
  - getDeepTaskCount
```
public int getDeepTaskCount(boolean onlyProgressRelevant)
```
    Counts this task and all its sub tasks.
    
    Parameters:
    
    onlyProgressRelevant - count only tasks relevant for progress computation
    
    Returns:
    
    deep count
  - add
```
public final void add(Task task)
```
    Parameters:
    
    task - task to add
  - remove
```
public boolean remove(Task task)
```
    Shallow remove.
    
    Parameters:
    
    task - task to remove
    
    Returns:
    
    true, if successful
  - deepRemove
```
public boolean deepRemove(Task task)
```
    Deep remove.
    
    Parameters:
    
    task - task to remove
    
    Returns:
    
    true, if successful
  - removeDeadLeaves
```
public boolean removeDeadLeaves()
```
    Removes any leaves that have succeeded (hasSucceeded()), were not skipped (!wasSkipped()) and used online resources (useOnlineResources).
    
    Returns:
    
    true, if any leaves were removed
  - getTasks
```
public Task[] getTasks()
```
    All subtasks without their subtasks.
    
    Returns:
    
    shallow sub tasks
  - getDeepTasks
```
public Task[] getDeepTasks()
```
    All subtasks and their subtasks.
    
    Returns:
    
    deep sub tasks
  - getDeepLeafs
```
public Task[] getDeepLeafs()
```
    Returns:
    
    deep walk to get all leafs
  - isLeaf
```
public boolean isLeaf()
```
  - process
```
public void process()
```
  - processBefore
```
public void processBefore(Task task)
```
    Process online results with this task before other tasks are invoked. Override this method, if you want to take online resources into account. Note that you will also need to set setUseOnlineResources(boolean) to true, if you want this method to be called at all.
    To avoid having this task processed again by runBefore(Task), you must call setSucceeded(boolean) with the argument true. If, for some reason, you could not take care of this task with just the available online resources, you must call setSucceeded(boolean) with the argument false
    This method is executed before sub tasks are run. When this method is called, the methods getSong() and getReferenceSong() will return meaningful results.
    
    Specified by:
    
    processBefore in interface TaskProcessListener
    
    Parameters:
    
    task - task
  - processAfter
```
public void processAfter(Task task)
```
    Is executed after sub tasks are run.
    
    Specified by:
    
    processAfter in interface TaskProcessListener
    
    Parameters:
    
    task - task
    
    See Also:
    
    TaskProcessListener.processBefore(Task)
  - processFinally
```
public void processFinally(Task task)
```
    Is executed after sub tasks are run regardless of whether those sub tasks succeeded or not.
    
    Specified by:
    
    processFinally in interface TaskProcessListener
    
    Parameters:
    
    task - task
    
    See Also:
    
    TaskProcessListener.processBefore(Task)
  - run
```
public void run()
         throws AnalysisException
```
    Calls runBefore(Task), all the sub task's run() methods, and runAfter(Task). Then runFinally(Task) is called.
    
    Throws:
    
    AnalysisException - if any of the analysis steps throw an AnalysisException
  - maybePause
```
protected void maybePause()
```
    Checks whether the task got paused or cancelled.
  - runBefore
```
public void runBefore(Task task)
               throws AnalysisException
```
    Is executed before sub tasks are run.
    
    Specified by:
    
    runBefore in interface TaskRunListener
    
    Parameters:
    
    task - task
    
    Throws:
    
    AnalysisException - if this analysis step fails
  - runAfter
```
public void runAfter(Task task)
              throws AnalysisException
```
    Is executed after sub tasks are run.
    
    Specified by:
    
    runAfter in interface TaskRunListener
    
    Parameters:
    
    task - task
    
    Throws:
    
    AnalysisException - if this analysis step fails
  - runFinally
```
public void runFinally(Task task)
```
    Is executed after sub tasks are run regardless of whether those sub tasks succeeded or not.
    
    Specified by:
    
    runFinally in interface TaskRunListener
    
    Parameters:
    
    task - task
  - matches
```
public boolean matches(Pattern[] patterns,
                       PlayList.SubstringFilterProperty substringFilterProperty)
```
    Description copied from interface: Matchable
    
    True if this object matches all provided patters (logical AND).
    
    Specified by:
    
    matches in interface Matchable<PlayList.SubstringFilterProperty>
    
    Parameters:
    
    patterns - patterns
    
    substringFilterProperty - specifies a particular way in which the match should occur
    
    Returns:
    
    true if this object matches.
  - getId
```
public long getId()
```
  - setId
```
public void setId(long id)
```
  - skip
```
public boolean skip()
```
    Indicates, whether this task can be skipped. Defaults to false.
    Since this task is not necessarily called by beaTunes, but by your own implementation of runBefore(Task), you should call setSkipped(boolean) with whatever value you are returning.
    
    Returns:
    
    true or false
  - getDescription
```
public String getDescription()
```
    HTML or plain text description of this task.
    
    Returns:
    
    description
  - getName
```
public String getName()
```
    HTML or plaintext name of this task. Defaults to the task's classname.
    
    Returns:
    
    name
  - getPropertyNames
```
public final Iterator<String> getPropertyNames()
```
    Names of persistent properties.
    
    Returns:
    
    iterator over the property names
  - getProperty
```
public String getProperty(String propertyName)
```
    Returns property.
    
    Parameters:
    
    propertyName - name of the property in question
    
    Returns:
    
    value or null if not found
  - setProperty
```
public final String setProperty(String name,
                                String value)
```
    Sets persistent property. Properties are not persisted, if this method is called while the task is executed.
    
    Parameters:
    
    name - property name
    
    value - property value
    
    Returns:
    
    old property value or null, if none was set
  - clearProperties
```
public final void clearProperties()
```
    Delete all properties.
  - getProperties
```
public final Map<String,String> getProperties()
```
    Used for XML based persistence by beaTunes. For programmatic getting of properties, use getProperty(String) and getPropertyNames().
    
    Returns:
    
    unmodifiable properties map or null, if none was set
  - setProperties
```
public final void setProperties(Map<String,String> properties)
```
    Used for XML based persistence by beaTunes. For programmatic setting of properties, use setProperty(String, String) and clearProperties().
    
    Parameters:
    
    properties - properties
  - createTask
```
public final Task createTask()
```
    Specified by:
    
    createTask in interface TaskFactory
    
    Returns:
    
    copy
    
    See Also:
    
    createDeepCopy()
  - createDeepCopy
```
public Task createDeepCopy()
```
    This method creates a copy of the Task and its subtasks. If you added any members to your subclass you MUST override this method and provide code that copies your members.
    
    Returns:
    
    copy
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - getPriority
```
public int getPriority()
```
    Returns:
    
    priority
  - setPriority
```
public void setPriority(int priority)
```
    Subtasks with lower priority are executed first.
    
    Parameters:
    
    priority - priority
  - getMessagePanel
```
protected MessagePanel getMessagePanel()
```
    Convenience method for getting the analysis queue message panel.
    
    Returns:
    
    message panel
    
    See Also:
    
    Message

Class Task

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

useOnlineResources

Constructor Detail

Task

Method Detail

addTaskProcessListener

addTaskRunListener

hasSucceeded

setSucceeded

wasSkipped

setSkipped

isAvailable

setAvailable

getEditor

createEditor

isUseOnlineResources

setUseOnlineResources

isDeepUseOnlineResources

cancel

getCurrentOperation

setCurrentOperation

isCancelled

isPaused

setPaused

getApplication

setApplication

getAnalysisProgress

setAnalysisProgress

isProgressRelevant

setProgressRelevant

getSong

setSong

setReferenceSong

getReferenceSong

isFileExistedBeforeStart

fetchCollections

getSongId

setSongId

getAudioFileFormat

setAudioFileFormat

getParent

setParent

getTask

getTaskCount

getDeepTaskCount

add

remove

deepRemove

removeDeadLeaves

getTasks

getDeepTasks

getDeepLeafs

isLeaf

process

processBefore

processAfter

processFinally

run

maybePause

runBefore

runAfter

runFinally

matches

getId

setId

skip

getDescription

getName

getPropertyNames

getProperty

setProperty

clearProperties

getProperties

setProperties

createTask