HTML to PDF API for Java

This is the documentation of the Java client library for the Pdfcrowd HTML to PDF API. Here are some sample PDFs generated by the API:


Status report	JavaScript vector chart	Wikipedia page	Invoice	Newsletter

Installation

Integration with your application is a matter of a few minutes:

Sign up and obtain your username and API key.
Download the client library: pdfcrowd-2.5-java.zip
Unpack the downloaded .zip file and put pdfcrowd.jar to your CLASSPATH.

Getting Started

In the following examples, do not forget to replace "username" and "apikey" with your username and API key.

import com.pdfcrowd.*;
import java.io.*;

public class PdfcrowdTest {
    public static void main(String[] args) {
        try 
        {
            FileOutputStream fileStream;     
 
            // create an API client instance
            Client client = new Client("username", "apikey");

            // convert a web page and save the PDF to a file
            fileStream = new FileOutputStream("example.pdf");
            client.convertURI("http://example.com/", fileStream);
            fileStream.close();

            // convert an HTML string and store the PDF into a byte array
            ByteArrayOutputStream memStream  = new ByteArrayOutputStream();
            String html = "<html><body>In-memory HTML.</body></html>";
            client.convertHtml(html, memStream);

            // convert an HTML file
            fileStream = new FileOutputStream("file.pdf");
            client.convertFile("/path/to/local/file.html", fileStream);
            fileStream.close();

            // retrieve the number of tokens in your account
            Integer ntokens = client.numTokens();
        }
        catch(PdfcrowdError why) {
            System.err.println(why.getMessage());
        }
        catch(IOException exc) {
            // handle the exception
        }
    }
}

Error Handling

try {
    // ..
    // call the API
} catch(PdfcrowdError why) {
    // why.getMessage() returns an error message
}

API Reference

class com.pdfcrowd.Client (view source)

Provides access to the Pdfcrowd API from your Java applications.

Constructor

public Client(String username, String apikey)

Arguments are your username at Pdfcrowd and apikey which can be found in your account.

Conversion

public void convertHtml(String html, java.io.OutputStream outstream)

Converts the html string to PDF and writes the result to outstream.

public void convertFile(String fpath, java.io.OutputStream outstream)

Converts a local file fpath to PDF and writes the result to outstream. The file can be either an HTML document or a .zip, .tar.gz., or .tar.bz2 archive which can contain external resources such as images, stylesheets, etc.

public void convertURI(String url, java.io.OutputStream outstream)

Converts a web page at url to PDF and writes the result to outstream.

Page Setup

public void setPageWidth(double/String value)

Sets PDF page width in units.

public void setPageHeight(double/String value)

Sets PDF page height in units. Use -1 for a single page PDF.

public void setPageMargins(String top, String right, String bottom, String left)

Sets PDF page margins in units.

public void setHorizontalMargin(double/String value)

Deprecated. Use setPageMargins instead.

public void setVerticalMargin(double/String value)

Deprecated. Use setPageMargins instead.

Header and Footer

public void setFooterHtml(String html)

Places the specified html code inside the page footer. The following variables are expanded:

%u - URL to convert.
%p - The current page number.
%n - Total number of pages.

public void setFooterUrl(String url)

Loads HTML code from the specified url and places it inside the page footer. See setFooterHtml for the list of variables that are expanded.

public void setHeaderHtml(String html)

Places the specified html code inside the page header. See setFooterHtml for the list of variables that are expanded.

public void setHeaderUrl(String url)

Loads HTML code from the specified url and places it inside the page header. See setFooterHtml for the list of variables that are expanded.

public void setHeaderFooterPageExcludeList(String exclist)

exclist is a comma seperated list of physical page numbers on which the header a footer are not printed. Negative numbers count backwards from the last page: -1 is the last page, -2 is the last but one page, and so on.
Example: "1,-1" will not print the header and footer on the first and the last page.

public void setPageNumberingOffset(int offset)

An offset between physical and logical page numbers. The default value is 0.
Example: if set to "1" then the page numbering will start with 1 on the second page.

HTML options

public void enableImages(boolean value)

Set value to false to disable printing images to the PDF. The default is true

public void enableBackgrounds(boolean value)

Set value to false to disable printing backgrounds to the PDF. The default is true

public void setHtmlZoom(double value)

Set HTML zoom in percents. It determines the precision used for rendering of the HTML content. Despite its name, it does not zoom the HTML content. Higher values can improve glyph positioning and can lead to overall better visual appearance of generated PDF .The default value is 200. See also setPdfScalingFactor().

public void enableJavaScript(boolean value)

Set value to false to disable JavaScript in web pages. The default is true.

public void enableHyperlinks(boolean value)

Set value to false to disable hyperlinks in the PDF. The default is true.

public void setDefaultTextEncoding(String value)

value is the text encoding used when none is specified in a web page. The default is utf-8.

public void usePrintMedia(boolean value)

If value is true then the print CSS media type is used (if available).

PDF options

public void setEncrypted(boolean value)

If value is set to true then the PDF is encrypted. This prevents search engines from indexing the document. The default is false.

public void setUserPassword(String pwd)

Protects the PDF with a user password. When a PDF has a user password, it must be supplied in order to view the document and to perform operations allowed by the access permissions. At most 32 characters.

public void setOwnerPassword(String pwd)

Protects the PDF with an owner password. Supplying an owner password grants unlimited access to the PDF including changing the passwords and access permissions. At most 32 characters.

public void setNoPrint(boolean value)

Set value to true disables printing the generated PDF. The default is false.

public void setNoModify(boolean value)

Set value to true to disable modifying the PDF. The default is false.

public void setNoCopy(boolean value)

Set value to true to disable extracting text and graphics from the PDF. The default is false.

public void setPageLayout(int value)

Specifies the initial page layout when the PDF is opened in a viewer.

SINGLE_PAGE
CONTINUOUS
CONTINUOUS_FACING

public void setPageMode(int value)

Specifies the appearance of the PDF when opened.

FULLSCREEN - Full-screen mode.

public void setInitialPdfZoomType(int value)

value specifies the appearance of the PDF when opened.

FIT_WIDTH
FIT_HEIGHT
FIT_PAGE

public void setInitialPdfExactZoom(double value)

value specifies the initial page zoom of the PDF when opened.

public void setPdfScalingFactor(double value)

The scaling factor used to convert between HTML and PDF. The default value is 1.0.

public void setPageBackgroundColor(String value)

The page background color in RRGGBB hexadecimal format.

public void setTransparentBackground(boolean value)

Does not print the body background. Requires the following CSS rule to be declared:
body {background-color:rgba(255,255,255,0.0);}

public void setAuthor(String author)

Sets the author field in the created PDF.

Watermark

public void setWatermark(String url, String offset_x, String offset_y)

url is a public absolute URL of the watermark image (must start either with http:// or https://). The supported formats are PNG and JPEG. offset_x and offset_y is the watermark offset in units. The default offset is (0,0).

public void setWatermarkRotation(double angle)

Rotates the watermark by angle degrees.

public void setWatermarkInBackground(boolean value)

When value is set to true then the watermark is be placed in the background. By default, the watermark is placed in the foreground.

Miscellaneous

public void useSSL(boolean use_ssl)

Set to true to call the API over a secure connection. The default is false.

public int numTokens()

Returns the number of available conversion tokens in your account.

public void setMaxPages(int npages)

Prints at most npages pages.

public void setFailOnNon200(boolean value)

If value is true then the conversion will fail when the source URI returns 4xx or 5xx HTTP status code. The default is false.

class com.pdfcrowd.PdfcrowdError

Derived from RuntimeException. It is thrown when an error occurs. Use getMessage() method to get the error message.

Units

Page dimensions and margins can be specified in inches (in), millimeters (mm), centimeters (cm), or points (pt). If no units are specified, points are assumed. Examples: "210mm", "8.5in".