Docmosis API 4.5.0

com.docmosis.template.store
Interface TemplateStore

All Known Implementing Classes:
TemplateStoreFactory.PresetTemplateStore

public interface TemplateStore

This interface provides access to systems for storage and retrieval of templates. There is the concept of an original and a working template. The working template is derived from the original template to allow for performant populating. If the original template is acceptable for population processing, then no working template need be specified. Custom implementations of this interface need to note the following:

  1. When storing templates you need to store:
    1. the templateId should be treated as a unique key
    2. the original template stream needs to be stored (origTemplateSource)
    3. a derived version of the template needs to be stored (workingTemplateSource)
    4. an analysis object needs to be stored (analysis)
    5. a thumbnail needs to be stored
    6. a time-of-storage needs to be stored
  2. You should not implement any caching strategies, Docmosis does this itself.
  3. getTemplate() is the key performance-related method in typical use so this method should efficiently retrieve the template by templateId.
  4. To plug in your own implementation, set the property as follows:
     docmosis.template.store.location=custom:my.own.CustomTemplateStore
     or
     docmosis.template.store.location=custom:my.own.CustomTemplateStore:myParamValue
     
    The first setting will instantiate my.own.CustomTemplateStore by calling the no-argument constructor. The second setting will instantiate my.own.CustomTemplateStore by calling the constructor with a single String parameter and pass the "myParamValue" value in the parameter.


Method Summary
 void deleteAll()
          Delete all templates in the store.
 void deleteTemplate(TemplateIdentifier templateId)
          Delete the given template from the store.
 void deleteTemplates(TemplateContext context, boolean includeSubContexts)
          Delete all templates in the given context.
 TemplateDetails[] findByContext(TemplateContext templateContext, boolean includeSubContexts)
          Get the list of templates for the given context.
 InputStream getOriginalTemplate(TemplateIdentifier templateId)
          Get the original template provided in storeTemplate().
 Template getTemplate(TemplateIdentifier templateId)
          Get the (working) template identified by the given templateId.
 TemplateAnalysis getTemplateAnalysis(TemplateIdentifier templateId)
          Get the template analysis for the template identified by the given template info.
 long getTemplateStoredTime(TemplateIdentifier templateId)
          Return the time that the template was stored in this template store.
 TemplateDetails storeTemplate(TemplateIdentifier templateId, InputStream origTemplateSource, InputStream workingTemplateSource, TemplateAnalysis analysis, InputStream thumbnail, boolean overwrite, boolean templateErrorsFatal, String plainTextFieldPrefix, String plainTextFieldSuffix, boolean allowPaddedFields)
          Store the given InputStream as a template using the given templateId.
 

Method Detail

storeTemplate

public TemplateDetails storeTemplate(TemplateIdentifier templateId,
                                     InputStream origTemplateSource,
                                     InputStream workingTemplateSource,
                                     TemplateAnalysis analysis,
                                     InputStream thumbnail,
                                     boolean overwrite,
                                     boolean templateErrorsFatal,
                                     String plainTextFieldPrefix,
                                     String plainTextFieldSuffix,
                                     boolean allowPaddedFields)
                              throws IOException,
                                     TemplateAlreadyExistsException,
                                     TemplateStoreException
Store the given InputStream as a template using the given templateId.

Parameters:
templateId - the unique identification for this template.
origTemplateSource - an InputStream over the "original" template. This is the raw template as provided by whatever source (eg a user).
workingTemplateSource - an InputStream over a working template source. This is expected to be a converted form of the original template that is suitable for populating by a TemplatePopulator. Specify null if the origTemplateSource should be used as the working template. The working template is returned by getTemplate().
analysis - the analysis for the template. This may be null and is expected to be constructed dynamically by some TemplateStore implementations, so most implementations should simply store what is given.
thumbnail - an image thumbnail for the template. This may be null and is expected to be constructed dynamically by some TemplateStore implementations, so most implementations of this interface should simply store what is given.
overwrite - if true, any existing template will be overwritten.
templateErrorsFatal - if true, errors detected in the template will result in a TemplateStoreException. If false, errors will be highlighted in the template (where possible) and thus be visible when the document is rendered. Most implementations of this interface can ignore this parameter because it is used by the TemplateStore implementation that will provide the TemplateAnalysis.
plainTextFieldPrefix - if not null, specifies a prefix to use when analysing templates to identify Docmosis fields in plain text. Most implementations of this interface can ignore this parameter because it is used by the TemplateStore implementation that will provide the TemplateAnalysis.
plainTextFieldSuffix - this is the partner to plainTextFieldPrefix and identifies the end of the field. Most implementations of this interface can ignore this parameter because it is used by the TemplateStore implementation that will provide the TemplateAnalysis.
allowPaddedFields - when processing the template allow fields padded with spaces to be included as fields. Most implementations of this interface can ignore this parameter because it is used by the TemplateStore implementation that will provide the TemplateAnalysis.
Returns:
a new TemplateDetails object with information about the template
Throws:
IOException - if an error occurs storing the template
TemplateAlreadyExistsException - if the template is already present and overwrite is not true
TemplateStoreException - if any other unexpected error occurs.

getTemplate

public Template getTemplate(TemplateIdentifier templateId)
                     throws IOException,
                            TemplateNotFoundException,
                            TemplateStoreException
Get the (working) template identified by the given templateId. This method is intended to be used for obtaining the template for further processing/populating. NOTE: the template should be cleaned up (template.cleanup()) when finished so that InputStreams and other resources may be released.

Parameters:
templateId - the identifier for the template
Returns:
the template.
Throws:
IOException - if an error occurs obtaining the template
TemplateNotFoundException - if the specified template cannot be found
TemplateStoreException

findByContext

public TemplateDetails[] findByContext(TemplateContext templateContext,
                                       boolean includeSubContexts)
                                throws IOException,
                                       TemplateStoreException
Get the list of templates for the given context. The context may specify just the name or may further constrain the returned result by specifying more information.

Parameters:
templateContext - the context under which to find templates
includeSubContexts - if true, templates under subcontexts will be returned.
Returns:
an array of TemplateDetails objects or null if no templates are found
Throws:
IOException - if an error occurs obtaining the template
TemplateStoreException - if a problem occurs specific to the store

getOriginalTemplate

public InputStream getOriginalTemplate(TemplateIdentifier templateId)
                                throws IOException,
                                       TemplateNotFoundException
Get the original template provided in storeTemplate().

Parameters:
templateId - details of the template to retrieve.
Returns:
the original template provided by storeTemplate() or null if there is no template found.
Throws:
IOException - if an IO problem occurs.
TemplateNotFoundException - if the specified template is not found

getTemplateAnalysis

public TemplateAnalysis getTemplateAnalysis(TemplateIdentifier templateId)
                                     throws IOException,
                                            TemplateNotFoundException,
                                            TemplateStoreException
Get the template analysis for the template identified by the given template info.

Parameters:
templateId -
Returns:
null if the template is not found
Throws:
TemplateNotFoundException - if the template cannot be located
TemplateStoreException - if an error occurs retrieving the analysis
IOException - if an error occurs obtaining the analysis

deleteTemplate

public void deleteTemplate(TemplateIdentifier templateId)
                    throws TemplateStoreException
Delete the given template from the store. If the template does not exist, then no action is taken.

Parameters:
templateId - the identifier for the template
Throws:
TemplateStoreException - if the template could not be deleted.

deleteTemplates

public void deleteTemplates(TemplateContext context,
                            boolean includeSubContexts)
                     throws TemplateStoreException
Delete all templates in the given context. If the context does not exist then no action is taken.

Parameters:
context - the template context in which all templates are to be deleted
includeSubContexts - if true all templates in contexts under the given context will also be deleted.
Throws:
TemplateStoreException - if any of the templates could not be deleted

deleteAll

public void deleteAll()
               throws TemplateStoreException
Delete all templates in the store. If no templates exist, then no action is taken.

Throws:
TemplateStoreException - if any of the templates could not be deleted

getTemplateStoredTime

public long getTemplateStoredTime(TemplateIdentifier templateId)
                           throws TemplateStoreException
Return the time that the template was stored in this template store. The time is returned as a long (millis since the epoch) as standard.

Returns:
-1 if the template is not known.
Throws:
TemplateStoreException - if an error occurred while retrieving this information.

Docmosis API 4.5.0

Copyright © 2014 Docmosis Pty Ltd. All Rights Reserved.