Package org.zefer.pd4ml

Class PD4ML

    • Field Detail

      • adjustHtmlWidthFlag

        public boolean adjustHtmlWidthFlag

      • fitPageVertically

        public boolean fitPageVertically

      • fitPageVerticallyAndCenter

        public boolean fitPageVerticallyAndCenter

      • debug

        public boolean debug

      • disableHyperlinksFlag

        public boolean disableHyperlinksFlag

    • Constructor Detail

      • PD4ML

        public PD4ML()
        PD4ML Constructor Creates and initializes an instance of the rendering engine

    • Method Detail

      • isDemoMode

        public static final boolean isDemoMode()
        returns true if the library is used in evaluation mode
        Since:
        v1.1.0

      • isPro

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

      • getVersion

        public static String getVersion()
        getVersion() returns current version number
        Returns:
        version number formatted as a string

      • merge

        public void merge​(InputStream input,
                  int fromPage,
                  int toPage,
                  boolean append)
        Merges conversion result with an already existing PDF document
        Parameters:
        input - PDF document input stream
        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.
        Since:
        v3.8 *Pro*

      • merge

        public void merge​(Reader input,
                  int fromPage,
                  int toPage,
                  boolean append)
        Merges conversion result with an already existing PDF document
        Parameters:
        input - PDF document reader
        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.
        Since:
        v3.8 *Pro*

      • render

        public void render​(InputStreamReader isr,
                   OutputStream os,
                   URL base)
            throws InvalidParameterException,
                   IOException
        converts input data to PDF.
        Parameters:
        isr - input stream reader of formatted data. Relies to properly specified encoding.
        os - output stream to generate PDF to
        base - base URL to lookup referred resources like images or CSS. Can be specified in HTML body with <base href="..."> tag
        Throws:
        InvalidParameterException - the input or output stream is null
        IOException - input/output problems

      • render

        public void render​(StringReader isr,
                   OutputStream os,
                   URL base,
                   String encoding)
            throws InvalidParameterException,
                   IOException
        converts input data to PDF
        Parameters:
        isr - string reader of formatted data. Take care for proper encoding
        os - output stream to generate PDF to
        base - base URL to lookup referred resources like images or CSS. Can be specified in HTML body with <base href="..."> tag
        encoding - content encoding
        Throws:
        InvalidParameterException - the input or output stream is null
        IOException - input/output problems

      • render

        public void render​(StringReader isr,
                   OutputStream os,
                   URL base)
            throws InvalidParameterException,
                   IOException
        converts input data to PDF
        Parameters:
        isr - string reader of formatted data. Take care for proper encoding
        os - output stream to generate PDF to
        base - base URL to lookup referred resources like images or CSS. Can be specified in HTML body with <base href="..."> tag
        Throws:
        InvalidParameterException - the input or output stream is null
        IOException - input/output problems

      • render

        public void render​(StringReader[] isrs,
                   OutputStream os,
                   URL base)
            throws InvalidParameterException,
                   IOException
        converts input data to PDF
        Parameters:
        isrs - array of string readers wrap formatted data. Take care for proper encoding
        os - output stream to generate PDF to
        base - base URL to lookup referred resources like images or CSS. Can be specified in HTML body with <base href="..."> tag
        Throws:
        InvalidParameterException - the input or output stream is null
        IOException - input/output problems

      • enableDebugInfo

        public void enableDebugInfo()
        enables an output of debug messages. (absolute paths to loaded images and TTF)
        Since:
        v1.2.0

      • useTTF

        public void useTTF​(String pathToFontDirs,
                   boolean embed)
            throws FileNotFoundException
        enables TTF font embedding subsystem. Available only in professional version of PD4ML.
        Parameters:
        embed - if true forces PD4ML to include used font glyphs to the resulting PDF
        pathToFontDirs - URL of a font directory.
        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", true );

        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:", true );

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

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

      • 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

      • generatePdfForms

        public void generatePdfForms​(boolean enable,
                             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 - (not implemented yet) - UNICODE TTF font name to be used for form input. The name must appear in pd4fonts.properties
        enable - enables or disables the feature
        Since:
        v3.2.3 Pro
        See Also:
        useTTF(String, boolean)

      • 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

      • useServletContext

        public void useServletContext​(Object ctx)
        method allows to inform PD4ML about actual servlet context (if any). An access to servlet context allows to resolve absolute resource paths.
        Parameters:
        ctx - servlet context: a javax.servlet.ServletContext (Java EE) or a jakarta.servlet.ServletContext (Jakarta EE 9 and newer)

      • useServletContext

        public void useServletContext​(javax.servlet.ServletContext ctx)
        Deprecated.
        binary compatibility with code compiled against earlier PD4ML versions only; the build marks it synthetic, so compilers do not see it. Use useServletContext(Object).

      • useHttpRequest

        public void useHttpRequest​(Object httpRequest,
                           Object httpResponse)
        method allows to inform PD4ML about actual HTTP request context (if any). HTTP request/response allows to get output of dynamic webapp resources. Takes the javax.servlet (Java EE) or the jakarta.servlet (Jakarta EE 9 and newer) request and response.
        Parameters:
        httpRequest - actual HTTP request: javax.servlet.http.HttpServletRequest or jakarta.servlet.http.HttpServletRequest
        httpResponse - actual HTTP response: javax.servlet.http.HttpServletResponse or jakarta.servlet.http.HttpServletResponse

      • useHttpRequest

        public void useHttpRequest​(javax.servlet.http.HttpServletRequest httpRequest,
                           javax.servlet.http.HttpServletResponse httpResponse)
        Deprecated.
        binary compatibility with code compiled against earlier PD4ML versions only; the build marks it synthetic, so compilers do not see it. Use useHttpRequest(Object, Object).

      • setDefaultTTFs

        public void setDefaultTTFs​(String serif,
                           String sansserif,
                           String monospace)
        defines deafult TTF font faces to be used as substritutions for unknown fonts.
        Parameters:
        serif - - plain font face for serif fonts (like Times New Roman)
        sansserif - - plain font face for sansserif fonts (like Helvetica or Arial)
        monospace - - plain font face for monospace fonts (like Courier New)
        Since:
        3.0.2

      • enableRenderingPatch

        public void enableRenderingPatch​(boolean patch)
        Deprecated.
        no patching is needed
        enables or disables a patch of the Swing HTML rendering engine. The patch solves some visual problems with unknown tags and corrupted representation of XHTML files. By default the patch is enabled.
        Parameters:
        patch - boolean switch

      • useAdobeFontMetrics

        public void useAdobeFontMetrics​(boolean use)
        Deprecated.
        always uses AFM
        if set to true, it forces PD4ML to use Adobe font glyph widths instead of the font metrics provided by Java graphical environment. As a result HTML page layout can look broken in GUI (in PD4ML Browser/Converter; for instance, text strings can overlap each other), but resulting PDF is rendered usually more correctly.
        Parameters:
        use - boolean switch
        Since:
        v1.1.0

      • generateOutlines

        public void generateOutlines​(boolean fromHeadings)
        if triggered, than PD4ML generates PDF bookmarks (aka outlines).
        Parameters:
        fromHeadings - if set to false, PD4ML creates PDF bookmarks taken from <a name="destination">Label</a> tags. If a label is not defined, it uses destination string as visible label.
        if set to true, than PD4ML creates PDF bookmark tree structure derived from <H1>-<H6> structure.
        Since:
        v1.2.0

      • setSessionID

        public void setSessionID​(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​(String encoding)
        sets default encoding for URL-addressed HTML documents
        Parameters:
        encoding - name
        Since:
        v3.7.1

      • disableHyperlinks

        public void disableHyperlinks()
        if triggered, PD4ML does not generate active hyperlinks in resulting PDF.
        Since:
        v1.2.0

      • enableImgSplit

        public void enableImgSplit​(boolean split)
        allows to disable image splitting by page breaks. By default the option is true (splitting enabled). If the option is set to false, than PD4ML tries to put page breaks protecting the images. If an image height (in screen pixels) is bigger than computed page height (in screen pixels), than it will be splitted regardless the option.
        Parameters:
        split - boolean switch
        See Also:
        setHtmlWidth(int)

      • enableTableBreaks

        public void enableTableBreaks​(boolean enable)
        Deprecated.
        Use enableSmartTableBreaks(boolean) instead
        Since:
        v2.2.0b1/1.2.6/3.1.0

      • enableSmartTableBreaks

        public void enableSmartTableBreaks​(boolean enable)
        The method switches on/off the experimental table break feature. If it set to true, PD4ML tries to insert page breaks inbetween table rows to make the table portions fit PDF page height. If the table has a header (the first row with <th> cells only) it replicates the row to each table section. In order avoid multi-pass re-layouting of source HTML, the feature is implemented by simple way and has its limitations: it does not support nested tables, multi-page rowspans etc. As long as the feature experimental please use it in production only with extensively tested HTML templates.
        Since:
        v3.6.1b2

      • setPermissions

        public void setPermissions​(String password,
                           int permissions,
                           boolean isStrong)
        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
        isStrong - selects between two type of PDF encryption: type2 (false) and type3 (true)
        Since:
        v1.1.0

      • setCookie

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

      • addDocumentActionHandler

        public void addDocumentActionHandler​(String actionType,
                                     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

      • setHtmlWidth

        public void setHtmlWidth​(int width)
                  throws InvalidParameterException
        defines desired HTML page width in screen pixels. Virtually it can be seen as a web browser window horizonltal 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:
        InvalidParameterException - when the width is not a positive value great that 0.

      • adjustHtmlWidth

        public void adjustHtmlWidth()
        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.
        Since:
        3.0.2

      • fitPageVertically

        public void fitPageVertically()
        forces PD4ML to downscale entire HTML layout to fit a single PDF page vertically.
        Since:
        v3.0.4

      • fitPageVertically

        public void fitPageVertically​(boolean center)

      • generatePdfa

        public final void generatePdfa​(boolean enable)
        Forces PD4ML to output PDF 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.
        Since:
        v3.6.0
        See Also:
        PD4Constants.PD4ML_PDFA_STATUS, getLastRenderInfo(String)

      • protectPhysicalUnitDimensions

        public void protectPhysicalUnitDimensions()
        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 layouting. The method call can not be combined with adjustHtmlWidth() and fitPageVertically() calls, which affect HTML-to-PDF scale factor their own way.
        Since:
        v3.0.4

      • interpolateImages

        public final void interpolateImages​(boolean mode)
        enables or disables image interpolation
        Parameters:
        mode - true - enables interpolation. default is false
        Since:
        v1.0.5

      • setAuthorName

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

      • setDocumentTitle

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

      • addStyle

        public final void addStyle​(URL stylesheet,
                           boolean overrideDocumentStyles)
                    throws InvalidParameterException
        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:
        InvalidParameterException - too many styles added
        Since:
        v3.1.0 Pro

      • addStyle

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

      • resetAddedStyles

        public final void resetAddedStyles()
        Reset all styles added with PD4ML.addStyle()
        Since:
        v3.1.0 Pro

      • renderAsImages

        public BufferedImage[] renderAsImages​(URL url,
                                      int width,
                                      int height)
                               throws IOException
        converts URL to image object(s)
        Parameters:
        width - target image width
        height - target image height
        Returns:
        an array of buffered images, represent a page.
        Throws:
        IOException

      • renderAsImages

        public BufferedImage[] renderAsImages​(StringReader isr,
                                      URL base,
                                      int width,
                                      int height)
                               throws IOException
        Parameters:
        isr - string reader of formatted data. Take care for proper encoding
        base - base URL to lookup referred resources like images or CSS. Can be specified in HTML body with <base href="..."> tag
        width - target image width
        height - target image height
        Returns:
        an array of buffered images, represent a page.
        Throws:
        IOException

      • debug

        public static void debug​(String str)
        debug() utility method
        Parameters:
        str - debug message

      • translate

        public static final int translate​(int i)
        converts from millimeters to points
        Parameters:
        i - value in millimeters

      • changePageOrientation

        public Dimension changePageOrientation​(Dimension d)
        rotates given page format by 90 degrees.
        Make sure that after rotating of standard page formats from PD4Constants you pass the new dimensions to setPageSize() (not setPageSizeMM())
        Parameters:
        d - original page dimension
        Returns:
        modified page dimensions

      • predictScale

        public static final float predictScale​(Insets pageInsets,
                                       Dimension pageSize,
                                       int userSpace)

      • predictPageHeight

        public static final int predictPageHeight​(Insets pageInsets,
                                          Dimension pageSize,
                                          int userSpace)

      • setDynamicParams

        public void setDynamicParams​(Map dynamicParams)
        Parameters:
        dynamicParams - 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.

      • getLastRenderInfo

        public Object getLastRenderInfo​(String key)
        returns statistics for the last render() call
        Parameters:
        key - - one of the currently supported keys: "pd4ml.document.height.px", "pd4ml.right.edge.px" or "pd4ml.total.pages".
        Returns:
        Long object (for the currently implemented keys; other types expected in the future)
        Since:
        3.5.1
        See Also:
        PD4Constants

      • outputRange

        public void outputRange​(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

      • outputFormat

        public void outputFormat​(String format)
        Parameters:
        format - file format to output. PD4Constants.PDF - default.
        Since:
        v3.7.0

      • outputFormat

        public void outputFormat​(String format,
                         int width,
                         int height)
        Parameters:
        format - file format to output. PD4Constants.PDF - default.
        height - - limits resulting document simentions by height. relevant for HTML-to-image conversions only
        width - - limits resulting document simentions by width. relevant for HTML-to-image conversions only
        Since:
        v3.7.1

      • addMetadata

        public void addMetadata​(String key,
                        String value,
                        boolean hide)
        The method defines custom properties for PDF document meta data. The method takes effect only in PD4ML Volume DMS and PD4ML SRC license binaries.
        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

      • clearCache

        public void clearCache()
        removes all objects (images, CSS, etc) from internal caches.
        Since:
        v3.6.0fx1

      • setCache

        public void setCache​(PD4Cache cacheWrapper)
        lets PD4ML to reuse data, cached by another PD4ML instance. PD4ML caches data in static hash tables, which implicitly share the cached data amonth PD4ML instances. The method call makes only sence if the tables are garbage collected for some reasons.
        Since:
        v3.6.1b2
        See Also:
        getCache()

      • utility

        public void utility​(StringBuffer diags)
        Utility method used for testing
        Parameters:
        diags - string buffer to write to

      • monitorProgress

        public void monitorProgress​(PD4ProgressListener listener)
        conversion progress callback support
        Parameters:
        listener - receiver of progress update messages