PDFreactor 8 Migration Guide

With PDFreactor 8 we are introducing the first major API change since PDFreactor 2. One major benefit of this change is that the new Java API is identical (with a few additions) to the newly introduced Java web service client API.

Using the Legacy Java API

Java integrators can still use the old API, however we highly recommend to migrate to the new API as soon as possible, since the old one will be removed in a future release of PDFreactor. To continue using the old legacy API, just change the package from

com.realobjects.pdfreactor

to

com.realobjects.pdfreactor.legacy

Migrating to the New API

The Configuration Object

The most obvious change is the introduction of the Configuration object. In previous versions of PDFreactor, you invoked all API methods on the PDFreactor instance, however this had some disadvantages like making the PDFreactor instance non-reusable. In PDFreactor 8, you just have to create one instance of PDFreactor. The instance only has a few API methods, like convert.

All settings and options are properties of the configuration and have to be set there. While most methods are the same as in previous versions of PDFreactor, some have changed. For example, instead of add-methods, getters are used to retrieve lists on which new entries can be added. Make sure to consult the API documentation.

Converting

To create a PDF or image, you now just have to call the convert method with the configuration as a single parameter, which also specifies the input document. PDFreactor automatically detects if you are converting an HTML string, a URL or binary data.

Retrieving the Result

The new convert(Configuration) method no longer returns the PDF as binary directly. It returns a Result object which not only contains the PDF as binary, but also other useful data such as the log.

There are additional convert methods, such as convert(Configuration, OutputStream) which writes the PDF directly in the specified OutputStream instead of returning it or convertAsBinary(Configuration) which returns the binary data directly instead of a Result object. Please make sure to read the API documentation and the PDFreactor manual (Chapter "Integration").

Examples

Below are simple examples in different programming languages that show how PDFreactor was used previously and how it is used now.

Java

Old API

PDFreactor pdfReactor = new PDFreactor();

// simple settings
pdfReactor.setAddBookmarks(true);
pdfReactor.setAddLinks(true);

// adding a user style sheet
pdfReactor.addUserStyleSheet("p { color: red }", null, null, null);

// create PDF and specify the document
byte[] pdf = pdfReactor.renderDocumentFromURL("http://www.realobjects.com");

New API

PDFreactor pdfReactor = new PDFreactor();
Configuration config = new Configuration();

// specify the document
config.setDocument("http://www.realobjects.com");

// simple settings
config.setAddBookmarks(true);
config.setAddLinks(true);

// adding a user style sheet
config.getUserStyleSheets().add(new Resource("p { color: red }", null));

// create PDF
Result result = pdfReactor.convert(config);
byte[] pdf = result.getDocument();

.NET

Old API

PDFreactor pdfReactor = new PDFreactor();

// simple settings
pdfReactor.SetAddBookmarks(true);
pdfReactor.SetAddLinks(true);

// adding a user style sheet
pdfReactor.AddUserStyleSheet("p { color: red }", "", "", "");

// create PDF and specify the document
byte[] pdf = pdfReactor.RenderDocumentFromURL("http://www.realobjects.com");

New API (Changed in version 8.1)

PDFreactor pdfReactor = new PDFreactor();
Configuration config = Configuration();

// specify the document
config.Document = "http://www.realobjects.com";

// simple settings
config.AddBookmarks = true;
config.AddLinks = true;

// adding a user style sheet
config.UserStyleSheets = new List<Resource> {new Resource("p { color: red }", "")};

// create PDF
Result result = pdfReactor.Convert(config);
byte[] pdf = result.Document;

PHP

Old API

$pdfReactor = new PDFreactor();

// simple settings
$pdfReactor->setAddBookmarks(true);
$pdfReactor->setAddLinks(true);

// adding a user style sheet
$pdfReactor->addUserStyleSheet("p { color: red }", "", "", "");

// create PDF and specify the document
$result = $pdfReactor->renderDocumentFromURL("http://www.realobjects.com");

New API

$pdfReactor = new PDFreactor();
$config = array(
    // specify the document
    "document" => "http://www.realobjects.com",
    
    // simple settings
    "addBookmarks" => true,
    "addLinks" => true,
    
    // adding a user style sheet
    "userStyleSheets" => array(
        array(
            "content"=> "p { color: red }"
        )
    )
);

// create PDF
// ...as base64 encoded String
$result = $pdfReactor->convert($config);
$pdf = $result->document;

// ...as binary
$pdf = $pdfReactor->convertAsBinary($config);

To convert the base64 encoded document into binary data, you can do the following:

echo base64_decode($result->document);

Python

Old API

pdfReactor = PDFreactor()

# simple settings
pdfReactor.setAddBookmarks(True)
pdfReactor.setAddLinks(True)

# adding a user style sheet
pdfReactor.addUserStyleSheet("p { color: red }", "", "", "")

# create PDF and specify the document
result = pdfReactor.renderDocumentFromURL("http://www.realobjects.com");

New API

pdfReactor = PDFreactor()
config = {
    # specify the document
    'document': "http://www.realobjects.com",
    
    # simple settings
    'addBookmarks': True,
    'addLinks': True,
    
    # adding a user style sheet
    'userStyleSheets': [
        {
            'content': "p { color: red }"
        }
    ]
}

# create PDF
# ...as base64 encoded String
result = pdfReactor.convert(config)
pdf = result['document']

# ...as binary
pdf = pdfReactor.convertAsBinary(config)

To convert the base64 encoded document into binary data, you can do the following:

import base64
print(base64.b64decode(result['document']))

Ruby

Old API

pdfReactor = PDFreactor.new();

# simple settings
pdfReactor.setAddBookmarks(true)
pdfReactor.setAddLinks(true)

# adding a user style sheet
pdfReactor.addUserStyleSheet("p { color: red }", "", "", "")

# create PDF and specify the document
result = pdfReactor.renderDocumentFromURL("http://www.realobjects.com")

New API

pdfReactor = PDFreactor.new()
config = {
    # specify the document
    document: "http://www.realobjects.com",
    
    # simple settings
    addBookmarks: true,
    addLinks: true,
    
    # adding a user style sheet
    userStyleSheets: [
        {
            content: "p { color: red }"
        }
    ]
}

# create PDF
# ...as base64 encoded String
result = pdfReactor.convert(config)
pdf = result["document"]

# ...as binary
pdf = pdfReactor.convertAsBinary(config)

To convert the base64 encoded document into binary data, you can do the following:

require "base64"
print Base64.decode64(result["document"])

Perl

Old API

my $pdfReactor = PDFreactor -> new();

# simple settings
$pdfReactor -> setAddBookmarks('true');
$pdfReactor -> setAddLinks('true');

# adding a user style sheet
$pdfReactor -> addUserStyleSheet("p { color: red }", "", "", "");

# create PDF and specify the document
$result = pdfReactor -> renderDocumentFromURL("http://www.realobjects.com");

New API

my $pdfReactor = PDFreactor -> new();
$config = {
    # specify the document
    'document' => "http://www.realobjects.com",
    
    # simple settings
    'addBookmarks' => 'true',
    'addLinks' => 'true',
    
    # adding a user style sheet
    'userStyleSheets' => [
        {
            'content' => "p { color: red }"
        }
    ]
};

# create PDF
# ...as base64 encoded String
$result = $pdfReactor -> convert($config);
$pdf = $result->{'document'};

# ...as binary
$pdf = $pdfReactor -> convertAsBinary($config);

To convert the base64 encoded document into binary data, you can do the following:

use MIME::Base64 ();
print MIME::Base64::decode($result->{'document'});