26.4. Export plug-ins

26.4.1. Immediate download of exported data
The ImmediateDownloadExporter interface
The ExportOutputStream class
Call sequence during immediate download
26.4.2. The AbstractExporterPlugin class

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.

26.4.1. Immediate download of exported data

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.

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 class

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] Note

These methods must be called before starting to write data to the out stream.

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.

Call sequence during immediate download

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] 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.

26.4.2. The AbstractExporterPlugin class

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:

  1. Call begin().

  2. Call performExport().

  3. Call end().

  4. 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.