public interface DocumentFactoryBuilder
Templater document factory builder.
Main point of configuration:
| Modifier and Type | Interface and Description |
|---|---|
static interface |
DocumentFactoryBuilder.Formatter
Plugin signature for formatting values.
|
static interface |
DocumentFactoryBuilder.Handler
Plugin signature for invoking low-level API.
|
static interface |
DocumentFactoryBuilder.LowLevelReplacer
Register a new Low Level replacer plugin.
|
static interface |
DocumentFactoryBuilder.Navigate
Plugin signature for navigation over tag.
|
static interface |
DocumentFactoryBuilder.NavigationEnd
Specify ending for navigation plugin.
|
static interface |
DocumentFactoryBuilder.Processor<T>
Plugin signature for a data type handler.
|
static class |
DocumentFactoryBuilder.RemovalOption
How to deal with tag detected in XML.
|
static interface |
DocumentFactoryBuilder.SpreadsheetConfigurationBuilder
This builder allows for customizing various Spreadsheet specific behaviors,
such as formulas and limits.
|
static interface |
DocumentFactoryBuilder.SvgConverter
Conversion function.
|
static class |
DocumentFactoryBuilder.TagPattern
Supported tag patterns
|
static interface |
DocumentFactoryBuilder.UnprocessedTagsHandler
Register a new unprocessed tags plugin.
|
static interface |
DocumentFactoryBuilder.XmlCombine
Conversion function.
|
| Modifier and Type | Method and Description |
|---|---|
DocumentFactoryBuilder |
blacklist(java.lang.reflect.Member member)
To disable navigation over certain members blacklisting can be used.
|
DocumentFactory |
build()
Build a document factory instance.
|
DocumentFactory |
build(java.lang.String path)
Build a document factory instance using the provided custom license file.
|
DocumentFactory |
build(java.lang.String customer,
java.lang.String license)
Build a document factory instance using the provided license information.
|
DocumentFactoryBuilder |
builtInFormatters(boolean include)
Templater has a lot of builtin formatters (such as format, substring, ...)
While they can be overridden, if there is no use for them,
they can be excluded from usage
|
DocumentFactoryBuilder |
builtInHandlers(boolean include)
Templater has few builtin handlers (such as collapse).
|
DocumentFactoryBuilder |
builtInLowLevelPlugins(boolean include)
Templater has few builtin low level plugins (such as
buffered image
and image stream on Java)
If those classes are not available (as in case of Android) plugins should be disabled. |
DocumentFactoryBuilder |
builtInNavigation(boolean include)
Templater has few builtin navigation (such as
at(index), ...)
If there is no use for them, they can be excluded from usage |
EditorConfigurationBuilder |
configureEditor()
Configure document settings which are used in Templater Editor Add-In for Microsoft Office.
|
DocumentFactoryBuilder.SpreadsheetConfigurationBuilder |
configureSpreadsheet()
Fine tune specific behavior of spreadsheet processing
|
<T> DocumentFactoryBuilder |
include(java.lang.Class<T> manifest,
DocumentFactoryBuilder.Processor<T> processor)
Register a new processor plugin.
|
DocumentFactoryBuilder |
include(DocumentFactoryBuilder.Formatter formatter)
Register a new formatter plugin.
|
DocumentFactoryBuilder |
include(DocumentFactoryBuilder.Handler handler)
Register a new metadata handler plugin.
|
DocumentFactoryBuilder |
include(DocumentFactoryBuilder.LowLevelReplacer replacer)
When input values must be replaced before and there is not
appropriate metadata.
|
DocumentFactoryBuilder |
include(DocumentFactoryBuilder.Navigate expression)
Register a new navigation plugin.
|
DocumentFactoryBuilder |
navigateSeparator(char character,
DocumentFactoryBuilder.NavigationEnd findEnding)
Change navigation separator.
|
DocumentFactoryBuilder |
navigateUsing(char character)
Change navigation character.
|
DocumentFactoryBuilder |
onUnprocessed(DocumentFactoryBuilder.UnprocessedTagsHandler handler)
Specify custom behavior for tags which were left after processing.
|
DocumentFactoryBuilder |
resizeLimit(int limit)
Maximum number of times same tag can be resized.
|
DocumentFactoryBuilder |
sign(java.security.cert.X509Certificate certificate,
java.security.PrivateKey privateKey)
Sign office document at the end of processing.
|
DocumentFactoryBuilder |
streaming(int size)
Configure the streaming size.
|
DocumentFactoryBuilder |
svgConverter(DocumentFactoryBuilder.SvgConverter converter)
When adding SVG into documents, use additional converter for fallback image.
|
DocumentFactoryBuilder |
typeVisibility(boolean onlyPublic)
During type analysis, analyze
all vs only public signatures. |
DocumentFactoryBuilder |
withJavaBeans(boolean useConvention)
During class analysis, bean convention can be used.
|
DocumentFactoryBuilder |
withMatcher(java.lang.String regex)
Customize tag matcher for all patterns.
|
DocumentFactoryBuilder |
withMatcher(java.lang.String regex,
DocumentFactoryBuilder.TagPattern pattern)
Customize tag matcher for a specific pattern.
|
DocumentFactoryBuilder |
xmlBuilder(javax.xml.parsers.DocumentBuilderFactory builder,
boolean isFullyConfigured)
Change default XML parser.
|
DocumentFactoryBuilder |
xmlCombine(java.lang.String metadata,
java.util.function.BiFunction<org.w3c.dom.Element,org.w3c.dom.Element[],org.w3c.dom.Element[]> combine)
Deprecated.
|
DocumentFactoryBuilder |
xmlCombine(java.lang.String metadata,
DocumentFactoryBuilder.RemovalOption tagRemoval,
DocumentFactoryBuilder.XmlCombine combine)
To fine tune behavior of xml injection into the document allow for inspection
of provided and existing XML and passing in a final XML.
|
DocumentFactoryBuilder |
xmlReader(javax.xml.stream.XMLInputFactory readerFactory,
boolean isFullyConfigured)
Change default XML reader.
|
DocumentFactoryBuilder |
xmlTransformer(javax.xml.transform.TransformerFactory transformer,
boolean isFullyConfigured)
Change default XML transformer.
|
DocumentFactoryBuilder |
xmlWriter(javax.xml.stream.XMLOutputFactory writerFactory,
boolean isFullyConfigured)
Change default XML writer.
|
DocumentFactoryBuilder include(DocumentFactoryBuilder.Navigate expression)
Register a new navigation plugin.
The plugin works by accepting an object value and current metadata and returns the same object if the plugin is not applicable or a new value if the plugin is applicable.
Metadata can be parsed to extract arguments from it.
expression - navigation pluginDocumentFactoryBuilder include(DocumentFactoryBuilder.Formatter formatter)
Register a new formatter plugin.
The plugin works by accepting an object value and current metadata and returns the same object if the plugin is not applicable or a new value if the plugin is applicable.
Metadata can be parsed to extract arguments from it.
builder.include((value, metadata) ->
"join".equals(metadata) && value instanceof String[]
? String.join(", ", (String[])value)
: value
)
formatter - formatting pluginDocumentFactoryBuilder include(DocumentFactoryBuilder.Handler handler)
Register a new metadata handler plugin.
Plugin works by accepting an object value, current metadata,
current property (path) and an Templater instance.
Returns instructions on how to continue with further processing.
Metadata can be parsed to extract arguments from it.
.include((value, metadata, tag, position, templater) -> {
if ("collapse".equals(metadata) && (value == null || value == "" || value instanceof Boolean && (Boolean)value)) {
boolean resized = position == -1
? templater.resize(new String[] { tag }, 0)
: templater.resize(new TagPosition[] { new TagPosition(tag, position) }, 0);
if (resized) return Handled.NESTED_TAGS;
}
return Handled.NOTHING;
})
handler - handler plugin<T> DocumentFactoryBuilder include(java.lang.Class<T> manifest, DocumentFactoryBuilder.Processor<T> processor)
Register a new processor plugin.
Plugin works by accepting the current navigation prefix,
the Templater instance and the current object value.
It should return false if it's not applicable or
true if it processed the current path.
T - type of object to processmanifest - supported classprocessor - processing pluginDocumentFactoryBuilder include(DocumentFactoryBuilder.LowLevelReplacer replacer)
When input values must be replaced before and there is not appropriate metadata.
Common case would be replacement from LocalDate -> Date,
BigDecimal -> localized number representation, etc...
replacer - custom code for low level replacementDocumentFactoryBuilder withMatcher(java.lang.String regex)
Customize tag matcher for all patterns. Default tag regex is [-+@\w\s.,!?/:()|]+
Full matcher consists from more elements, this is just the path of the tag.
regex - tag regexDocumentFactoryBuilder withMatcher(java.lang.String regex, DocumentFactoryBuilder.TagPattern pattern)
Customize tag matcher for a specific pattern. Default tag regex is [-+@\w\s.,!?/:()|]+
[[TAG]], {{TAG}} and <<TAG>> are enabled by default and use default tag regex.
Patterns can be disabled by using unmatchable regex for the specified pattern (such as [^\S\s]).
Different patterns can have different regexes.
Full matcher consists from more elements, this is just the path of the tag.
regex - tag regexpattern - tag patternDocumentFactoryBuilder resizeLimit(int limit)
Maximum number of times same tag can be resized. Default is 8.
To protect against badly designed documents where Templater resizes the wrong context, set this limit to the maximum expected nesting.
limit - maximum nesting levelDocumentFactoryBuilder onUnprocessed(DocumentFactoryBuilder.UnprocessedTagsHandler handler)
Specify custom behavior for tags which were left after processing.
By default [[tag]:unprocessed] will be left in the place of the tag.
Common customization would instead replace all such tags with an empty string and thus remove them from the document.
Alternative implementation could replace them with metadata value in the tag
handler - custom code to run after tags were left unprocessedDocumentFactoryBuilder builtInNavigation(boolean include)
at(index), ...)
If there is no use for them, they can be excluded from usageinclude - include all builtin navigationDocumentFactoryBuilder builtInFormatters(boolean include)
include - should Templater default formatters be active by defaultDocumentFactoryBuilder builtInHandlers(boolean include)
include - should Templater default handlers be active by defaultDocumentFactoryBuilder builtInLowLevelPlugins(boolean include)
buffered image
and image stream on Java)
If those classes are not available (as in case of Android) plugins should be disabled.include - should Templater include default low level pluginsDocumentFactoryBuilder withJavaBeans(boolean useConvention)
During class analysis, bean convention can be used.
By default bean convention is enabled, which means that properties such as getWidth
can be used in templates as width.
If bean convention is not enabled exact method name must be used.
useConvention - recognize tags through bean naming conventionDocumentFactoryBuilder typeVisibility(boolean onlyPublic)
During type analysis, analyze all vs only public signatures.
By default this value is false as private classes can be passed into processing. Since this does create some problems (it will be prevented in future Java version - and requires access visibility changes which can affect performance), this can be disabled.
If non public class has public base class or interface(s), their properties will be considered for usage
This value will be changed to false in future version.
onlyPublic - will consider only public signaturesDocumentFactoryBuilder xmlBuilder(javax.xml.parsers.DocumentBuilderFactory builder, boolean isFullyConfigured) throws javax.xml.parsers.ParserConfigurationException
Change default XML parser.
By default Templater will use Java default document factory if it's available on classpath,
otherwise it will use new instance
which might use unwanted builder due to dependencies on the classpath.
Since Java 11 does not allow specifying internal classes anymore
this method is used to explicitly set the builder to use.
document factory can be passed in fully configured (in which case isFullyConfigured should be set to true)
or just a new default instance created via new instance or similar means in which case
passing in isFullyConfigured as false will perform additional setup on the builder factory.
On some systems additional configuration will throw exceptions due to missing features in which case
document factory should be fully configured and passed in with appropriate flag set to true
builder - specific XML builder to useisFullyConfigured - configure builder to avoid common problems (disable external validations, protect against XXE, ...)javax.xml.parsers.ParserConfigurationException - unable to setup provided builder with expected optionsDocumentFactoryBuilder xmlTransformer(javax.xml.transform.TransformerFactory transformer, boolean isFullyConfigured) throws javax.xml.transform.TransformerConfigurationException
Change default XML transformer.
By default Templater will use Java default transformer factory if it's available on classpath,
otherwise it will use new instance
which might use unwanted transformer due to dependencies on the classpath.
Since Java 11 does not allow specifying internal classes anymore
this method is used to explicitly set the transformer to use.
transformer factory can be passed in fully configured (in which case performAdditionalConfiguration should be set to false)
or just a new default instance created via new instance or similar means.
On some systems additional configuration will throw exceptions due to missing features in which case
transformer factory should be fully configured and passed in with appropriate flag set to true
transformer - specific XML transformer to useisFullyConfigured - configure builder to avoid common problems (disable external validations, ...)javax.xml.transform.TransformerConfigurationException - unable to configure transformer with expected optionsDocumentFactoryBuilder xmlReader(javax.xml.stream.XMLInputFactory readerFactory, boolean isFullyConfigured)
Change default XML reader.
By default Templater will use XMLInputFactory.newInstance() new instance for XML reader.
When custom reader needs to be use, factory can be specified via this configuration.
input factory can be passed in fully configured (in which case performAdditionalConfiguration should be set to false)
or just a new default instance created via new instance or similar means.
On some systems additional configuration will throw exceptions due to missing features in which case
input factory should be fully configured and passed in with appropriate flag set to true
readerFactory - custom reader factoryisFullyConfigured - configure reader to avoid common problems (disable external validations, ...)DocumentFactoryBuilder xmlWriter(javax.xml.stream.XMLOutputFactory writerFactory, boolean isFullyConfigured)
Change default XML writer.
By default Templater will use XMLOutputFactory.newFactory() new instance for XML writer.
When custom writer needs to be use, factory can be specified via this configuration.
output factory can be passed in fully configured (in which case performAdditionalConfiguration should be set to false)
or just a new default instance created via new instance or similar means.
On some systems additional configuration will throw exceptions due to missing features in which case
output factory should be fully configured and passed in with appropriate flag set to true
writerFactory - custom writer factoryisFullyConfigured - configure writer to avoid common problemsDocumentFactoryBuilder streaming(int size)
Configure the streaming size. Default is 16384.
When Iterator or Enumeration is used, it's processed by streaming algorithm.
Instead of loading all data into memory it's processed in chunk of streaming size.
If format supports flushing, it's flushed after specified size is reached.
To disable streaming use 0
size - streaming chunk sizeDocumentFactoryBuilder blacklist(java.lang.reflect.Member member)
getClass.getProtectionDomain.getCodeSource.getLocation it's often useful to disable their evaluation.member - field or method for which the navigation is disabledDocumentFactoryBuilder svgConverter(DocumentFactoryBuilder.SvgConverter converter)
When adding SVG into documents, use additional converter for fallback image. SVG can be displayed in new applications without converted image, but some applications support only fallback image.
By default SVG converter is not registered which means Templater will only insert SVG image into target document.
Passing null means no SVG converter is used (which is the default behavior) Returning null from the conversion will result in no fallback image.
converter - svg to image converterDocumentFactoryBuilder xmlCombine(java.lang.String metadata, DocumentFactoryBuilder.RemovalOption tagRemoval, DocumentFactoryBuilder.XmlCombine combine)
To fine tune behavior of xml injection into the document allow for inspection of provided and existing XML and passing in a final XML.
When built in plugins such as xml-replace or xml-merge are not sufficient, a new plugin can be registered to fine tune the expected behavior.
Provided function will receive XML location where operation will be performed along with the provided array of XML passed to Templater. It should return XML array as it wants that XML location to be replaced with.
This behavior will be triggered either on XML templater-xml=METADATA value or on standard [[tag]:METADATA] tag definition.
If resulting array contains provided location, that XML instance will be preserved but content will be adjusted to matched newly provided XML. XML elements before the location will be injected before in output document, while XML elements after the location will be added after. If resulting XML does not contain location, XML elements will be added after location and location will be removed from the output document.
There are 3 main option to deal with tag removal. The most common one is remove tags before calling the plugin in which case tagRemoval=RemovalOption.BEFORE. In cases when we are interested in finding out order of the tags within the XML but don't want to deal with actual XML mutation to remove the tag tagRemoval=RemovalOption.AFTER will take care of removing the specific tag. If full management of tags is required, tagRemoval=RemovalOption.MANUAL in which case plugin should take special care of XML and tags inside as Templater will not try to remove specific tags after processing.
metadata - the keyword which triggers this operationtagRemoval - should tag be removed by Templater or plugincombine - function to perform XML combination@Deprecated DocumentFactoryBuilder xmlCombine(java.lang.String metadata, java.util.function.BiFunction<org.w3c.dom.Element,org.w3c.dom.Element[],org.w3c.dom.Element[]> combine)
metadata - the keyword which triggers this operationcombine - function to perform XML combinationDocumentFactoryBuilder navigateUsing(char character)
Change navigation character. Default navigation character is . (DOT)
To make navigation more familiar in some cases it is possible to change navigation character into more appropriate one, e.g.: / (SLASH)
Character must be included in tag regular expression, which can be customized if required.
character - custom navigation characterDocumentFactoryBuilder navigateSeparator(char character, DocumentFactoryBuilder.NavigationEnd findEnding)
Change navigation separator. By default this is disabled.
To support metadata during navigation,
custom expression can be used which will invoke metadata at appropriate place.
An example would be usage of built in at(index) metadata which can be enabled via : (SEMICOLON)
[[collection:at(2).name]] would provide third element of the collection without expanding the collection.
Character must be included in tag regular expression, which can be customized if required.
If findEnding parameter is not provided, Templater will assume parsing until closing parenthesis followed by separator or navigation char.
character - custom navigation separatorfindEnding - find navigation endingDocumentFactoryBuilder.SpreadsheetConfigurationBuilder configureSpreadsheet()
EditorConfigurationBuilder configureEditor()
Configure document settings which are used in Templater Editor Add-In for Microsoft Office.
Instead of normal processing, schema can be embedded into OOXML documents which will make document easier to manage from Microsoft Office.
Processing debug log can be embedded into OOXML documents which will allow to inspect how document looked at each step of processing.
This feature is not available in SOLO developer license.
DocumentFactoryBuilder sign(java.security.cert.X509Certificate certificate, java.security.PrivateKey privateKey) throws java.security.cert.CertificateException
Sign office document at the end of processing.
To prevent further changes to the document allow signing it with a certificate. This will make document final. If any changes are made to the document signature validation will fail and user will know that the document was changed after the signing.
This feature is not available in SOLO developer license.
certificate - signing certificateprivateKey - certificate private keyjava.security.cert.CertificateException - unable to use provided certificate for signingDocumentFactory build()
Build a document factory instance.
License will be checked from "templater.lic" file in the
working directory or the root path in resources.
Resource will be checked using the current thread class loader.
If a license is not found, Templater will run in an unlicensed mode.
To force exception if a license is missing, use
configure("templater.lic") instead.
DocumentFactory build(java.lang.String path)
Build a document factory instance using the provided custom license file.
The specified path will be tested by checking for that path in the working directory. If the path does not exist, a resource lookup will occur via the current thread class loader.
When loading from a resource, the class loader requires an absolute path
(e.g. "org/example/templater.lic")
path - path to license file or resourceDocumentFactory build(java.lang.String customer, java.lang.String license)
customer - license ownerlicense - license key