com.docmosis.template.store
Interface TemplateStore

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.

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

thumbnail - an image thumbnail for the template. This may be null and is expected to be constructed dynamically by some TemplateStore implementations.

overwrite - if true, any existing template will be overwritten.

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.