com.docmosis.template.store
Class DropStoreHelper

java.lang.Object
  extended by com.docmosis.template.store.DropStoreHelper

public class DropStoreHelper
extends Object

This class makes it easier to pick up documents in a directory, zip or jar and register them into the (configured) store. Only templates that have changed or are new will be uploaded into the store, replacing any previously registered counterparts.

Error Handling: Any errors that occur will result in the template causing the error to not be stored, and a log error message. Templates not causing any errors will still be processed if continuation is specified by an explicit parameter (continueOnError) or set as the system default. The default setting is true and can be overridden by setting docmosis.store.dropstore.error.continue to true.

Performance: By default, timestamps are used to compare what is already cached with templates being loaded in, and only newer templates are loaded. This can be changed by setting the property docmosis.store.dropstore.compareWithTimestamps to false in which case the MD5 hash will be computed and used for comparisons.

The templates are located in the store under a context that is based on the path that the original template resides in. If no context is specified, the templates will be located at the root context.

Several methods throw NoConvertersRunningException if there are no converters online at the time of the render. If all converters are busy, these methods will still wait up to the configured max wait. This exception is only thrown if there are no operating converters in the pool.


Constructor Summary
DropStoreHelper(TemplateStore store)
          Create a new DropStoreHelper object.
DropStoreHelper(TemplateStore store, ExternalResourcePermissions externalResourcePermissions)
          Create a new DropStoreHelper object.
 
Method Summary
 void process(File dropDirectory)
          Drop a whole directory of templates into the store processing sub-directories recursively.
 void process(File dropDirectory, boolean isRecursive)
          Drop a whole directory of templates into the store optionally processing sub-directories.
 void process(File dropDirectory, TemplateContext storeContext)
          Drop a whole directory of templates into the store recursively processing sub-directories.
 void process(File dropDirectory, TemplateContext storeContext, boolean isRecursive)
          Drop a whole directory of templates into the store optionally processing sub-directories.
 void processDirectory(File dropDirectory, TemplateContext storeContext, boolean isRecursive, boolean continueOnError)
          Drop a whole directory of templates into the store, optionally into a specified context, processing sub-directories and error handling.
 void processJarOrZipFile(File file)
          Process the contents of a Jar or Zip file as it if was a directory.
 void processJarOrZipFile(File file, TemplateContext storeContext, boolean continueOnError)
          Process the contents of a Jar or Zip file as it if was a directory.
 void processResource(URL url)
          Process templates from the specified URL.
 void processResource(URL url, TemplateContext baseContext, boolean continueOnError)
          Process templates from the specified URL.
static TemplateValidationResult validateTemplate(InputStream templateStream, ExternalResourcePermissions externalResourcePermissions)
          Process the given stream as a template and return a TemplateValidationResult.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DropStoreHelper

public DropStoreHelper(TemplateStore store)
Create a new DropStoreHelper object. Processing is done with external resource permissions = ALL (meaning no security applied to links in the processed templates). If processed templates contain links to files or external websites, the links may be called during processing.

Parameters:
store - the store to use.

DropStoreHelper

public DropStoreHelper(TemplateStore store,
                       ExternalResourcePermissions externalResourcePermissions)
Create a new DropStoreHelper object.

Parameters:
store - the store to use.
externalResourcePermissions - a description of permissions regarding urls in the templates processed. This can be used to block template which reference file system or external websites. Permission NONE will block all external links found and ALL will allow anything. Otherwise a white-list of URL prefixes can be supplied allowing known external references to be permitted. A null value means use the system-defined default.
Method Detail

process

public void process(File dropDirectory)
             throws IOException,
                    ConversionException,
                    ConverterPoolException,
                    TemplateStoreException,
                    NoConvertersRunningException
Drop a whole directory of templates into the store processing sub-directories recursively. If an error is encountered, processing continues on a best effort by default (see documentation at the top of this class about error handling).

Parameters:
dropDirectory - the directory to pick up documents from.
Throws:
ConversionException - if a template cannot be processed
ConverterPoolException - if the converter pool is not working
TemplateStoreException - if the underlying template store has an error
IOException - if an IO error occurs
NoConvertersRunningException - if there are no converters running

process

public void process(File dropDirectory,
                    TemplateContext storeContext)
             throws TemplateStoreException,
                    IOException,
                    NoConvertersRunningException
Drop a whole directory of templates into the store recursively processing sub-directories. If an error is encountered, processing continues on a best effort by default (see documentation at the top of this class about error handling).

Parameters:
dropDirectory - the directory to pick up documents from.
storeContext - the context within the store to use.
Throws:
TemplateStoreException - if the underlying template store has an error
IOException - if an IO error occurs
NoConvertersRunningException - if there are no converters running

process

public void process(File dropDirectory,
                    TemplateContext storeContext,
                    boolean isRecursive)
             throws TemplateStoreException,
                    IOException,
                    NoConvertersRunningException
Drop a whole directory of templates into the store optionally processing sub-directories. If an error is encountered, processing continues on a best effort by default (see documentation at the top of this class about error handling).

Parameters:
dropDirectory - the directory to pick up documents from.
storeContext - the context within the store to use.
isRecursive - true to recursively drop sub-directories; false to only process the given directory.
Throws:
TemplateStoreException - if the underlying template store has an error
IOException - if an IO error occurs
NoConvertersRunningException - if there are no converters running

process

public void process(File dropDirectory,
                    boolean isRecursive)
             throws TemplateStoreException,
                    IOException,
                    NoConvertersRunningException
Drop a whole directory of templates into the store optionally processing sub-directories. If an error is encountered, processing continues on a best effort by default (see documentation at the top of this class about error handling).

Parameters:
dropDirectory - the directory to pick up documents from.
isRecursive - true to recursively drop sub-directories; false to only process the given directory.
Throws:
TemplateStoreException - if the underlying template store has an error
IOException - if an IO error occurs
NoConvertersRunningException - if there are no converters running

processDirectory

public void processDirectory(File dropDirectory,
                             TemplateContext storeContext,
                             boolean isRecursive,
                             boolean continueOnError)
                      throws TemplateStoreException,
                             IOException,
                             NoConvertersRunningException
Drop a whole directory of templates into the store, optionally into a specified context, processing sub-directories and error handling.

Parameters:
dropDirectory - the directory to pick up documents from.
storeContext - the context within the store to use.
isRecursive - true to recursively drop sub-directories; false to only process the given directory.
continueOnError - if true errors will be logged and processing will do its best effort to process all templates found. If false, an exception will be thrown on first problem encountered.
Throws:
TemplateStoreException - if the underlying template store has an error or the given dropDirectory is not valid
IOException - if an IO error occurs
NoConvertersRunningException - if there are no converters running

processJarOrZipFile

public void processJarOrZipFile(File file)
                         throws NoConvertersRunningException,
                                IOException,
                                ConversionException,
                                ConverterPoolException,
                                TemplateStoreException
Process the contents of a Jar or Zip file as it if was a directory. Any templates in the root of the Jar file will be dropped into the root context. All templates in sub-directories within the Jar or Zip file will be dropped into a matching sub-context so that the templates will be stored in a structure that matches the directory structure within the Jar or Zip file.

If an error is encountered, processing continues on a best effort by default (see documentation at the top of this class about error handling).

Parameters:
file - the file to process
Throws:
IOException - if an IO error occurs
NoConvertersRunningException - if there are no converters running
ConversionException - if a template cannot be processed
ConverterPoolException - if the converter pool is not working
TemplateStoreException - if the underlying template store has an error

processJarOrZipFile

public void processJarOrZipFile(File file,
                                TemplateContext storeContext,
                                boolean continueOnError)
                         throws NoConvertersRunningException,
                                IOException,
                                ConversionException,
                                ConverterPoolException,
                                TemplateStoreException
Process the contents of a Jar or Zip file as it if was a directory. Any templates in the root of the Jar file will be dropped into the given context. All templates in sub-directories within the Jar file will be dropped into a matching sub-context so that the templates will be stored in a structure that matches the directory structure within the Jar or Zip file.

Parameters:
file - the file to process
storeContext - the context under which the templates are stored
continueOnError - if true, errors are logged but not thrown so that as much processing as possible is done.
Throws:
IOException - if an IO error occurs
NoConvertersRunningException - if there are no converters running
ConversionException - if a template cannot be processed
ConverterPoolException - if the converter pool is not working
TemplateStoreException - if the underlying template store has an error

processResource

public void processResource(URL url)
                     throws IOException,
                            TemplateStoreException,
                            NoConvertersRunningException,
                            ConversionException
Process templates from the specified URL. This method is provided to allow templates to be loaded from Resources obtained from the classloader. It will process all templates found under the given resource location, including those in sub-folders and zip/jar archives. The hierarchy (folder-structure) of the resources will be preserved.

If an error is encountered, processing continues on a best effort by default (see documentation at the top of this class about error handling).

For example:

        URL myTemplates = getClass().getClassLoader().getResource("my/company/project/templates");
        new DropStoreHelper(mystore).processResource(myTemplates);
 

Parameters:
url - the URL to the
Throws:
TemplateStoreException - if there is a problem storing the template
IOException - if an IO error occurs
NoConvertersRunningException - if there are no converters running
ConversionException - if the template cannot be analyzed and stored

processResource

public void processResource(URL url,
                            TemplateContext baseContext,
                            boolean continueOnError)
                     throws IOException,
                            TemplateStoreException,
                            NoConvertersRunningException,
                            ConversionException
Process templates from the specified URL. This method is provided to allow templates to be loaded from Resources obtained from the classloader. It will process all templates found under the given resource location, including those in sub-folders and zip/jar archives. The hierarchy (folder-structure) of the resources will be preserved.

For example:

        URL myTemplates = getClass().getClassLoader().getResource("my/company/project/templates");
        new DropStoreHelper(mystore).processResource(myTemplates, null, false);
 

Parameters:
url - the URL to the
baseContext - an optional context under which to store these templates. null means store the templates starting in the root of the store.
continueOnError - if true errors will be logged and processing will do its best effort to process all templates found. If false, an exception will be thrown on first problem encountered.
Throws:
TemplateStoreException - if there is a problem storing the template
IOException - if an IO error occurs
NoConvertersRunningException - if there are no converters running
ConversionException - if the template cannot be analyzed and stored

validateTemplate

public static TemplateValidationResult validateTemplate(InputStream templateStream,
                                                        ExternalResourcePermissions externalResourcePermissions)
                                                 throws TemplateStoreException
Process the given stream as a template and return a TemplateValidationResult. The result will indicate if there are any errors, and if so, details about the error message and any suggested remedies are embodied in the result.

Parameters:
templateStream - a stream for the template to validate
Throws:
TemplateStoreException - if a problem occurs trying to validate
See Also:
TemplateValidationResult


Copyright © 2014–2023 Docmosis Pty Ltd. All rights reserved.