PDFreactor Migration Guide

Migrating from PDFreactor 10.0 to PDFreactor 10.1

config.setSecuritySettings(new SecuritySettings()
    .setAllowExternalXmlParserResources(true)
    .setDefaults(new SecurityDefaults()
        .setAllowFileSystemAccess(true)));

Migrating from PDFreactor 9 to PDFreactor 10

config.setCssSettings(new CssSettings().setValidationMode(CssPropertySupport.ALL));

svg, canvas, img, object, embed {
    -ro-rasterization-max-size: none;
}

svg, canvas, img, object, embed {
    -ro-rasterization-max-size: 3.5;
}

roMjPath = "";              // default: "",
                            // examples: "MathJax/", "../../resource/js/mathjax/",
                            // "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/"
roMjFile = "MathJax.js";    // default: "MathJax.js",
                            // examples: "mathjax.js", "mathjaxmod.js"
roMjSvgBlacker = 0;         // default: 0,
                            // examples: 1, 2

document.documentElement.firstElementChild.insertAdjacentHTML('beforeend',
    '\u003Cscript type="text/x-mathjax-config">MathJax.Hub.Config(' +
    JSON.stringify({
        jax: ["input/MathML", "output/SVG"],
        extensions: ["mml2jax.js"],
        MathML: { extensions: ["content-mathml.js"] },
        SVG: { blacker: (typeof window.roMjSvgBlacker == "number" &&
            window.roMjSvgBlacker > 0 ? window.roMjSvgBlacker : 0) }
    }) +
    ');\u003C/script>\n' +
    '\u003Cscript type="text/javascript" src="' +
    (window.roMjPath ? window.roMjPath : "MathJax/") +
    (window.roMjPath && !(window.roMjPath + "").endsWith("/") ? "/" : "") +
    (window.roMjFile ? window.roMjFile : "MathJax.js") +
    '">\u003C/script>'
);

try {
    pdfReactor.convert(config);
} catch (PDFreactorException e) {
    // ...
} catch (IOException e) {
    // ...
} catch (SAXException e) {
    // ...
} catch (TransformerException e) {
    // ...
}

pdfReactor.convert(config, function(result) {
    processResult(result);
}, function(error) {
    processError(error);
});

try {
    const result = await pdfReactor.convert(config);
    processResult(result);
} catch (error) {
    processError(error);
}

config.setJavaScriptMode(true);

config.setJavaScriptSettings(
  new JavaScriptSettings().setEnabled(true));

config.setEnableDebugMode(true);

config.setDebugSettings(
  new DebugSettings().setAll(true));

config.setAppendLog(true);

config.setDebugSettings(
  new DebugSettings().setAppendLogs(true));

config.setResourceRequestTimeout(
          Integer);

config.setResourceReadTimeout(Integer);
config.setResourceConnectTimeout(Integer);

config.setDEfaultColorSpace(
  ColorSpace);

config.setColorSpaceSettings(
  new ColorSpaceSettings().setTargetColorSpace(
    ColorSpace));

content: string(namedString, last-except);

content: string(namedString, first-except);

Updated default HTML styles

With PDFreactor 9 some of the standard HTML styles have been edited to be more in line with the HTML5 specification and modern browsers. While most changes are cosmetic, some will influence the layouts of existing documents. When these have a negative impact on existing documents and adapting the print styles accordingly is to complex, the following snippets can be used to undo the most significant changes:

Page Margin

The default page margins were increased from 1cm to 2cm.

@page {
    margin: 1cm;
}

Body Margin

In previous versions of PDFreactor the default margins of body elements were 8px, in accordance to the HTML specification. As these default margins are only useful in non-paged environments they were dropped in PDFreactor 9.

body {
    margin: 8px;
}

For this to take effect in multi-page documents the following snippet has to be applied as well.

Box Decoration Break

The default value of the property box-decoration-break is now slice, as per the specification. The margin, padding and border-width values around page break will be treated as 0.

* {
    box-decoration-break: clone;
}

Rounding Mode

The default value of the proprietary property -ro-rounding-mode is now floor. This avoids rare cases where accumulated rounding imprecisions could lead to unexpected layout results, but may lead to different line and page-breaks.

html {
    -ro-rounding-mode: round;
}

First Page Side

The default side of first pages has changed from left to recto (i.e. right, unless the document direction is right-to-left), as per the specification.

@-ro-preferences {
    first-page-side: left;
}

Margins after Breaks

The top margins of blocks at the start of pages and columns are no longer set to 0 for first pages and columns or after forced breaks. This matches the behavior of browsers and the requirements of the latest CSS specifications.

html {
    -ro-truncate-margin-after-break: always;
}

However, in most cases it is advisable to apply non-proprietary styles, that result in the same improvement in browsers.

h1 {
    break-before: page;
    margin-top: 0;
}

div.multiColumn > *:first-child {
    margin-top: 0;
}

API Changes

The package of the ExceedingContent class has been changed from

com.realobjects.pdfreactor.exceedingcontent

to

com.realobjects.pdfreactor.contentobserver

Deprecated API

Java

The method setDocument(Object) is obsolete, use setDocument(String), setDocument(byte[]) or setDocument(InputSource) instead. This only affects the non-wrapper Java library.

Java and Java Wrapper

Constructors of inner Configuration classes (except for the KeyValuePair class) that take multiple arguments have been deprecated and will be removed in a future version. Use the no-argument constructor in conjunction with individual setters instead. An exception is the KeyValuePair class whose multi-argument constructor is not deprecated. Setters now return an instance of the class, thus allowing you to chain multiple subsequent setter calls. The following example demonstrates using no-argument constructors and chainable setters by adding a user script and a user style sheet to a Configuration instance:

Old API

config.setUserScripts(new ScriptResource(null, "http://myScript.js", false));
config.setUserStyleSheets(new Resource("p { color: red; }", null));

New API

config
    .setUserScripts(new ScriptResource().setUri("http://myScript.js"))
    .setUserStyleSheets(new Resource().setContent("p { color: red; }"));

.NET Wrapper

Multi-argument constructors are now obsolete in favor of object initializers.

Old API

config.UserScripts.Add(new ScriptResource(null, "http://myScript.js", false));
config.UserStyleSheets.Add(new Resource("p { color: red; }", null));

New API

config.UserScripts.Add(new ScriptResource { Uri = "http://myScript.js" });
config.UserStyleSheets.Add(new Resource { Content = "p { color: red; }" });

PHP Wrapper

The PDFreactor PHP classes are now located in the namespace com\realobjects\pdfreactor\webservice\client\. To adjust your integration, just add appropriate use directives like this:

use com\realobjects\pdfreactor\webservice\client\PDFreactor as PDFreactor;
use com\realobjects\pdfreactor\webservice\client\LogLevel as LogLevel;
use com\realobjects\pdfreactor\webservice\client\ViewerPreferences as ViewerPreferences;
...

All APIs

The configuration properties mergeByteArray, mergeByteArrays, mergeURL and mergeURLs are now obsolete. Use mergeDocuments instead. Note that mergeDocuments takes one or more Resource objects, so you have to use the appropriate properties of that object, either data for binary data or uri for URLs. Java example:

Old API

// merge single document from binary source
config.setMergeByteArray(byteArray1);
// merge multiple documents from binary source
config.setMergeByteArrays(byteArray1, byteArray2);
// merge single document from URL source
config.setMergeByteURL(url1);
// merge multiple documents from URL source
config.setMergeByteURLs(url1, url2);

New API

// merge single document from binary source
config.setMergeDocuments(new Resource().setData(byteArray1));
// merge multiple documents from binary source
config.setMergeDocuments(new Resource().setData(byteArray1),
        new Resource().setData(binary2));
// merge single document from URL source
config.setMergeDocuments(new Resource().setUri(url1));
// merge multiple documents from URL source
config.setMergeDocuments(new Resource().setUri(url1),
        new Resource().setUri(url2)));

The ScriptResource type is now deprecated, use Resource instead. This change only affects Java and .NET APIs.

Java and .NET wrappers

When using either the Java or .NET wrapper APIs, your integration has to be adjusted. These wrapper APIs are now based on the REST API rather than the SOAP API. This was done to provide an API that is more in line with the other wrapper APIs.

PDFreactor Web Service settings

When using the PDFreactor Web Service with custom settings in the "pdfreactorwebservice.vmoptions" file, you have to migrate these settings to the "start.ini" located in the "PDFreactor/jetty" directory.

If your "pdfreactorwebservice.vmoptions" looked like this

-Xmx1024m
-Djava.awt.headless=true

you have to add the lines from your "pdfreactorwebservice.vmoptions" to the end of your "start.ini" file

--exec
-Dorg.apache.cxf.Logger=org.apache.cxf.common.logging.Slf4jLogger
-Dcom.realobjects.interceptConsoleOutput=true
# old pdfreactorwebservice.vmoptions settings
-Djava.awt.headless=true
-Xmx1024m

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

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("https://www.realobjects.com");

New API

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

// specify the document
config.setDocument("https://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("https://www.realobjects.com");

New API (Changed in version 8.1)

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

// specify the document
config.Document = "https://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("https://www.realobjects.com");

New API

$pdfReactor = new PDFreactor();
$config = array(
    // specify the document
    "document" => "https://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("https://www.realobjects.com");

New API

pdfReactor = PDFreactor()
config = {
    # specify the document
    'document': "https://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("https://www.realobjects.com")

New API

pdfReactor = PDFreactor.new()
config = {
    # specify the document
    document: "https://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("https://www.realobjects.com");

New API

my $pdfReactor = PDFreactor -> new();
$config = {
    # specify the document
    'document' => "https://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'});