Class BaseRendererBuilder<TFinalClass extends BaseRendererBuilder,TBaseRendererBuilderState extends BaseRendererBuilder.BaseRendererBuilderState>
- java.lang.Object
-
- com.openhtmltopdf.outputdevice.helper.BaseRendererBuilder<TFinalClass,TBaseRendererBuilderState>
-
- Direct Known Subclasses:
Java2DRendererBuilder
,PdfRendererBuilder
public abstract class BaseRendererBuilder<TFinalClass extends BaseRendererBuilder,TBaseRendererBuilderState extends BaseRendererBuilder.BaseRendererBuilderState> extends java.lang.Object
Baseclass for all RendererBuilders (PDF and Java2D), has all common settings
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
BaseRendererBuilder.BaseRendererBuilderState
This class is an internal implementation detail.
This is internal, please don't use directly.static class
BaseRendererBuilder.FontStyle
static class
BaseRendererBuilder.FSFontUseCase
Use cases for fonts.static class
BaseRendererBuilder.PageSizeUnits
static class
BaseRendererBuilder.TextDirection
-
Field Summary
Fields Modifier and Type Field Description static float
PAGE_SIZE_LETTER_HEIGHT
static BaseRendererBuilder.PageSizeUnits
PAGE_SIZE_LETTER_UNITS
static float
PAGE_SIZE_LETTER_WIDTH
protected TBaseRendererBuilderState
state
-
Constructor Summary
Constructors Modifier Constructor Description protected
BaseRendererBuilder(TBaseRendererBuilderState state)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description TFinalClass
addDOMMutator(FSDOMMutator domMutator)
Add a DOM mutator to this builder.protected java.io.Closeable
applyDiagnosticConsumer()
TFinalClass
defaultTextDirection(BaseRendererBuilder.TextDirection textDirection)
The default text direction of the document.TFinalClass
testMode(boolean mode)
Whether to use test mode and output the PDF uncompressed.TFinalClass
useDefaultPageSize(float pageWidth, float pageHeight, BaseRendererBuilder.PageSizeUnits units)
Specifies the default page size to use if none is specified in CSS.TFinalClass
useDocumentBuilderFactoryImplementationClass(java.lang.String documentBuilderFactoryClass)
This method should be considered advanced and is not required for most setups.TFinalClass
useExternalResourceAccessControl(java.util.function.BiPredicate<java.lang.String,ExternalResourceType> allowExternalResource, ExternalResourceControlPriority priority)
Allows to set one external access controller to run before the uri resolver and one to run after the uri resolver.TFinalClass
useFastMode()
Use the new (May 2018) fast renderer.TFinalClass
useFont(FSSupplier<java.io.InputStream> supplier, java.lang.String fontFamily)
Simpler overload foruseFont(FSSupplier, String, Integer, FontStyle, boolean)
TFinalClass
useFont(FSSupplier<java.io.InputStream> supplier, java.lang.String fontFamily, java.lang.Integer fontWeight, BaseRendererBuilder.FontStyle fontStyle, boolean subset)
Add a font programmatically.TFinalClass
useFont(FSSupplier<java.io.InputStream> supplier, java.lang.String fontFamily, java.lang.Integer fontWeight, BaseRendererBuilder.FontStyle fontStyle, boolean subset, java.util.Set<BaseRendererBuilder.FSFontUseCase> useFontFlags)
Add a font programmatically.TFinalClass
useFont(java.io.File fontFile, java.lang.String fontFamily)
Simpler overload foruseFont(File, String, Integer, FontStyle, boolean)
TFinalClass
useFont(java.io.File fontFile, java.lang.String fontFamily, java.lang.Integer fontWeight, BaseRendererBuilder.FontStyle fontStyle, boolean subset)
Allows the user to provide a font file for use by the main document only (not SVGs).TFinalClass
useFont(java.io.File fontFile, java.lang.String fontFamily, java.lang.Integer fontWeight, BaseRendererBuilder.FontStyle fontStyle, boolean subset, java.util.Set<BaseRendererBuilder.FSFontUseCase> fontUsedFor)
Allows the user to provide a font file for use any or all of the use cases listed inBaseRendererBuilder.FSFontUseCase
such as main document, SVGs, etc.TFinalClass
useHttpStreamImplementation(FSStreamFactory factory)
Provides an HttpStreamFactory implementation if the user desires to use an external HTTP/HTTPS implementation.TFinalClass
useInitialPageNumber(int initialPageNumber)
Allows the setting of the initial page number to use with thepage
andpages
CSS counters.TFinalClass
useMathMLDrawer(SVGDrawer mathMlImpl)
Use the specified MathML implementation.TFinalClass
useObjectDrawerFactory(FSObjectDrawerFactory objectDrawerFactory)
Set a factory for <object> drawersTFinalClass
useProtocolsStreamImplementation(FSStreamFactory factory, java.lang.String... protocols)
Provides anFSStreamFactory
implementation if the user desires to use an external stream provider for a particular list of protocols.TFinalClass
useProtocolsStreamImplementation(FSStreamFactory factory, java.util.Set<java.lang.String> protocols)
Provides anFSStreamFactory
implementation if the user desires to use an external stream provider for a particular set of protocols.TFinalClass
useReplacementText(java.lang.String replacement)
The replacement text to use if a character is cannot be renderered by any of the specified fonts.TFinalClass
useSVGDrawer(SVGDrawer svgImpl)
Uses the specified SVG drawer implementation.TFinalClass
useTransformerFactoryImplementationClass(java.lang.String transformerFactoryClass)
This method should be considered advanced and is not required for most setups.TFinalClass
useUnicodeBidiReorderer(BidiReorderer reorderer)
Provides a reorderer to properly reverse RTL text.TFinalClass
useUnicodeBidiSplitter(BidiSplitterFactory splitter)
Provides a text splitter to split text into directional runs.TFinalClass
useUnicodeCharacterBreaker(FSTextBreaker breaker)
Specify the character breaker.TFinalClass
useUnicodeLineBreaker(FSTextBreaker breaker)
Specify the line breaker.TFinalClass
useUnicodeToLowerTransformer(FSTextTransformer tr)
Specify a transformer to use to lower case strings.TFinalClass
useUnicodeToTitleTransformer(FSTextTransformer tr)
Specify a transformer to title case strings.TFinalClass
useUnicodeToUpperTransformer(FSTextTransformer tr)
Specify a transformer to use to upper case strings.TFinalClass
useUriResolver(FSUriResolver resolver)
Provides a uri resolver to resolve relative uris or private uri schemes.TFinalClass
withDiagnosticConsumer(java.util.function.Consumer<Diagnostic> diagnosticConsumer)
TFinalClass
withFile(java.io.File file)
Provides a file to convert to PDF.TFinalClass
withHtmlContent(java.lang.String html, java.lang.String baseDocumentUri)
Provides a string containing XHTML/XML to convert to PDF.TFinalClass
withUri(java.lang.String uri)
Provides a URI to convert to PDF.TFinalClass
withW3cDocument(org.w3c.dom.Document doc, java.lang.String baseUri)
Provides a w3c DOM Document acquired from an external source.
-
-
-
Field Detail
-
PAGE_SIZE_LETTER_WIDTH
public static final float PAGE_SIZE_LETTER_WIDTH
- See Also:
- Constant Field Values
-
PAGE_SIZE_LETTER_HEIGHT
public static final float PAGE_SIZE_LETTER_HEIGHT
- See Also:
- Constant Field Values
-
PAGE_SIZE_LETTER_UNITS
public static final BaseRendererBuilder.PageSizeUnits PAGE_SIZE_LETTER_UNITS
-
state
protected final TBaseRendererBuilderState extends BaseRendererBuilder.BaseRendererBuilderState state
-
-
Constructor Detail
-
BaseRendererBuilder
protected BaseRendererBuilder(TBaseRendererBuilderState state)
-
-
Method Detail
-
addDOMMutator
public TFinalClass addDOMMutator(FSDOMMutator domMutator)
Add a DOM mutator to this builder. DOM mutators allow to modify the DOM before it is rendered. e.g. LaTeXDOMMutator can be used to translate latex text within a <latex> node to HTMl and MathML.- Parameters:
domMutator
- the DOM Mutator- Returns:
- this for method chaining
-
useTransformerFactoryImplementationClass
public final TFinalClass useTransformerFactoryImplementationClass(java.lang.String transformerFactoryClass)
This method should be considered advanced and is not required for most setups. Set a preferred implementation class for use as javax.xml.transform.TransformerFactory. Use null to let a default implementation class be used. The default is "com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl". This seems to work with most systems but not JBoss Wildfly and related setups. In this case you can use null to let the container use whatever TransformerFactory it has available.- Parameters:
transformerFactoryClass
-- Returns:
- this for method chaining
-
useDocumentBuilderFactoryImplementationClass
public final TFinalClass useDocumentBuilderFactoryImplementationClass(java.lang.String documentBuilderFactoryClass)
This method should be considered advanced and is not required for most setups. Set a preferred implementation class for use as javax.xml.parsers.DocumentBuilderFactory. Use null to let a default implementation class be used. The default is "com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl". If the default does not work you can use null to let the container use whatever DocumentBuilderFactory it has available.- Parameters:
documentBuilderFactoryClass
-- Returns:
- this for method chaining
-
defaultTextDirection
public final TFinalClass defaultTextDirection(BaseRendererBuilder.TextDirection textDirection)
The default text direction of the document. LTR by default.- Parameters:
textDirection
-- Returns:
- this for method chaining
-
testMode
public final TFinalClass testMode(boolean mode)
Whether to use test mode and output the PDF uncompressed. Turned off by default.- Parameters:
mode
-- Returns:
- this for method chaining
-
useHttpStreamImplementation
public final TFinalClass useHttpStreamImplementation(FSStreamFactory factory)
Provides an HttpStreamFactory implementation if the user desires to use an external HTTP/HTTPS implementation. Uses URL::openStream by default.- Parameters:
factory
- the factory to use for HTTP/HTTPS- Returns:
- this for method chaining
- See Also:
useProtocolsStreamImplementation(FSStreamFactory, String[])
-
useProtocolsStreamImplementation
public final TFinalClass useProtocolsStreamImplementation(FSStreamFactory factory, java.util.Set<java.lang.String> protocols)
Provides anFSStreamFactory
implementation if the user desires to use an external stream provider for a particular set of protocols. Protocols should always be in lower case. NOTE: HttpStreamFactory, despite its historical name, can be used for any protocol including private made-up protocols.- Parameters:
factory
- the stream factory to useprotocols
- the list of protocols the factory should be used for- Returns:
- this for method chaining
- See Also:
useHttpStreamImplementation(FSStreamFactory)
,useProtocolsStreamImplementation(FSStreamFactory, String[])
-
useProtocolsStreamImplementation
public final TFinalClass useProtocolsStreamImplementation(FSStreamFactory factory, java.lang.String... protocols)
Provides anFSStreamFactory
implementation if the user desires to use an external stream provider for a particular list of protocols. Protocols should always be in lower case. NOTE: HttpStreamFactory, despite its historical name, can be used for any protocol including private made-up protocols.- Parameters:
factory
- the stream factory to useprotocols
- the list of protocols the stream factory should be used for- Returns:
- this for method chaining
- See Also:
useHttpStreamImplementation(FSStreamFactory)
,useProtocolsStreamImplementation(FSStreamFactory, Set)
-
useUriResolver
public final TFinalClass useUriResolver(FSUriResolver resolver)
Provides a uri resolver to resolve relative uris or private uri schemes.- Parameters:
resolver
- the URI resolver used to resolve any kind of private URIs/protocolls- Returns:
- this for method chaining
-
useUnicodeBidiSplitter
public final TFinalClass useUnicodeBidiSplitter(BidiSplitterFactory splitter)
Provides a text splitter to split text into directional runs. Does nothing by default.- Parameters:
splitter
- the unicode bidi splitter to use.- Returns:
- this for method chaining
-
useUnicodeBidiReorderer
public final TFinalClass useUnicodeBidiReorderer(BidiReorderer reorderer)
Provides a reorderer to properly reverse RTL text. No-op by default.- Parameters:
reorderer
- the unicode bidi reorderer to use.- Returns:
- this for method chaining
-
withHtmlContent
public final TFinalClass withHtmlContent(java.lang.String html, java.lang.String baseDocumentUri)
Provides a string containing XHTML/XML to convert to PDF. Note that baseDocumentUri can be null if there are no relative resources, otherwise should be a uri to a (possibly fake) document that is used to resolve relative resources. Examples:file:///Users/user/my-dummy-doc.html
,file:/C:/Users/me/Desktop/dummy.html
- Parameters:
html
- the HTML text to use.baseDocumentUri
- the base document URI to resolve future relative resources (e.g. images)- Returns:
- this for method chaining
-
withW3cDocument
public final TFinalClass withW3cDocument(org.w3c.dom.Document doc, java.lang.String baseUri)
Provides a w3c DOM Document acquired from an external source.- Parameters:
doc
- the DOM of the HTML documentbaseUri
- the base URI, it will be used to resolve future resources (images, etc.- Returns:
- this for method chaining
-
withUri
public final TFinalClass withUri(java.lang.String uri)
Provides a URI to convert to PDF. The URI MUST point to a strict XHTML/XML document.- Parameters:
uri
- the URI of the HTML source to convert.- Returns:
- this for method chaining
-
withFile
public final TFinalClass withFile(java.io.File file)
Provides a file to convert to PDF. The file MUST contain XHTML/XML in UTF-8 encoding.- Parameters:
file
- the file with the HTML source to convert- Returns:
- this for method chaining
-
useSVGDrawer
public final TFinalClass useSVGDrawer(SVGDrawer svgImpl)
Uses the specified SVG drawer implementation. NOTE: This implementation is used for both inline SVG markup and SVG markup in external files included via theimg
tag. Please be very careful if using an insecureSVGDrawer
that all SVG images are trusted.- Parameters:
svgImpl
- the SVG implementation- Returns:
- this for method chaining
-
useMathMLDrawer
public final TFinalClass useMathMLDrawer(SVGDrawer mathMlImpl)
Use the specified MathML implementation.- Parameters:
mathMlImpl
- the MathML implementation- Returns:
- this for method chaining
-
useReplacementText
public final TFinalClass useReplacementText(java.lang.String replacement)
The replacement text to use if a character is cannot be renderered by any of the specified fonts. This is not broken across lines so should be one or zero characters for best results. Also, make sure it can be rendered by at least one of your specified fonts! The default is the # character.- Parameters:
replacement
- the default replacement text- Returns:
- this for method chaining
-
useUnicodeLineBreaker
public final TFinalClass useUnicodeLineBreaker(FSTextBreaker breaker)
Specify the line breaker. By default a Java default BreakIterator line instance is used with US locale. Additionally, this is wrapped with UrlAwareLineBreakIterator to also break before the forward slash (/) character so that long URIs can be broken on to multiple lines. You may want to use a BreakIterator with a different locale (wrapped by UrlAwareLineBreakIterator or not) or a more advanced BreakIterator from icu4j (see the rtl-support module for an example).- Parameters:
breaker
- the text breaker to use- Returns:
- this for method chaining
-
useUnicodeCharacterBreaker
public final TFinalClass useUnicodeCharacterBreaker(FSTextBreaker breaker)
Specify the character breaker. By default a break iterator character instance is used with US locale. Currently this is used whenword-wrap: break-word
is in effect.- Parameters:
breaker
- the character breaker to use- Returns:
- this for method chaining
-
useUnicodeToUpperTransformer
public final TFinalClass useUnicodeToUpperTransformer(FSTextTransformer tr)
Specify a transformer to use to upper case strings. By defaultString::toUpperCase(Locale.US)
is used.- Parameters:
tr
- the text transformer to use- Returns:
- this for method chaining
-
useUnicodeToLowerTransformer
public final TFinalClass useUnicodeToLowerTransformer(FSTextTransformer tr)
Specify a transformer to use to lower case strings. By defaultString::toLowerCase(Locale.US)
is used.- Parameters:
tr
- the text transformer to use.- Returns:
- this for method chaining
-
useUnicodeToTitleTransformer
public final TFinalClass useUnicodeToTitleTransformer(FSTextTransformer tr)
Specify a transformer to title case strings. By default a best effort implementation (non locale aware) is used.- Parameters:
tr
- the text transformer to use- Returns:
- this for method chaining
-
useDefaultPageSize
public final TFinalClass useDefaultPageSize(float pageWidth, float pageHeight, BaseRendererBuilder.PageSizeUnits units)
Specifies the default page size to use if none is specified in CSS.- Parameters:
pageWidth
- the new default widthpageHeight
- the new default heightunits
- either mm or inches.- Returns:
- this for method chaining
- See Also:
PAGE_SIZE_LETTER_WIDTH
,PAGE_SIZE_LETTER_HEIGHT
,PAGE_SIZE_LETTER_UNITS
-
useObjectDrawerFactory
public final TFinalClass useObjectDrawerFactory(FSObjectDrawerFactory objectDrawerFactory)
Set a factory for <object> drawers- Parameters:
objectDrawerFactory
- Object Drawer Factory- Returns:
- this for method chaining
-
useFastMode
public final TFinalClass useFastMode()
Use the new (May 2018) fast renderer. This renderer can be 100s of times faster for very large documents. Please note that the fast renderer will be the only renderer at some future release so please at least test your code using the fast mode. Note: As of version 1.0.5 the fast renderer will be the default and this method is not required. To temporarily use the slow renderer (now only available for PDFs) calluseSlowMode
.- Returns:
- this for method chaining
-
useFont
public TFinalClass useFont(java.io.File fontFile, java.lang.String fontFamily, java.lang.Integer fontWeight, BaseRendererBuilder.FontStyle fontStyle, boolean subset)
Allows the user to provide a font file for use by the main document only (not SVGs). See:
useFont(File, String, Integer, FontStyle, boolean, Set)
For gotchas related to font handling please see: Wiki: Fonts
-
useFont
public TFinalClass useFont(java.io.File fontFile, java.lang.String fontFamily, java.lang.Integer fontWeight, BaseRendererBuilder.FontStyle fontStyle, boolean subset, java.util.Set<BaseRendererBuilder.FSFontUseCase> fontUsedFor)
Allows the user to provide a font file for use any or all of the use cases listed in
BaseRendererBuilder.FSFontUseCase
such as main document, SVGs, etc.For gotchas related to font handling please see: Wiki: Fonts
- Parameters:
fontFile
- A file system font file in true-type format. Beware of using resources as they will not be separate files in the final jar.fontFamily
- Font family name. If using a font in Java2D, SVG or MathML this should matchFont.createFont(Font.TRUETYPE_FONT, fontFile).getFamily()
.fontWeight
- Font boldness, usually 400 for regular fonts and 700 for bold fonts.fontStyle
- Normal, italic or oblique.subset
- For PDF use whether the font is subset, usually true unless the font is being used by form controls.fontUsedFor
- Which components use the font such as main document, SVG, etc. Example:EnumSet.of(FSFontUseCase.DOCUMENT, FSFontUseCase.SVG)
- Returns:
- this for method chaining
-
useFont
public TFinalClass useFont(java.io.File fontFile, java.lang.String fontFamily)
Simpler overload foruseFont(File, String, Integer, FontStyle, boolean)
- Returns:
- this for method chaining
-
useFont
public TFinalClass useFont(FSSupplier<java.io.InputStream> supplier, java.lang.String fontFamily, java.lang.Integer fontWeight, BaseRendererBuilder.FontStyle fontStyle, boolean subset)
Add a font programmatically. If the font is NOT subset, it will be downloaded when the renderer is run, otherwise, assuming a font-metrics cache has been configured, the font will only be downloaded if required. Therefore, the user could add many fonts, confident that only those that are needed will be downloaded and processed.
The InputStream returned by the supplier will be closed by the caller. Fonts should generally be subset (Java2D renderer ignores this argument), except when used in form controls. FSSupplier is a lambda compatible interface.
Fonts can also be added using a font-face at-rule in the CSS (not recommended for Java2D usage).
IMPORTANT: This method will add fonts for use by the main document only. It is not recommended for use with Java2D. To add fonts for use by Java2D, SVG, etc see:
useFont(File, String, Integer, FontStyle, boolean, Set)
For gotchas related to font handling please see: Wiki: Fonts
- Returns:
- this for method chaining
-
useFont
public TFinalClass useFont(FSSupplier<java.io.InputStream> supplier, java.lang.String fontFamily, java.lang.Integer fontWeight, BaseRendererBuilder.FontStyle fontStyle, boolean subset, java.util.Set<BaseRendererBuilder.FSFontUseCase> useFontFlags)
Add a font programmatically. If the font is NOT subset, it will be downloaded when the renderer is run, otherwise, assuming a font-metrics cache has been configured, the font will only be downloaded if required. Therefore, the user could add many fonts, confident that only those that are needed will be downloaded and processed.
The InputStream returned by the supplier will be closed by the caller. Fonts should generally be subset (Java2D renderer ignores this argument), except when used in form controls. FSSupplier is a lambda compatible interface.
Fonts can also be added using a font-face at-rule in the CSS (not recommended for Java2D usage).
IMPORTANT: This method is not recommended for use with Java2D. To add fonts for use by Java2D, SVG, etc see:
useFont(File, String, Integer, FontStyle, boolean, Set)
For gotchas related to font handling please see: Wiki: Fonts
- Returns:
- this for method chaining
-
useFont
public TFinalClass useFont(FSSupplier<java.io.InputStream> supplier, java.lang.String fontFamily)
Simpler overload foruseFont(FSSupplier, String, Integer, FontStyle, boolean)
- Returns:
- this for method chaining
-
withDiagnosticConsumer
public TFinalClass withDiagnosticConsumer(java.util.function.Consumer<Diagnostic> diagnosticConsumer)
-
applyDiagnosticConsumer
protected java.io.Closeable applyDiagnosticConsumer()
-
useExternalResourceAccessControl
public TFinalClass useExternalResourceAccessControl(java.util.function.BiPredicate<java.lang.String,ExternalResourceType> allowExternalResource, ExternalResourceControlPriority priority)
Allows to set one external access controller to run before the uri resolver and one to run after the uri resolver. The predicate will receive the uri and the resource type. If it returns false, the resource will not be loaded but the rendering process will attempt to continue without the resource. A default controller is registered that allows everything except file embed resources. To override the default controller, register a controller with after priority.
-
useInitialPageNumber
public TFinalClass useInitialPageNumber(int initialPageNumber)
Allows the setting of the initial page number to use with thepage
andpages
CSS counters. Useful when appending to an existing document. Must be one or greater.- Returns:
- this for method chaining.
-
-