Class PD4ML


public class PD4ML extends PD4Constants
  • Field Details

    • ISO8859_1

      public static final String ISO8859_1
      See Also:
    • FILE_ENCODING

      public static final String FILE_ENCODING
      See Also:
    • adjustHtmlWidthFlag

      public boolean adjustHtmlWidthFlag
    • fitPageVertically

      public boolean fitPageVertically
    • fitPageVerticallyAndCenter

      public boolean fitPageVerticallyAndCenter
    • debug

      public boolean debug
    • disableHyperlinksFlag

      public boolean disableHyperlinksFlag
  • Constructor Details

    • PD4ML

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

    • 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

      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
      Throws:
      InvalidParameterException - the input or output stream is null
      IOException - input/output problems
    • render

      public void render(StringReader isr, OutputStream os) throws InvalidParameterException, IOException
      converts input data to PDF
      Parameters:
      isr - string reader of formatted data. Relies to properly specified encoding.
      os - output stream to generate PDF to
      Throws:
      InvalidParameterException - the input or output stream is null
      IOException - input/output problems
    • 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
    • render

      input data referred by URL to PDF
      Parameters:
      textUrl - text representation of the input data URL
      os - output stream to generate PDF to
      Throws:
      MalformedURLException - invalid URL
      InvalidParameterException - the input or output stream is null
      IOException - input/output problems
    • render

      public void render(URL url, OutputStream os) throws InvalidParameterException, IOException
      converts input data referred by URL to PDF
      Parameters:
      url - input data URL
      os - output stream to generate PDF to
      Throws:
      MalformedURLException - invalid URL
      InvalidParameterException - the input or output stream is null
      IOException - input/output problems
    • render

      public void render(URL[] urls, OutputStream os) throws InvalidParameterException, IOException
      converts input data referred by URLs to PDF
      Parameters:
      urls - input data URLs
      os - output stream to generate PDF to
      Throws:
      MalformedURLException - invalid URL
      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
    • 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:
    • 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(jakarta.servlet.ServletContext 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
    • 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
    • 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:
    • enableTableBreaks

      public void enableTableBreaks(boolean enable)
      Deprecated.
      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
    • setPageHeader

      public void setPageHeader(PD4PageMark mark) throws InvalidParameterException
      defines page header area
      Parameters:
      mark - header configuration object
      Throws:
      InvalidParameterException - when the config is null
      Since:
      v1.0.5
    • setPageFooter

      public void setPageFooter(PD4PageMark mark) throws InvalidParameterException
      defines page footer area
      Parameters:
      mark - footer configuration object
      Throws:
      InvalidParameterException - when the config is null or contains invalid data
      Since:
      v1.0.5
    • setPageSizeMM

      public void setPageSizeMM(Dimension d) throws InvalidParameterException
      defines page size in milimeters. The method internally converts sizes to points and calls setPageSize()
      Parameters:
      d - page dimensions in mm
      Throws:
      InvalidParameterException
      See Also:
    • 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
    • setPageSize

      public void setPageSize(Dimension d) throws InvalidParameterException
      defines page size in points. A set of predefined page format constants is available in the PD4Constants interface.
      To get "Landscape" page orientation of of the constant page sizes use changePageOrientation() method call to landscape convert the
      Parameters:
      d - page dimensions in points
      Throws:
      InvalidParameterException
      See Also:
    • setPageInsetsMM

      public void setPageInsetsMM(Insets ii) throws InvalidParameterException
      specifies page insets in millimeters. The method internally converts sizes to points and calls setPageInsets()
      Parameters:
      ii - page insets in millimeters
      Throws:
      InvalidParameterException
      See Also:
    • setPageInsets

      public void setPageInsets(Insets ii) throws InvalidParameterException
      specifies page insets in points
      Parameters:
      ii - page insets in points
      Throws:
      InvalidParameterException
    • 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:
    • 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
    • printInlineRtfHeaderOrFooter

      protected void printInlineRtfHeaderOrFooter(PD4RtfDevice gd, PageHeaderElement inlineHeader, String title, Map data, int htmlWidth, int generation)
      Prints header or footer (defined inline) whose height can vary from page to page.
      Parameters:
      gd - RTF device
      inlineHeader - header element
      title - document title (cab be overriden by API)
      data - dynamic data for placeholders substitution
      generation - dynamic data generation id
    • printRtfHeaderOrFooter

      protected void printRtfHeaderOrFooter(PD4RtfDevice gd, PD4PageMark header, String title, URL base, int userSpaceWidth, String encoding, ResourceCache cache, double scaleFactor, boolean firstPage) throws IOException
      Throws:
      IOException
    • printInlineHtmlHeaderOrFooter

      protected void printInlineHtmlHeaderOrFooter(PD4Device gd, boolean isFooter, PageHeaderElement inlineHeader, String title, int totalPages, int pageNumber, Map data, int maxHeight, int htmlWidth, int generation, Vector footnotes) throws IOException
      Prints header or footer (defined inline) whose height can vary from page to page.
      Parameters:
      gd - device
      isFooter - boolean mode: "header or footer"
      inlineHeader - header element
      title - document title (cab be overriden by API)
      totalPages - total number of pages
      pageNumber - current page number
      data - dynamic data for placeholders substitution
      maxHeight - height limit
      htmlWidth - actual setHtmlWidth(int) parameter
      generation - dynamic data generation id
      footnotes - page footnotes (if any)
      Throws:
      IOException
    • inlineHtmlHeaderHeight

      protected int inlineHtmlHeaderHeight(PageHeaderElement header, String title, int pageNumber, Map data, int maxHeight, int htmlWidth, int generation)
      Measures height of header or footer (defined inline).
      Parameters:
      header - header element
      title - document title (cab be overriden by API)
      pageNumber - current page number
      data - dynamic data for placeholders substitution
      maxHeight - height limit
      htmlWidth - actual setHtmlWidth(int) parameter
      generation - dynamic data generation id
      Returns:
      header/footer area height
    • printBackground

      protected void printBackground(PD4Device gd, PD4PageMark header, PD4PageMark footer, URL base, int pageNumber, ResourceCache cache) throws IOException
      Throws:
      IOException
    • printHtmlHeaderAndFooter

      protected void printHtmlHeaderAndFooter(PD4Device gd, PD4PageMark header, PD4PageMark footer, String title, URL base, int userSpaceWidth, int totalPages, int pageNumber, String encoding, ResourceCache cache, double scaleFactor) throws IOException
      Throws:
      IOException
    • 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:
    • 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
    • getCache

      public PD4Cache getCache()
      Returns:
      wrapped PD4ML cache to be reused
      Since:
      v3.6.1b2
      See Also:
    • 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:
    • monitorProgress

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