Export plug-ins are plug-ins that takes data from BASE, and
prepares it for use with some external entity. Usually this
means that data is taken from the database and put into a file
with some well-defined file format.
An export plug-in should return MainType.EXPORT
from
the Plugin.getMainType()
method.
An export plug-in may want to give the user a choice
between saving the exported data in the BASE file system
or to download it immediately to the client computer. With the basic
plug-in API the second option is not possible. The
ImmediateDownloadExporter
is an
interface that extends the Plugin
interface to provide this functionality. If your export
plug-in wants to provide immediate download functionality it must
implement the ImmediateDownloadExporter
interface.
public void doExport(ExportOutputStream out,
ProgressReporter progress);
Perform the export. The plug-in should write the
exported data to the out
stream.
If the progress
parameter is not null,
the progress should be reported at regular interval in the
same manner as in the Plugin.run()
method.
The ExportOutputStream
is
an extension to the
java.io.OutputStream
. Use the regular
write()
methods to write data to it.
It also has some additional methods, which are used for setting
metadata about the generated file. These methods are useful, for
example, when generating HTTP response headers.
Note | |
---|---|
These methods must be called before starting to write data to
the |
public void setContentLength(long contentLength);
Set the total size of the exported data. Don't call this method if the total size is not known.
public void setMimeType(String mimeType);
Set the MIME type of the file that is being generated.
public void setCharacterSet(String charset);
Sets the character set used in text files. For example, UTF-8 or ISO-8859-1.
public void setFilename(String filename);
Set a suggested name of the file that is being generated.
Supporting immediate download also means that the method call sequence is a bit altered from the standard sequence described in the section called “Executing a job”.
The plug-in must call Response.setDownloadImmediately()
instead of Response.setDone()
in Plugin.configure()
to end the job configuration wizard. This requests that the core starts
an immediate download.
Note | |
---|---|
Even if an immediate download is requested by the plug-in this feature may have been disabled by the server administrator. If so, the plug-in can choose if the job should be added to job queue or if this is an error condition. |
If immediate download is granted the web client will keep the
same plug-in instance and call ImmediateDownloadExporter.doExport()
.
In this case, the Plugin.run()
is never called.
After the export, Plugin.done()
is called as
usual.
If immediate download is not granted and the job is added to the job queue the regular job execution sequence is used.
This is an abstract superclass that will make it easier
to implement export plug-ins that support immediate
download. It defines PluginParameter
objects for asking a user about a path where the exported
data should be saved and if existing files should be overwritten or not.
If the user leaves the path empty the immediate download functionality
should be used. It also contains implementations of both the
Plugin.run()
method and the
ImmediateDownloadExporter.doExport()
method.
Here is what you need to do in your own plug-in code (code examples are
taken from the HelpExporter
):
Your plug-in should extend the AbstractExporterPlugin
class:
public class HelpExporter extends AbstractExporterPlugin implements InteractivePlugin
You need to implement the
InteractivePlugin.getRequestInformation()
method. Use the getSaveAsParameter()
and getOverwriteParameter()
methods defined in the
superclass to create plug-in parameters that asks for the file name to save
to and if existing files can be overwritten or not.
You should also check if the administrator has enabled the immediate execution
functionality for your plug-in. If not, the only option is to
export to a file in the BASE file system and the filename is a
required parameter.
// Selected parts of the getRequestConfiguration() method ... List<PluginParameter<?>> parameters = new ArrayList<PluginParameter<?>>(); ... PluginDefinition pd = job.getPluginDefinition(); boolean requireFile = pd == null ? false : !pd.getAllowImmediateExecution(); parameters.add(getSaveAsParameter(null, null, defaultPath, requireFile)); parameters.add(getOverwriteParameter(null, null)); configureJob = new RequestInformation ( Request.COMMAND_CONFIGURE_JOB, "Help exporter options", "Set Client that owns the helptexts, " + "the file path where the export file should be saved", parameters ); .... return configureJob;
You must also implement the configure()
method and check the parameters. If no filename has been given,
you should check if immediate exection is allowed and set an
error if it is not. If a filename is present, use the
pathCanBeUsed()
method to check if
it is possible to save the data to a file with that name. If the
file already exists it can be overwritten if the OVERWRITE
is TRUE
or if the file has been flagged for removal.
Do not forget to store the parameters with the storeValue()
method.
// Selected parts from the configure() method if (request.getParameterValue(SAVE_AS) == null) { if (!request.isAllowedImmediateExecution()) { response.setError("Immediate download is not allowed. " + "Please specify a filename.", null); return; } Client client = (Client)request.getParameterValue("client"); response.setDownloadImmediately("Export help texts for client application " + client.getName(), ExecutionTime.SHORTEST, true); } else { if (!pathCanBeUsed((String)request.getParameterValue(SAVE_AS), (Boolean)request.getParameterValue(OVERWRITE))) { response.setError("File exists: " + (String)request.getParameterValue(SAVE_AS), null); return; } storeValue(job, request, ri.getParameter(SAVE_AS)); storeValue(job, request, ri.getParameter(OVERWRITE)); response.setDone("The job configuration is complete", ExecutionTime.SHORTEST); }
Implement the performExport()
method.
This is defined as abstract in the AbstractExporterPlugin
class. It has the same parameters as the ImmediateDownloadExporter.doExport()
method and they have the same meaning. The only difference is that the
out
stream can be linked to a file in the BASE filesystem
and not just to the HTTP response stream.
Optionally, implement the begin()
,
end()
and getSuccessMessage()
methods. Theese methods do nothing by default.
The call sequence for plug-ins extending AbstractExporterPlugin
is:
Call begin()
.
Call performExport()
.
Call end()
.
Call getSuccessMessage()
if running as a regular
job. This method is never called when doing an immediate download since there
is no place to show the message.