net.sf.basedb.core.plugin
Interface Response

All Known Implementing Classes:

ExternalProgramExecutor.ResponseWrapper, PluginResponse.ResponseImpl

public interface Response

The response interface used by the core.

Version:

2.0

Author:

Nicklas, Enell

Last modified

$Date$

Nested Class Summary

static class

Response.Status

Method Summary

void	setContinue(String nextCommand) This method will continue the configuration or execution of the job with a new command to the plugin.
void	setDone(String message) This will end the job execution and report it as a success.
void	setDone(String message, Job.ExecutionTime estimatedExecutionTime) This will end the configuration of a job and set the estimated execution time for it.
void	setDownloadImmediately(String message, Job.ExecutionTime estimatedExecutionTime, boolean failIfDenied) This will end the configuration of a export job, and start to execute it for immediate download.
void	setDryRun(boolean dryRun) A plug-in may call this method in it's configuration phase or after it has been executed to indicate that the job should be or was executed as a dry-run job.
void	setError(String message, List<? extends Throwable> errorList) This will end the job execution or configuration and report it as a failure.
void	setExecuteImmediately(String message, Job.ExecutionTime estimatedExecutionTime, boolean failIfDenied) This will end the configuration of a job, and start to execute it immediately if the plugin is permitted to do so.
void	setSuggestedJobName(String jobName) A plug-in may call this method on it's job configuration phase to suggest a name for the job.

Method Detail

setContinue

void setContinue(String nextCommand)
                 throws PermissionDeniedException

This method will continue the configuration or execution of the job with a new command to the plugin. If the plug-in is currently being configured the configuration will continue with the next command. If the plug-in is currently executing the job will be returned to job queue. The intention is that plug-ins can use this to survive a temporary shutdown of the system after catching the Signal.SHUTDOWN signal.

Parameters:

nextCommand - The next command to the plugin

Throws:

PermissionDeniedException - If another command isn't allowed

setDone

void setDone(String message,
             Job.ExecutionTime estimatedExecutionTime)

This will end the configuration of a job and set the estimated execution time for it.

Parameters:

message - An optional message

estimatedExecutionTime - An estimated execution time for the job, null is the same as ExecutionTime.LONG

setExecuteImmediately

void setExecuteImmediately(String message,
                           Job.ExecutionTime estimatedExecutionTime,
                           boolean failIfDenied)
                           throws PermissionDeniedException

This will end the configuration of a job, and start to execute it immediately if the plugin is permitted to do so. If it is not possible to execute the job immediately it will be added to the job queue for later execution unless the failIfDenied flag is set to true, in which case an exception will be thrown.

If immediate execution is possible the client application must continue to use the same instance of the plugin object. This means that immediate execution always happens in the same virtual machine. Plugins should be aware of this and avoid excessive use of resources such as memory and CPU time.

The client application may execute the job in another thread.

Parameters:

message - An optional message

estimatedExecutionTime - An estimated execution time for the job, null is the same as ExecutionTime.LONG. This value is only used if immediate execution isn't possible and the job has to be added to the job queue.

failIfDenied - TRUE if a PermissionDeniedException should be thrown if immediate exection isn't possible, FALSE to add the job to the job queue for later exection

Throws:

PermissionDeniedException - If logged in user doesn't have write permission on the job.

Since:

2.2

setDownloadImmediately

void setDownloadImmediately(String message,
                            Job.ExecutionTime estimatedExecutionTime,
                            boolean failIfDenied)
                            throws PermissionDeniedException

This will end the configuration of a export job, and start to execute it for immediate download. This method is similar to the setExecuteImmediately(String, Job.ExecutionTime, boolean) but:

• The plugin must implement the ImmediateDownloadExporter interface.
• The core will call ImmediateDownloadExporter.doExport(ExportOutputStream, ProgressReporter) instead of the Plugin.run(Request, Response, ProgressReporter) method.

Parameters:

message - An optional message

estimatedExecutionTime - An estimated execution time for the job, null is the same as ExecutionTime.LONG. This value is only used if immediate execution isn't possible and the job has to be added to the job queue.

failIfDenied - TRUE if a PermissionDeniedException should be thrown if immediate exection isn't possible, FALSE to add the job to the job queue for later exection

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission to the job.

Since:

2.2

setDone

void setDone(String message)

This will end the job execution and report it as a success.

Parameters:

message - A message containing any relevant information about what the plugin did, or null

setDryRun

void setDryRun(boolean dryRun)

A plug-in may call this method in it's configuration phase or after it has been executed to indicate that the job should be or was executed as a dry-run job. A dry-run job is a job that does all the things a normal job would do except committing the changes to the database. The dry-run job may output a log file with detailed information about what should have happened if it hadn't been a dry-run.

NOTE! Setting this value to true doesn't change the behaviour of the core. It is the responsibility of the plug-in to check this value(eg. Job.isDryRun() and take appropriate action.

Parameters:

dryRun - TRUE to indicate that the job should be or was executed as a dry-run

Since:

2.8

setSuggestedJobName

void setSuggestedJobName(String jobName)

A plug-in may call this method on it's job configuration phase to suggest a name for the job. Otherwise a default name will be generated by the core.

Parameters:

jobName -

Since:

2.17

setError

void setError(String message,
              List<? extends Throwable> errorList)

This will end the job execution or configuration and report it as a failure. If in a configuration sequence the client application may try the same command again with different parameters.

Parameters:

message - Information about the reason for the error

errorList - Detailed information about the error