Package com.pd4ml

Class PD4ML


  • public class PD4ML
    extends java.lang.Object
    • Constructor Summary

      Constructors 
      Constructor Description
      PD4ML()
      PD4ML Constructor Creates and initializes an instance of the converter
      PD4ML​(int loglevel)
      PD4ML Constructor Creates and initializes an instance of the converter
      PD4ML​(java.lang.String license)
      PD4ML Constructor Creates and initializes an instance of the converter
      PD4ML​(java.lang.String license, int loglevel)
      PD4ML Constructor Creates and initializes an instance of the converter
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addCustomResourceProvider​(java.lang.String customProviderClassName)
      add custom resource loader for non-standard or customized transport protocols
      void addCustomTagHandler​(java.lang.String customTagName, CustomTag implementation)
      adds a proprietary HTML tag implementation
      void addDocumentActionHandler​(java.lang.String actionType, java.lang.String javaScript)
      method defines JavaScript action handler for generated document.
      void addMetadata​(java.lang.String key, java.lang.String value, boolean hide)
      The method defines custom properties for PDF document meta data.
      void addStyle​(java.lang.String stylesheet, boolean overrideDocumentStyles)
      Apply additional stylesheet to the document
      void addStyle​(java.net.URL stylesheet, boolean overrideDocumentStyles)
      Apply additional stylesheet to the document
      void adjustHtmlWidth​(boolean adjust)
      sets htmlWidth to the most right margin of the HTML block content.
      void applyKerning​(boolean enable)
      Forces PD4ML to align font glyphs to each other according to the font kerning hints (if available).
      boolean applyLicense​(java.lang.String license)
      applies license code.
      void asyncResourceLoader​(int threadPoolSize)
      enables asynchronous resource loading (graphics, attachments etc) if thread pool size is not equal 0.
      java.lang.String dump​(int mode)
      debug/diagnostics method
      void embedTTFs​(boolean embed, boolean allGlyphs)  
      void enableHyperlinks​(boolean enable)
      enables converting of HTML to PDF hyperlinks.
      void enableLigatures​(boolean enable)
      Forces PD4ML to load TTF/OTF glyph susbstitution tables, to apply ligature replacements and to build compound glyphs.
      void fitPageVertically​(int align)
      forces PD4ML to downscale entire HTML layout to fit a single PDF page vertically.
      void generateBookmarksFromAnchors​(boolean enable)  
      void generateBookmarksFromHeadings​(boolean enable)  
      void generateForms​(boolean enable, java.lang.String useTtfFont)
      forces PD4ML to convert HTML forms into PDF forms (Acroforms).
      void generateForms​(boolean enable, java.lang.String useTtfFont, java.lang.String formFontCharRange)
      forces PD4ML to convert HTML forms into PDF forms (Acroforms).
      void generateMulticolumn​(int columns, int span, boolean millimeters)
      switches PD4ML into multicolumn mode.
      java.lang.Object getCache()  
      java.lang.String getDocumentTitle()  
      short getFitPageVertically()  
      int getHeight​(int width)
      calculates document height for given document width.
      java.lang.Object getLastRenderInfo​(java.lang.String key)
      returns statistics for the last render() call
      PageMargins getPageMargins​(int pageNum, boolean imageGeneration)
      Returns page margins object for a specified page number.
      PageSize getPageSize​(int pageNum)
      Returns page dimensions object for a specified page number.
      static java.lang.String getVersion()
      returns current version number
      static java.util.Date getVersionBuildDate()  
      void injectHtml​(java.lang.String htmlSnippet, boolean prependBodyContent)
      Injects a portion of HTML to the source
      boolean isDemoMode()  
      boolean isPro()  
      void merge​(PdfDocument pdf, int fromPage, int toPage, boolean append)
      Merges conversion result with an already existing PDF document
      void monitorProgressWith​(ProgressListener listener)
      conversion progress callback support
      void outputRange​(java.lang.String description)  
      void overrideDocumentEncoding​(java.lang.String encoding)
      sets default encoding for URL-addressed HTML documents
      static int predictPageHeight​(PageMargins pageMargins, PageSize pageSize, int userSpace)
      predicts page height for given conversion parameters
      static float predictScale​(PageMargins pageMargins, PageSize pageSize, int userSpace)
      predicts document HTML-to-PDF mapping scale for given conversion parameters
      void protectPhysicalUnitDimensions​(boolean keepPhysicalUnitDimensions)
      makes PD4ML to output PDF objects respecting dimensions/font sizes given in "in", "pt", "cm" etc.
      void readHTML​(java.io.InputStream isr)
      converts input data to PDF
      void readHTML​(java.io.InputStream isr, java.net.URL base)
      converts input data to PDF.
      void readHTML​(java.io.InputStream isr, java.net.URL base, java.lang.String encoding)
      converts input data to PDF
      void readHTML​(java.net.URL url)
      input data referred by URL to PDF
      void readHTML​(java.net.URL url, java.lang.String encoding)
      input data referred by URL to PDF
      java.awt.image.BufferedImage[] renderAsImages()
      renders document in RAM as a set of images, represent document pages
      java.io.File renderAsImages​(java.io.File dir, java.lang.String fileNamePrefix, java.lang.String format)
      renders document as a set of image files, represent document pages
      byte[][] renderAsImages​(java.lang.String format)
      renders document in RAM as a set of images, represent document pages
      void setAuthorName​(java.lang.String name)
      sets an author name for the document
      void setCache​(java.lang.Object fontCache)  
      void setCookie​(java.lang.String name, java.lang.String value)
      makes PD4ML to add a cookie with given name and value to each URL connection request
      void setDocumentTitle​(java.lang.String title)
      forces to override HTML title
      void setDynamicData​(java.util.Map<java.lang.String,​java.lang.String> map)  
      void setHtmlWidth​(int width)
      defines desired HTML page width in screen pixels.
      void setHttpOptions​(java.lang.String proxy, java.lang.String basicAuthentication)
      specifies HTTP options
      void setInitialPageNumber​(int initialPageNumber)
      sets page number counter to given value.
      void setLogLevel​(int level)
      enables an output of log/diagnostics messages.
      void setPageBackground​(java.lang.String htmlCode)
      defines HTML code to be rendered under each page content
      void setPageBackground​(java.lang.String htmlCode, java.lang.String scope)
      defines HTML code to be rendered under each page content
      void setPageFooter​(java.lang.String htmlCode, int heightPx)
      defines HTML code to be rendered as page footer(s).
      void setPageFooter​(java.lang.String htmlCode, int heightPx, java.lang.String scope)
      defines HTML code to be rendered as page footer(s).
      void setPageHeader​(java.lang.String htmlCode, int heightPx)
      defines HTML code to be rendered as page header(s).
      void setPageHeader​(java.lang.String htmlCode, int heightPx, java.lang.String scope)
      defines HTML code to be rendered as page header(s).
      void setPageMargins​(PageMargins margins)
      defines page margins for all document pages
      void setPageMargins​(PageMargins margins, java.lang.String scope)
      defines page margins for specified range(s) of pages
      void setPageSize​(PageSize d)
      defines page size for all document pages.
      void setPageSize​(PageSize d, java.lang.String scope)
      defines page size for specified range(s) of pages
      void setParam​(java.lang.String key, java.lang.String value)
      Sets parsing/rendering parameters
      void setPermissions​(java.lang.String password, int permissions)
      forces the resulting document to be encrypted with the given password
      void setRenderingHints​(java.util.Map hints)
      Replaces the values of all preferences for the image rendering algorithms with the specified hints.
      void setSessionID​(java.lang.String sessionID)
      the method informs PD4ML about current session ID (in web application environments).
      void setWatermark​(java.lang.String htmlCode, float left, float top, float opacity, float angle, float scale, boolean screen, boolean print, java.lang.String scope)
      defines page watermark.
      void terminate()
      Terminates conversion process and cleans the font cache
      void testTermination()  
      static float translateToPt​(float mm)
      converts from millimeters to points
      void useHttpRequest​(jakarta.servlet.http.HttpServletRequest httpRequest, jakarta.servlet.http.HttpServletResponse httpResponse)
      method allows to inform PD4ML about actual HTTP request context (if any).
      void useTTF​(java.lang.String pathToFontDirs)
      enables TTF font embedding subsystem.
      void useTTF​(java.lang.String pathToFontDirs, boolean generateFontMappingFileIfMissing)  
      void useTTF​(java.lang.String pathToFontDirs, java.lang.String fontFileNameFilter)
      registers font directory and forces to index fonts, whose names match the filter patterns (for example, "arial,courier").
      void writeDOCX​(java.io.OutputStream os)  
      void writePDF​(java.io.OutputStream os)
      renders and writes parsed HTML as PDF document
      void writePDF​(java.io.OutputStream os, java.lang.String pdfFormat)  
      void writeRTF​(java.io.OutputStream os, boolean convertImagesToWMF)  
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • disableBatik

        public static boolean disableBatik
      • disableMathML

        public static boolean disableMathML
    • Constructor Detail

      • PD4ML

        public PD4ML()
        PD4ML Constructor Creates and initializes an instance of the converter
      • PD4ML

        public PD4ML​(java.lang.String license,
                     int loglevel)
        PD4ML Constructor Creates and initializes an instance of the converter
        Parameters:
        loglevel - bitmask to control logging verbosity
        license - license string or license file URI
      • PD4ML

        public PD4ML​(int loglevel)
        PD4ML Constructor Creates and initializes an instance of the converter
        Parameters:
        loglevel - bitmask to control logging verbosity
      • PD4ML

        public PD4ML​(java.lang.String license)
        PD4ML Constructor Creates and initializes an instance of the converter
        Parameters:
        license - license string or license file URI
    • Method Detail

      • applyLicense

        public final boolean applyLicense​(java.lang.String license)
        applies license code. The method should be called before initiation of PDF, RTF or image output. The method is implicitly called by PD4ML(String) If the method is not invoked, the software runs in demo mode: its output is watermarked and supplied with an ad footer. An applying of evalution license removes the watermarks but the footer message remains. An applying of a commercial license removes both watermark and footer in permitted output modes.
        Parameters:
        license - license string or license file URI
        Returns:
        true if the license is valid
        See Also:
        PD4ML(String)
      • isDemoMode

        public final boolean isDemoMode()
        Returns:
        true if the library is used in demo mode
        Since:
        v1.1.0
      • isPro

        public final boolean isPro()
        Returns:
        true if it is Pro version of the library
        Since:
        v3.8.1
      • getVersion

        public static java.lang.String getVersion()
        returns current version number
        Returns:
        version number formatted as a string
      • getVersionBuildDate

        public static java.util.Date getVersionBuildDate()
        Returns:
        current version build date
      • merge

        public void merge​(PdfDocument pdf,
                          int fromPage,
                          int toPage,
                          boolean append)
        Merges conversion result with an already existing PDF document
        Parameters:
        pdf - PDF document
        fromPage - start page of the existing document (1 or greater)
        toPage - end page of the existing document (-1 means all pages)
        append - 'true' forces to append the existing PDF to the conversion result. Otherwise the existing document will lead the conversion result.
      • terminate

        public void terminate()
        Terminates conversion process and cleans the font cache
      • readHTML

        public void readHTML​(java.io.InputStream isr)
                      throws InvokeException,
                             java.io.IOException
        converts input data to PDF
        Parameters:
        isr - input stream of formatted data. Determines encoding from BOM bytes or from HTML's meta tag
        Throws:
        InvokeException - the input or output stream is null
        java.io.IOException - input/output problems
      • readHTML

        public void readHTML​(java.io.InputStream isr,
                             java.net.URL base)
                      throws InvokeException,
                             java.io.IOException
        converts input data to PDF.
        Parameters:
        isr - input stream of formatted data. Determines encoding from BOM bytes or from HTML's meta tag
        base - base URL to lookup referred resources like images or CSS. Can be specified in HTML body with <base href="..."> tag
        Throws:
        InvokeException - the input or output stream is null
        java.io.IOException - input/output problems
      • readHTML

        public void readHTML​(java.io.InputStream isr,
                             java.net.URL base,
                             java.lang.String encoding)
                      throws InvokeException,
                             java.io.IOException
        converts input data to PDF
        Parameters:
        isr - input stream of formatted data. Determines encoding from BOM bytes or from HTML's meta tag
        base - base URL to lookup referred resources like images or CSS. Can be specified in HTML body with <base href="..."> tag
        encoding - content encoding. Value "default" corresponds to current OS encoding
        Throws:
        InvokeException - the input or output stream is null
        java.io.IOException - input/output problems
      • readHTML

        public void readHTML​(java.net.URL url)
                      throws InvokeException,
                             java.io.IOException
        input data referred by URL to PDF
        Parameters:
        url - text representation of the input data URL
        Throws:
        java.net.MalformedURLException - invalid URL
        InvokeException - the input or output stream is null
        java.io.IOException - input/output problems
      • readHTML

        public void readHTML​(java.net.URL url,
                             java.lang.String encoding)
                      throws java.net.MalformedURLException,
                             InvokeException,
                             java.io.IOException
        input data referred by URL to PDF
        Parameters:
        url - text representation of the input data URL
        encoding - encoding name to override
        Throws:
        java.net.MalformedURLException - invalid URL
        InvokeException - the input or output stream is null
        java.io.IOException - input/output problems
      • setLogLevel

        public void setLogLevel​(int level)
        enables an output of log/diagnostics messages.
        Parameters:
        level - log output verbosity level
      • useTTF

        public void useTTF​(java.lang.String pathToFontDirs)
                    throws java.io.FileNotFoundException
        enables TTF font embedding subsystem. Available only in professional version of PD4ML.
        Parameters:
        pathToFontDirs - URL of a font directory or a path to pd4fonts.properties mapping file
        The font directory should contain pd4fonts.properties mapping file. The file records have the following format:
        font_name=file_name
        • font_name - font name used in the source HTML.
        • file_name - font file name (should exist in the font directory)

        Example:

        Book\ Antiqua=BKANT.TTF
        To generate the file automatically you may use the command line call:
        java -jar pd4ml.jar -configure.fonts <fontdir>
        After the generation, please edit the file and remove manually all references to the fonts, that are not allowed to be redistributed. Contact your TTF fonts provider for the info.

        In order to support J2EE deployments a PD4ML-specific protocol "java:" is supported to load font resources via ClassLoader.

        Example: useTTF("java:myfonts");

        In that case the runtime looks for a fonts folder named "/myfonts" in all JAR files available for the application class loaders. The content of the folder should correspond to the rules described above: pd4fonts.properties + *.ttf

        Example: useTTF("java:");

        The simplest case. The runtime looks for a JAR file which contains pd4fonts.properties + *.ttf in the root directory.

        Throws:
        java.io.FileNotFoundException - if pd4fonts.properties file is not found or the file refers to missing font files
      • useTTF

        public void useTTF​(java.lang.String pathToFontDirs,
                           boolean generateFontMappingFileIfMissing)
                    throws java.io.FileNotFoundException
        Parameters:
        pathToFontDirs - URI of TTF file directory
        generateFontMappingFileIfMissing - forces to index available fonts (if they are not indexed yet). The indexing may be time/resource consuming. If true, make sure PD4ML has write permission to pathToFontDirs
        Throws:
        java.io.FileNotFoundException - font directory not found
        See Also:
        useTTF(String)
      • useTTF

        public void useTTF​(java.lang.String pathToFontDirs,
                           java.lang.String fontFileNameFilter)
                    throws java.io.FileNotFoundException
        registers font directory and forces to index fonts, whose names match the filter patterns (for example, "arial,courier").
        Parameters:
        pathToFontDirs - URI of TTF file directory,
        fontFileNameFilter - a comma-separated list of font family names or name parts
        Throws:
        java.io.FileNotFoundException - font directory not found
        See Also:
        useTTF(String)
      • embedTTFs

        public void embedTTFs​(boolean embed,
                              boolean allGlyphs)
        Parameters:
        embed - if true forces PD4ML to include used font glyphs to the resulting PDF, otherwise it registers only font family names (expecting the TTFs present in the PDF reader environment)
        allGlyphs - if true (and if param 'embed' is true) forces PD4ML to include all font glyphs to the resulting PDF
      • generateForms

        public void generateForms​(boolean enable,
                                  java.lang.String useTtfFont)
        forces PD4ML to convert HTML forms into PDF forms (Acroforms). Note: The feature is at a very early stage now (v3.2.3).
        Parameters:
        useTtfFont - - UNICODE TTF font name to be used for form input. The name must appear in pd4fonts.properties or specified via @font-face CSS at-rule
        enable - enables or disables the feature
        Since:
        v3.2.3 Pro
        See Also:
        useTTF(String)
      • generateForms

        public void generateForms​(boolean enable,
                                  java.lang.String useTtfFont,
                                  java.lang.String formFontCharRange)
        forces PD4ML to convert HTML forms into PDF forms (Acroforms). Note: The feature is at a very early stage now (v3.2.3).
        Parameters:
        useTtfFont - - UNICODE TTF font name to be used for form input. The name must appear in pd4fonts.properties or specified via @font-face CSS at-rule
        enable - enables or disables the feature
        formFontCharRange - - specifies ranges of characters to be embedded to the resulting PDF to cover possible user input, e.g. "0-9a-zA-Z*.,:"
        Since:
        v4.0.2
        See Also:
        useTTF(String)
      • generateMulticolumn

        public void generateMulticolumn​(int columns,
                                        int span,
                                        boolean millimeters)
        switches PD4ML into multicolumn mode. The mode in not compatible with adjustHtmlWidth() and fitPageVertically() calls.
        Parameters:
        columns - - number of columns per page
        span - - space between the columns
        millimeters - - if 'true' the gap is in millimeters, otherwise in points
      • useHttpRequest

        public void useHttpRequest​(jakarta.servlet.http.HttpServletRequest httpRequest,
                                   jakarta.servlet.http.HttpServletResponse httpResponse)
        method allows to inform PD4ML about actual HTTP request context (if any). HTTP request/response allows to get output of dynamic webapp resources.
        Parameters:
        httpRequest - actual HTTP request
        httpResponse - actual HTTP response
      • addCustomResourceProvider

        public void addCustomResourceProvider​(java.lang.String customProviderClassName)
        add custom resource loader for non-standard or customized transport protocols
        Parameters:
        customProviderClassName - name of class, derived from CustomResourceProvider. The class implementation must be in the classpath
      • addCustomTagHandler

        public void addCustomTagHandler​(java.lang.String customTagName,
                                        CustomTag implementation)
        adds a proprietary HTML tag implementation
        Parameters:
        customTagName - HTML tag name
        implementation - an instance of implementation class
      • generateBookmarksFromHeadings

        public void generateBookmarksFromHeadings​(boolean enable)
        Parameters:
        enable - if set to true, PD4ML creates PDF bookmark tree structure derived from <H1>-<H6> structure.
        See Also:
        generateBookmarksFromAnchors(boolean)
      • generateBookmarksFromAnchors

        public void generateBookmarksFromAnchors​(boolean enable)
        Parameters:
        enable - if true, PD4ML creates PDF bookmarks from headings ( <a name="destination">Label</a> tags). If a label attribute is not defined, it uses destination string as visible label.
        See Also:
        generateBookmarksFromHeadings(boolean)
      • setSessionID

        public void setSessionID​(java.lang.String sessionID)
        the method informs PD4ML about current session ID (in web application environments). The session ID is implicitely added by PD4ML to resource references (CSS, image etc). The addition is done in the following form: "resource.jpg;jsessionid=<sessionID>?other_args". "jsessionid" reserved name can be overriden by a setting of "pd4ml.sessionid.varname" environment variable
        Parameters:
        sessionID - actual session ID
        Since:
        v3.0.0.b1
      • overrideDocumentEncoding

        public void overrideDocumentEncoding​(java.lang.String encoding)
        sets default encoding for URL-addressed HTML documents
        Parameters:
        encoding - encoding name, matches Java encoding naming specifics (i.e. "ISO8859_1" instead of "ISO-8859-1")
        Since:
        v3.7.1
      • enableHyperlinks

        public void enableHyperlinks​(boolean enable)
        enables converting of HTML to PDF hyperlinks.
        Parameters:
        enable - if false, PD4ML does not generate active hyperlinks in resulting PDF. Default is "true"
        Since:
        v1.2.0
      • setPageHeader

        public void setPageHeader​(java.lang.String htmlCode,
                                  int heightPx)
                           throws InvokeException
        defines HTML code to be rendered as page header(s). Implicitly adds <pd4ml:page.header> to source HTML
        Parameters:
        htmlCode - header HTML code
        heightPx - header height (in screen pixels)
        Throws:
        InvokeException - method called with invalid parameters
      • setPageHeader

        public void setPageHeader​(java.lang.String htmlCode,
                                  int heightPx,
                                  java.lang.String scope)
                           throws InvokeException
        defines HTML code to be rendered as page header(s). Implicitly adds <pd4ml:page.header scope="..."> to source HTML
        Parameters:
        htmlCode - header HTML code
        heightPx - header height (in screen pixels)
        scope - scope of pages to apply the header
        Throws:
        InvokeException - method called with invalid parameters
      • setPageFooter

        public void setPageFooter​(java.lang.String htmlCode,
                                  int heightPx)
                           throws InvokeException
        defines HTML code to be rendered as page footer(s). Implicitly adds <pd4ml:page.footer> to source HTML
        Parameters:
        htmlCode - footer HTML code
        heightPx - footer height (in screen pixels)
        Throws:
        InvokeException - method called with invalid parameters
      • setPageFooter

        public void setPageFooter​(java.lang.String htmlCode,
                                  int heightPx,
                                  java.lang.String scope)
                           throws InvokeException
        defines HTML code to be rendered as page footer(s). Implicitly adds <pd4ml:page.footer scope="..."> to source HTML
        Parameters:
        htmlCode - footer HTML code
        heightPx - footer height (in screen pixels)
        scope - scope of pages to apply the footer
        Throws:
        InvokeException - method called with invalid parameters
      • setWatermark

        public void setWatermark​(java.lang.String htmlCode,
                                 float left,
                                 float top,
                                 float opacity,
                                 float angle,
                                 float scale,
                                 boolean screen,
                                 boolean print,
                                 java.lang.String scope)
        defines page watermark. The watermark content is rendered over the page content on all (or selected) pages.
        Parameters:
        htmlCode - watermark HTML code
        left - horizintal position
        top - vertical position
        opacity - watermark opacity from 0 to 1
        angle - rotate watermark layout to a given degree
        scale - watermark content scale from 0 to 1
        screen - if true, watermarks screen view
        print - if true, watermarks printed output
        scope - scope of pages to apply the watermark
      • setPageBackground

        public void setPageBackground​(java.lang.String htmlCode)
        defines HTML code to be rendered under each page content
        Parameters:
        htmlCode - background layout HTML code
      • setPageBackground

        public void setPageBackground​(java.lang.String htmlCode,
                                      java.lang.String scope)
        defines HTML code to be rendered under each page content
        Parameters:
        htmlCode - background layout HTML code
        scope - scope of pages to apply the background
      • setPermissions

        public void setPermissions​(java.lang.String password,
                                   int permissions)
        forces the resulting document to be encrypted with the given password
        Parameters:
        password - password. If is set to "empty", than no password assigned to document, only permissions.
        permissions - an integer value according to PDF encryption specification
        Since:
        v1.1.0
      • setCookie

        public void setCookie​(java.lang.String name,
                              java.lang.String value)
        makes PD4ML to add a cookie with given name and value to each URL connection request
        Parameters:
        name - cookie name
        value - cookie value
        Since:
        v3.0.2
      • setHttpOptions

        public void setHttpOptions​(java.lang.String proxy,
                                   java.lang.String basicAuthentication)
        specifies HTTP options
        Parameters:
        proxy - null or HTTP proxy settings in "host:port" format
        basicAuthentication - HTTP authentication pair in "login:password" format
      • addDocumentActionHandler

        public void addDocumentActionHandler​(java.lang.String actionType,
                                             java.lang.String javaScript)
        method defines JavaScript action handler for generated document.
        Parameters:
        actionType - "OpenAction", "DC" (document close), "WS" (will save), "DS" (did save), "WP" (will print) or "DP" (did print)
        javaScript - handler code
      • setPageSize

        public void setPageSize​(PageSize d,
                                java.lang.String scope)
        defines page size for specified range(s) of pages
        Parameters:
        d - page dimensions
        scope - scope of pages to apply the size
      • setPageSize

        public void setPageSize​(PageSize d)
                         throws InvokeException
        defines page size for all document pages. A set of predefined page format constants is available in the PD4Constants interface.
        To get "Landscape" page orientation invoke rotate() method of PageSize
        Parameters:
        d - page PageSize
        Throws:
        InvokeException - when the specified page format is null or does not fit to already defined page insets
      • getPageSize

        public PageSize getPageSize​(int pageNum)
        Returns page dimensions object for a specified page number. The result depends on default page format, page formats specified with setPageSize() calls as well as page formats defined in-line in CSS (page at-rule) or in HTML (<pd4ml:page.break> tag attribute).
        Parameters:
        pageNum - One-based indexed page number (the leading page is #1)
        Returns:
        page dimensions object
      • setPageMargins

        public void setPageMargins​(PageMargins margins)
        defines page margins for all document pages
        Parameters:
        margins - page margins
      • setPageMargins

        public void setPageMargins​(PageMargins margins,
                                   java.lang.String scope)
        defines page margins for specified range(s) of pages
        Parameters:
        margins - page margins
        scope - scope of pages to apply the margins
      • getPageMargins

        public PageMargins getPageMargins​(int pageNum,
                                          boolean imageGeneration)
        Returns page margins object for a specified page number. The result depends on default page margins, page margins specified with setPageMargins() calls as well as page formats defined in-line in CSS (page at-rule).
        Parameters:
        pageNum - One-based indexed page number (the leading page is #1)
        imageGeneration - selects default margin settings. By imageGeneration=true by default there is no margins.
        Returns:
        page margins object
      • setHtmlWidth

        public void setHtmlWidth​(int width)
                          throws InvokeException
        defines desired HTML page width in screen pixels. Virtually it can be seen as a web browser window horizontal resize.
        In the resulting PDF the HTML width is mapped to the paper page width (minus insets). There is no way to specify HTML page height. The height in screen pixels is set automatically depending on the width and the paper page proportions.
        Parameters:
        width - HTML width in screen pixels
        Throws:
        InvokeException - when the width is not a positive value great that 0.
      • adjustHtmlWidth

        public void adjustHtmlWidth​(boolean adjust)
        sets htmlWidth to the most right margin of the HTML block content. Calling the method would force PD4ML to build HTML layout with htmlWidth set by setHtmlWidth(int), to determine the most right edge of rendered content and to use the value for PDF mapping. Notes:
        • The method takes no effect for multi-URL PD4ML call: render(URL[],OutputStream)
        • In order to use the method efficiently, it is important to call setHtmlWidth(int) with a parameter value, which is greater than the expected right edge offset.
        • If the source document has HTML objects, whose width is set to 100%, than the method call is meaningless.
        • As long as htmlWidth affects HTML-to-PDF scale factor, usage of the method causes inconstancy of font/object sizes in the resulting PDF from document to document.
        Parameters:
        adjust - enables the adjustments
        Since:
        3.0.2
      • getFitPageVertically

        public short getFitPageVertically()
        Returns:
        content alignment if fitPageVertically mode is on
      • setAuthorName

        public final void setAuthorName​(java.lang.String name)
        sets an author name for the document
        Parameters:
        name - author's name
        Since:
        v1.0.5
      • setDocumentTitle

        public final void setDocumentTitle​(java.lang.String title)
        forces to override HTML title
        Parameters:
        title - document title
        Since:
        v1.0.5
      • setInitialPageNumber

        public void setInitialPageNumber​(int initialPageNumber)
        sets page number counter to given value. Impacts page numbering in document headers and footers.
        Parameters:
        initialPageNumber - page number of the first generated page
      • addStyle

        public final void addStyle​(java.net.URL stylesheet,
                                   boolean overrideDocumentStyles)
                            throws InvokeException
        Apply additional stylesheet to the document
        Parameters:
        stylesheet - of css stylesheet
        overrideDocumentStyles - if true, applies the stylesheet after styles defined in the document header.
        Throws:
        InvokeException - too many styles added
        Since:
        v3.1.0 Pro
      • addStyle

        public final void addStyle​(java.lang.String stylesheet,
                                   boolean overrideDocumentStyles)
                            throws InvokeException
        Apply additional stylesheet to the document
        Parameters:
        stylesheet - stylesheet content
        overrideDocumentStyles - if true, applies the stylesheet after styles defined in the document header.
        Throws:
        InvokeException - too many styles added
        Since:
        v3.1.0 Pro
      • injectHtml

        public void injectHtml​(java.lang.String htmlSnippet,
                               boolean prependBodyContent)
        Injects a portion of HTML to the source
        Parameters:
        htmlSnippet - HTML code
        prependBodyContent - if true, the HTML injected after opening <body> tag, otherwise right before closing </body> tag.
      • getHeight

        public int getHeight​(int width)
                      throws java.io.IOException
        calculates document height for given document width. The method implicitly renders the page layout in idle mode. The call can be time/resource consuming for big documents.
        Parameters:
        width - desired withs in screen pixels
        Returns:
        calculated document height
        Throws:
        java.io.IOException - general IO exception
      • getDocumentTitle

        public java.lang.String getDocumentTitle()
                                          throws InvokeException
        Returns:
        HTML document title
        Throws:
        InvokeException - if readHTML() is not invoked before
      • writePDF

        public void writePDF​(java.io.OutputStream os)
                      throws java.io.IOException
        renders and writes parsed HTML as PDF document
        Parameters:
        os - output stream to write PDF document bytes
        Throws:
        java.io.IOException - general IO exception
      • writePDF

        public void writePDF​(java.io.OutputStream os,
                             java.lang.String pdfFormat)
                      throws java.io.IOException
        Parameters:
        pdfFormat - Forces PD4ML to output either a regular PDF or a PDF format compliant with PDF/A specification. PDF/A specification requires all used fonts to be embedded to the resulting document. So the method call cannot guarantee the resulting doc is PDF/A, for example, if TTF embedding is disabled or not configured. To make sure a resulting document matches PDF/A requirements, request the last rendering status.
        os - output stream to write generated PDF bytes
        Throws:
        java.io.IOException - general IO exception
        See Also:
        Constants.PD4ML_PDFA_STATUS, getLastRenderInfo(String)
      • writeRTF

        public void writeRTF​(java.io.OutputStream os,
                             boolean convertImagesToWMF)
                      throws java.io.IOException
        Parameters:
        os - output stream to write generated RTF document bytes
        convertImagesToWMF - converts images to bulky WMF format for compatibility with restricted RTF viewers
        Throws:
        java.io.IOException - general IO exception
      • writeDOCX

        public void writeDOCX​(java.io.OutputStream os)
                       throws java.io.IOException
        Parameters:
        os - output stream to write generated DOCX document bytes
        Throws:
        java.io.IOException - general IO exception
      • setRenderingHints

        public void setRenderingHints​(java.util.Map hints)
        Replaces the values of all preferences for the image rendering algorithms with the specified hints. The existing values for all rendering hints are discarded and the new set of known hints and values are initialized from the specified Map object. Hint categories include controls for rendering quality and overall time/quality trade-off in the rendering process. Refer to the java.awt.RenderingHints class for definitions of some common keys and values.
        Parameters:
        hints - the image rendering hints to be set
        See Also:
        RenderingHints
      • renderAsImages

        public java.io.File renderAsImages​(java.io.File dir,
                                           java.lang.String fileNamePrefix,
                                           java.lang.String format)
                                    throws java.io.IOException
        renders document as a set of image files, represent document pages
        Parameters:
        dir - target directory
        fileNamePrefix - file name prefix for image files. The prefix is followed by page number and file extension, corresponds the requested image type.
        format - image format
        Returns:
        first page image file
        Throws:
        java.io.IOException - general IO exception
        See Also:
        Constants.PNG24, Constants.PNG8, Constants.MULTIPAGE_TIFF, Constants.MULTIPAGE_TIFF_COMPRESSED, Constants.TIFF, Constants.TIFF_COMPRESSED
      • renderAsImages

        public java.awt.image.BufferedImage[] renderAsImages()
                                                      throws java.io.IOException
        renders document in RAM as a set of images, represent document pages
        Returns:
        an array of buffered image objects
        Throws:
        java.io.IOException - general IO exception
      • dump

        public java.lang.String dump​(int mode)
                              throws java.io.IOException
        debug/diagnostics method
        Parameters:
        mode - dump verbosity flags
        Returns:
        dump or parsed/normalized HTML structure
        Throws:
        java.io.IOException - general IO exception
      • protectPhysicalUnitDimensions

        public void protectPhysicalUnitDimensions​(boolean keepPhysicalUnitDimensions)
        makes PD4ML to output PDF objects respecting dimensions/font sizes given in "in", "pt", "cm" etc. Use the method carefully: as long as it triggered, there is no single HTML-to-PDF scale factor for all HTML objects. The resulting PDF layout may appear visually corrupted. If the method is not triggered, all sizes given in physical measurement units are converted to their screen pixel equivalents (using 72dpi) before HTML layout. The method call can not be combined with adjustHtmlWidth() and fitPageVertically() calls, which affect HTML-to-PDF scale factor their own way.
        Parameters:
        keepPhysicalUnitDimensions - enable if true
        Since:
        v3.0.4, v4.0.9
      • translateToPt

        public static final float translateToPt​(float mm)
        converts from millimeters to points
        Parameters:
        mm - value in millimeters
        Returns:
        converted value
      • predictScale

        public static final float predictScale​(PageMargins pageMargins,
                                               PageSize pageSize,
                                               int userSpace)
        predicts document HTML-to-PDF mapping scale for given conversion parameters
        Parameters:
        pageMargins - page margins
        pageSize - page size
        userSpace - HTML width in screen pixels
        Returns:
        computed scale factor
      • predictPageHeight

        public static final int predictPageHeight​(PageMargins pageMargins,
                                                  PageSize pageSize,
                                                  int userSpace)
        predicts page height for given conversion parameters
        Parameters:
        pageMargins - page margins
        pageSize - page size
        userSpace - HTML width in screen pixels
        Returns:
        computed page height in screen pixels
      • setDynamicData

        public void setDynamicData​(java.util.Map<java.lang.String,​java.lang.String> map)
        Parameters:
        map - a set of key/value (String/String) pairs to dynamically substitute placeholders in HTML template (like "$[key]"). Key names "page", "total" and "title" are reserved for PDF headers and footers.
      • setParam

        public void setParam​(java.lang.String key,
                             java.lang.String value)
        Sets parsing/rendering parameters
        Parameters:
        key - parameter name
        value - parameter value
      • outputRange

        public void outputRange​(java.lang.String description)
        Parameters:
        description - a string with output rules. Currently allows to limit a scope of generated pages. Examples: "2+" - skip the first page, "1-2" - output only the first and the second pages, "even" or "odd" - it is obvious. The rules may be combined: "3-7,odd"
        Since:
        v3.5.5
      • monitorProgressWith

        public void monitorProgressWith​(ProgressListener listener)
        conversion progress callback support
        Parameters:
        listener - receiver of progress update messages
      • addMetadata

        public void addMetadata​(java.lang.String key,
                                java.lang.String value,
                                boolean hide)
        The method defines custom properties for PDF document meta data. The method takes effect only with PD4ML DMS and PD4ML UA license types.
        Parameters:
        key - a unique name, which must not be one of the standard property names Title, Author, Subject, Keywords, Creator, Producer, CreationDate, ModDate and Trapped
        value - data itself
        hide - makes the metadata not appear in the PDF document properties dialog of Acroread
      • applyKerning

        public void applyKerning​(boolean enable)
        Forces PD4ML to align font glyphs to each other according to the font kerning hints (if available). The API call takes effect only by PDF generation.
        Parameters:
        enable - - enables the feature
      • enableLigatures

        public void enableLigatures​(boolean enable)
        Forces PD4ML to load TTF/OTF glyph susbstitution tables, to apply ligature replacements and to build compound glyphs. The feature requires pd4ml_fonttool.jar
        Parameters:
        enable - - enables the feature
      • getCache

        public java.lang.Object getCache()
        Returns:
        cache object to be reused by new PD4ML instances. The cache object is not reentrant, so a single instance cannot be used from multiple threads.
        See Also:
        setCache(Object)
      • setCache

        public void setCache​(java.lang.Object fontCache)
        Parameters:
        fontCache - cache object returned by other PD4ML instance
        See Also:
        getCache()
      • asyncResourceLoader

        public void asyncResourceLoader​(int threadPoolSize)
        enables asynchronous resource loading (graphics, attachments etc) if thread pool size is not equal 0. By default the asynchronous loader is disabled. As the loader spawns new threads, usage of it is discouraged in Java EE environment.
        Parameters:
        threadPoolSize - loader thread pool size. If the value is negative, it it does not limit the pool size: creates new threads as needed, but will reuse previously constructed threads when they are available.