com.mucommander.job
Class FileJob

java.lang.Object
  com.mucommander.job.FileJob

All Implemented Interfaces:

java.lang.Runnable

Direct Known Subclasses:

ChangeFileAttributesJob, DeleteJob, MkdirJob, PropertiesJob, TransferFileJob

public abstract class FileJob
extends java.lang.Object
implements java.lang.Runnable

FileJob is a container for a 'file task' : basically an operation that involves files and bytes. The class extending FileJob is required to give some information about the status of the job that will be used to display visual indications of the job's progress.

The actual processing is performed in a separate thread. A FileJob needs to be started explicitely using start(). The lifecycle of a FileJob is as follows:

 NOT_STARTED -> RUNNING -> FINISHED
                         ^                |
                         |                -> INTERRUPTED
                         |                |                      
                         |                -> PAUSED -|
                         |                                    |
                         -------------------------------------|
 

Author:

Maxence Bernard

Field Summary

protected static int	APPEND_ACTION
protected static java.lang.String	APPEND_TEXT
protected AbstractFile	baseSourceFolder Base source folder
protected static int	CANCEL_ACTION
protected static java.lang.String	CANCEL_TEXT
protected AbstractFile	currentFile File currently being processed
protected int	currentFileIndex Index of file currently being processed, see getCurrentFileIndex()
protected java.lang.String	currentFilename Name of the file currently being processed
protected FileSet	files Files which are going to be processed
static int	FINISHED Indicates that this job has naturally finished (i.e.
static int	INTERRUPTED Indicates that this job has been interrupted by the end user, this is a permanent state
protected MainFrame	mainFrame Main frame on which the job is to be performed
protected int	nbFiles Number of files that this job contains
static int	NOT_STARTED Indicates that this job has not started yet, this is a temporary state
static int	PAUSED Indicates that this job is currently paused, waiting for user response, this is a temporary state
protected ProgressDialog	progressDialog Associated dialog showing job progression
protected static int	RETRY_ACTION
protected static java.lang.String	RETRY_TEXT
static int	RUNNING Indicates that this job is currently processing files, this is a temporary state
protected static int	SKIP_ACTION
protected static java.lang.String	SKIP_TEXT

Constructor Summary

FileJob(MainFrame mainFrame, FileSet files)
Creates a new FileJob without starting it, and with no associated ProgressDialog.

FileJob(ProgressDialog progressDialog, MainFrame mainFrame, FileSet files)
Creates a new FileJob without starting it.

Method Summary

void	addFileJobListener(FileJobListener listener) Registers a FileJobListener to receive notifications whenever state of this FileJob changes.
int	getCurrentFileIndex() Returns the index of the file currently being processed, getNbFiles() if all files have been processed.
protected java.lang.String	getCurrentFilename() Returns the name of the file currently being processed surrounded by simple quotes (e.g.
long	getEffectiveJobTime() Returns the number of milliseconds this job effectively spent processing files, exclusing any pause time.
long	getEndDate() Returns the timestamp in milliseconds when this job ended, 0 if this job hasn't finished yet.
int	getNbFiles() Returns the number of file that this job contains.
long	getPausedTime() Returns the number of milliseconds during which this job has been paused (been waiting for some user response).
long	getPauseStartDate() Returns the timestamp in milliseconds when this job was last paused, 0 if this job has not been paused yet.
long	getStartDate() Returns the timestamp in milliseconds when this job started.
int	getState() Returns the current state of this FileJob.
java.lang.String	getStatusString() Returns a String describing what the job is currently doing.
float	getTotalPercentDone() Returns this job's percentage of completion, as a float comprised between 0 and 1.
protected abstract boolean	hasFolderChanged(AbstractFile folder) Returns true if the given folder has or may have been modified by this job.
void	interrupt() Interrupts this job, changes the job state to INTERRUPTED and notifies listeners.
protected void	jobCompleted() This method is called when this job has completed normal execution : all files have been processed without any interruption (without any call to interrupt()).
protected void	jobPaused() This method is called when this job has been paused, either by the user, or by the job when asking for user input.
protected void	jobResumed() This method is called when this job has been resumed after being paused.
protected void	jobStarted() This method is called when this job starts, before the first call to processFile(AbstractFile,Object) is made.
protected void	jobStopped() This method is called when this job has been stopped.
protected void	nextFile(AbstractFile file) Changes the current file.
protected abstract boolean	processFile(AbstractFile file, java.lang.Object recurseParams) Automatically called by run() for each file that needs to be processed.
protected void	refreshTables() Check and if needed, refreshes both file tables's current folders, based on the job's refresh policy.
void	removeFileJobListener(FileJobListener listener) Removes the given FileJobListener from the list of listeners that receive notifications when the state of this FileJob has changed.
void	run() This method is public as a side-effect of this class implementing Runnable.
void	selectFileWhenFinished(AbstractFile file) Sets the given file to be selected in the active table after this job has finished.
void	setAutoUnmark(boolean autoUnmark) Specifies whether or not files that have been processed should be unmarked from current table (enabled by default).
void	setPaused(boolean paused) Sets or unsets this job in paused mode.
protected void	setState(int jobState) Sets a new state for this FileJob and notifies registered FileJobListener instances of the change.
protected int	showErrorDialog(java.lang.String title, java.lang.String message) Displays an error dialog with the specified title and message, offers to skip the file, retry or cancel and waits for user choice.
protected int	showErrorDialog(java.lang.String title, java.lang.String message, java.lang.String[] actionTexts, int[] actionValues) Displays an error dialog with the specified title and message and returns the selection action's value.
void	start() Starts file job in a separate thread.
protected int	waitForUserResponse(QuestionDialog dialog) Waits for the user's answer to the given question dialog, putting this job in pause mode while waiting for the user.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

progressDialog

protected ProgressDialog progressDialog

Associated dialog showing job progression

mainFrame

protected MainFrame mainFrame

Main frame on which the job is to be performed

baseSourceFolder

protected AbstractFile baseSourceFolder

Base source folder

files

protected FileSet files

Files which are going to be processed

nbFiles

protected int nbFiles

Number of files that this job contains

currentFileIndex

protected int currentFileIndex

Index of file currently being processed, see getCurrentFileIndex()

currentFile

protected AbstractFile currentFile

File currently being processed

currentFilename

protected java.lang.String currentFilename

Name of the file currently being processed

NOT_STARTED

public static final int NOT_STARTED

Indicates that this job has not started yet, this is a temporary state

See Also:

Constant Field Values

RUNNING

public static final int RUNNING

Indicates that this job is currently processing files, this is a temporary state

See Also:

Constant Field Values

PAUSED

public static final int PAUSED

Indicates that this job is currently paused, waiting for user response, this is a temporary state

See Also:

Constant Field Values

INTERRUPTED

public static final int INTERRUPTED

Indicates that this job has been interrupted by the end user, this is a permanent state

See Also:

Constant Field Values

FINISHED

public static final int FINISHED

Indicates that this job has naturally finished (i.e. without being interrupted), this is a permanent state

See Also:

Constant Field Values

SKIP_ACTION

protected static final int SKIP_ACTION

See Also:

Constant Field Values

RETRY_ACTION

protected static final int RETRY_ACTION

See Also:

Constant Field Values

CANCEL_ACTION

protected static final int CANCEL_ACTION

See Also:

Constant Field Values

APPEND_ACTION

protected static final int APPEND_ACTION

See Also:

Constant Field Values

SKIP_TEXT

protected static final java.lang.String SKIP_TEXT

RETRY_TEXT

protected static final java.lang.String RETRY_TEXT

CANCEL_TEXT

protected static final java.lang.String CANCEL_TEXT

APPEND_TEXT

protected static final java.lang.String APPEND_TEXT

Constructor Detail

FileJob

public FileJob(ProgressDialog progressDialog,
               MainFrame mainFrame,
               FileSet files)

Creates a new FileJob without starting it.

Parameters:

progressDialog - dialog which shows this job's progress

mainFrame - mainFrame this job has been triggered by

files - files which are going to be processed

FileJob

public FileJob(MainFrame mainFrame,
               FileSet files)

Creates a new FileJob without starting it, and with no associated ProgressDialog.

Parameters:

mainFrame - mainFrame this job has been triggered by

files - files which are going to be processed

Method Detail

setAutoUnmark

public void setAutoUnmark(boolean autoUnmark)

Specifies whether or not files that have been processed should be unmarked from current table (enabled by default).

selectFileWhenFinished

public void selectFileWhenFinished(AbstractFile file)

Sets the given file to be selected in the active table after this job has finished. The file will only be selected if it exists in the active table's folder and if this job hasn't been cancelled. The selection will occur after the tables have been refreshed (if they are refreshed).

Parameters:

file - the file to be selected in the active table after this job has finished

start

public void start()

Starts file job in a separate thread.

getState

public int getState()

Returns the current state of this FileJob. See constant fields for possible return values.

Returns:

the current state of this FileJob. See constant fields for possible return values.

setState

protected void setState(int jobState)

Sets a new state for this FileJob and notifies registered FileJobListener instances of the change.

Parameters:

jobState - the new state

addFileJobListener

public void addFileJobListener(FileJobListener listener)

Registers a FileJobListener to receive notifications whenever state of this FileJob changes.

Listeners are stored as weak references so removeFileJobListener(FileJobListener) doesn't need to be called for listeners to be garbage collected when they're not used anymore.

Parameters:

listener - the FileJobListener to register

removeFileJobListener

public void removeFileJobListener(FileJobListener listener)

Removes the given FileJobListener from the list of listeners that receive notifications when the state of this FileJob has changed.

Parameters:

listener - the FileJobListener to remove

getStartDate

public long getStartDate()

Returns the timestamp in milliseconds when this job started.

Returns:

the timestamp in milliseconds when this job started

getEndDate

public long getEndDate()

Returns the timestamp in milliseconds when this job ended, 0 if this job hasn't finished yet.

Returns:

the timestamp in milliseconds when this job ended

getPauseStartDate

public long getPauseStartDate()

Returns the timestamp in milliseconds when this job was last paused, 0 if this job has not been paused yet.

Returns:

the timestamp in milliseconds when this job was last paused

getPausedTime

public long getPausedTime()

Returns the number of milliseconds during which this job has been paused (been waiting for some user response). If this job has been paused several times, the total is returned. If this job has not been paused yet, 0 is returned.

Returns:

the number of milliseconds during which this job has been paused

getEffectiveJobTime

public long getEffectiveJobTime()

Returns the number of milliseconds this job effectively spent processing files, exclusing any pause time.

Returns:

the number of milliseconds this job effectively spent processing files, exclusing any pause time

interrupt

public void interrupt()

Interrupts this job, changes the job state to INTERRUPTED and notifies listeners.

setPaused

public void setPaused(boolean paused)

Sets or unsets this job in paused mode.

nextFile

protected void nextFile(AbstractFile file)

Changes the current file. This method should be called by subclasses whenever the job starts processing a new file other than a top-level file, i.e. one that was passed as an argument to processFile(). ({#nextFile(AbstractFile) nextFile()} is automatically called for files in base folder).

getCurrentFilename

protected java.lang.String getCurrentFilename()

Returns the name of the file currently being processed surrounded by simple quotes (e.g. 'test.zip'), or an empty string if no file is currently being processed.

Returns:

the name of the file currently being processed surrounded by simple quotes, or an empty string if no file is currently being processed

jobStarted

protected void jobStarted()

This method is called when this job starts, before the first call to processFile(AbstractFile,Object) is made. This method implementation does nothing but it can be overriden by subclasses to perform some first-time initializations.

jobCompleted

protected void jobCompleted()

This method is called when this job has completed normal execution : all files have been processed without any interruption (without any call to interrupt()).

The call happens after the last call to processFile(AbstractFile,Object) is made. This method implementation does nothing but it can be overriden by subclasses to properly complete the job.

Note that this method will NOT be called if a call to interrupt() was made before all files were processed.

jobPaused

protected void jobPaused()

This method is called when this job has been paused, either by the user, or by the job when asking for user input.

This method implementation does nothing but it can be overriden by subclasses to do whatever is needed when the job has been paused.

jobResumed

protected void jobResumed()

This method is called when this job has been resumed after being paused.

This method implementation does nothing but it can be overriden by subclasses to do whatever is needed when the job has returned from pause.

jobStopped

protected void jobStopped()

This method is called when this job has been stopped. The call happens after all calls to processFile(AbstractFile,Object) and jobCompleted(). This method implementation does nothing but it can be overriden by subclasses to properly terminate the job. This is where you want to close any opened connections.

Note that unlike jobCompleted() this method is always called, whether the job has been completed (all files were processed) or has been interrupted in the middle.

showErrorDialog

protected int showErrorDialog(java.lang.String title,
                              java.lang.String message)

Displays an error dialog with the specified title and message, offers to skip the file, retry or cancel and waits for user choice. The job is stopped if 'cancel' or 'close' was chosen, and the result is returned.

showErrorDialog

protected int showErrorDialog(java.lang.String title,
                              java.lang.String message,
                              java.lang.String[] actionTexts,
                              int[] actionValues)

Displays an error dialog with the specified title and message and returns the selection action's value.

waitForUserResponse

protected int waitForUserResponse(QuestionDialog dialog)

Waits for the user's answer to the given question dialog, putting this job in pause mode while waiting for the user.

refreshTables

protected void refreshTables()

Check and if needed, refreshes both file tables's current folders, based on the job's refresh policy.

getTotalPercentDone

public float getTotalPercentDone()

Returns this job's percentage of completion, as a float comprised between 0 and 1.

Returns:

this job's percentage of completion, as a float comprised between 0 and 1

getCurrentFileIndex

public int getCurrentFileIndex()

Returns the index of the file currently being processed, getNbFiles() if all files have been processed.

Returns:

the index of the file currently being processed, getNbFiles() if all files have been processed

getNbFiles

public int getNbFiles()

Returns the number of file that this job contains.

Returns:

the number of file that this job contains

getStatusString

public java.lang.String getStatusString()

Returns a String describing what the job is currently doing. This default implementation returns Processing CURRENT_FILE where CURRENT_FILE is the name of the file currently being processed. This method should be overridden to provide a more accurate description.

Returns:

a String describing what the job is currently doing

run

public final void run()

This method is public as a side-effect of this class implementing Runnable.

Specified by:

run in interface java.lang.Runnable

hasFolderChanged

protected abstract boolean hasFolderChanged(AbstractFile folder)

Returns true if the given folder has or may have been modified by this job. This method is called after this job has finished processing files, to determine if the current MainFrame's file tables need to be refreshed to reveal the modified contents.

Parameters:

folder - the folder to test

Returns:

true if the given folder has or may have been modified by this job

processFile

protected abstract boolean processFile(AbstractFile file,
                                       java.lang.Object recurseParams)

Automatically called by run() for each file that needs to be processed.

Parameters:

file - the file or folder to process

recurseParams - array of parameters which can be used when calling this method recursively, contains null when called by run()

Returns:

true if the operation was sucessful