dl java interface - datalogics1.2 datalogics java interface user guide an introduction to the java...

Datalogics®

User Guide

DL Java Interface

DatalogicsD A T A L O G I C S J A V A I N T E R F A C E

User Guide

This guide is part of the Adobe PDF Library v6.1.1 suite; 11/30/04.Copyright 1999-2004 Datalogics Incorporated. All Rights Reserved. Use of Datalogics software is subject to the applicable license agreement.

Datalogics Java Interface is a trademark of Datalogics Incorporated. Other products mentioned herein as Datalogics products are also trademarks or registered trademarks of Datalogics, Incorporated.Adobe, Adobe PDF Library, Portable Document Format (PDF), PostScript, Acrobat, Distiller, Exchange and Reader are trademarks of Adobe Systems Incorporated.Microsoft, Windows and Windows NT are trademarks or registered trademarks of Microsoft Corporation.IBM, AIX, AS/400, OS/400, MVS, and OS/390 are registered trademarks of International Business Machines. HP and HP-UX are registered trademarks of Hewlett Packard Corporation.SAS/C is a registered trademark of SAS Institute Inc.Java, J2EE, J2SE, J2ME, all Java-based marks, Sun and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.UNIX is a registered trademark of The Open Group.Linux is a registered trademark of Linus Torvalds.All other trademarks and registered trademarks are the property of their respective owners.

For additional information, contact:

Datalogics, Incorporated101 North Wacker Drive, Suite 1800Chicago, Illinois 60606-7301

Phone: 312-853-8200Fax: 312-853-8282

[email protected]

Table of Contents

C o n t e n t s . i

1 Getting Started 1.1

An Introduction to the Java Interface 1.2

What You Should Know 1.2

How to Use this Book 1.3

2 Overview of the Java Interface 2.1

Requirements 2.2

What’s in the package 2.2

Installation 2.3

3 Samples Building and Running 3.1

Building Sample Programs 3.2

Running Sample Programs 3.2

4 Packages and Method Translation 4.1

Packages 4.2

Method Translation 4.2

5 Exceptions and Error Handling 5.1

PDFLException Handling 5.2

C o n t e n t s . i i D a t a l o g i c s J a v a I n t e r f a c e U s e r G u i d e

1
Getting Started
This chapter introduces the Datalogics Java Interface.

1.1

1 . 2 Datalogics Java Interface User Guide

An Introduction to the Java Interface

The Datalogics Java Interface provides a Java-language wrapper to the Adobe PDF Library to facilitate

the rapid creation of PDF documents via Java calls.

The Adobe PDF Library is C-based, not Java-sourced, but as it is usable by any application type which

supports calls to a C-based library, the Datalogics Java Interface has been created.

For information on the various layers of Adobe PDF Library please see the Acrobat Core API Overview.

What You Should Know

This document is intended for programmers who are familiar with the Java language, text composition

and the creation of output drivers, or by application designers who are constructing an application based

on the Adobe PDF Library.

You should have access to the Adobe PDF Library Applications Programming Interface (API) manual and

the Adobe PDF Specifications manual for your system. You should find these documents provided within

your release, accessible via the referencelibrary.pdf document using the copy of Adobe Reader

provided (or any other PDF viewer utility).

For Adobe PDF Library v5.x releases, Adobe PDF Specification 1.4 is appropriate. For Adobe PDF

Library v6.x releases, Adobe PDF Specification 1.5 is appropriate.

The explanations, assumptions and samples provided in this guide refer to Adobe PDF Library v6.1.1Plus

and DLI v3.0.19 or higher.

NOTE: Current releases of the Java Interface do not include Datalogics Interface (DLI)

methods. These may be added in the future.

NOTE: Some structures permitted in Adobe PDF Specification 1.5 may not be

permitted in Adobe PDF Specification 1.4, and some structures defined in Adobe

PDF Specification 1.4 are not available in Adobe PDF Specification 1.3.

G e t t i n g S t a r t e d 1 . 3

How to Use this Book

This book has been created to guide you through the process of creating PDF documents with the

Datalogics Java Interface.

This chapter, Getting Started, outlines the chapters to follow, explains the document conventions used

here, and lists other related documentation which you may find useful for your work. Follow-on chapters

will outline the the steps needed to create PDF and introduce the Java Interface in relation to the Adobe

PDF Library, explain the methods used and how they fit together, and provide various samples.

The following list provides an outline of the chapters as well as a brief description of their contents. Click

on each Chapter title below to jump to its first page.

Chapter 1: "Getting Started" (This chapter) This introduces the Java Interface and describes the

contents of this book.

Chapter 2: "Overview of the Java Interface" gives a general explanation of the Java Interface to

the Adobe PDF Library.

Chapter 3: "Samples Building and Running" describes the accompanying Java Interface sample

applications.

Chapter 4: "Packages and Method Translation" discusses package and method handling within

the Java Interface.

Chapter 5: "Exceptions and Error Handling" outlines the expected mechanism for catching and

dealing with returned exceptions, which should be added to your application.


D o c u m e n t C o n v e n t i o n s

The terms note, link and bookmark are used in this book the same way they are in the user interface of

Adobe PDF Library v6.x.xPlus®, Acrobat®, Acrobat Exchange® and Adobe Reader®. These correspond

to the text annotation, link annotation and routine entry structures (respectively) that appear in a PDF

file. See the Portable Document Format Reference Manual for a description of the PDF file format.

The following documentation conventions appear throughout the manual to help you differentiate regular

text from product and program names, and to distinguish command syntax.

• Product and program names are set in italic type.

• Multi-line examples are separated from the text and set in

Courier monospace

• Directory names and filenames are contained within the text and set in Courier monospace.

• Commands are contained within the text and set in Courier monospace.

• New terms are italicized.

• Page numbers in this book do not correspond to page numbers in the PDF file. The numbering scheme

(e.g. 4.1 or A.10) indicates the chapter number (4) or appendix letter (A) first, followed by the page

number (1 or 10), separated by a period.

R e l a t e d D o c u m e n t a t i o n

The following documents will be useful in developing applications using DLI.

Datalogics Resources

Adobe PDF Library and DLI Installation Guide This document describes the installation

requirements for using the Adobe PDF Library and DLI on the various platforms to which Datalogics has

ported these products.

Adobe PDF Library Developer Overview This document is designed to aid developers with

incorporating the API calls for the Adobe PDF Library into their composition application.

DLI Implementation and Reference Guide This document details the Datalogics Interface, a

simplified interface to the COS Layer of the Adobe PDF Library.

Java Interface User Guide (This book) This document details the Datalogics Java Interface, a Java-

language wrapper interface to the Adobe PDF Library and DLI.

G e t t i n g S t a r t e d 1 . 5

Adobe Resources

The following documents are distributed by Adobe as part of the original Adobe PDF Library release, and

are redistributed by Datalogics without alteration. These and other documents may also be found on the

Adobe website at http://partners.adobe.com/asn/acrobat/technotes.jsp. (Descriptions

below are provided by Adobe as part of their original accompanying readme.txt file.)

Portable Document Format Reference Manual This document describes PDF Standard 1.5

specifications. The latest version may be found at http://partners.adobe.com/asn/tech/pdf/

specifications.jsp.

Adobe PDF Library Overview Technical Note #5189 provides background information and

development information for the Adobe PDF Library. Read this document before beginning development

for information such as supported platforms, known issues and development requirements.

Acrobat Core API Overview Technical Note #5190 provides an overview of the Acrobat API in

general. It covers information applicable to both Plug-in development and Library development. Read this

document to obtain an understanding of how the Acrobat API is organized.

AcroColor API Reference Technical Note #5425 explains the Host Function Table (HFT) that

allows you to access the AcroColor Engine (ACE), which controls color profile.

Acrobat Core API Reference Technical Note #5191 is the reference manual for all of the Acrobat

API methods made available by the Acrobat Viewer. It documents the parameters, return values and

availability of each method, as well as specific implementation notes. This document is useful while

developing with the Adobe PDF Library or planning development to determine method availability and

capabilities.

PDF Library Supplement to the Acrobat Core API Technical Note #5414 complements the

Acrobat Core API Reference and is specific to the Adobe PDF Library API methods. This is an important

and useful document for all Adobe PDF Library developers.

NOTE: Adobe Solutions Network (ASN) membership may be required in order to

access some material on the Adobe website. See http://

partners.adobe.com/asn/programs/developer/index.jsp for

more details.

NOTE: Adobe also provides an accompanying errata file for this manual, with last-

minute updates and corrections. One copy is provided with this documentation

(see your documentation file folder), and you can check for newer copies at

http://partners.adobe.com/public/developer/en/pdf/

errata.txt

http://partners.adobe.com/asn/acrobat/technotes.jsp

http://partners.adobe.com/asn/programs/developer/index.jsp

http://partners.adobe.com/asn/programs/developer/index.jsp

http://partners.adobe.com/asn/tech/pdf/specifications.jsp

http://partners.adobe.com/asn/tech/pdf/specifications.jsp

http://partners.adobe.com/public/developer/en/pdf/errata.txt

http://partners.adobe.com/public/developer/en/pdf/errata.txt

2
Overview of
the Java Interface

The Java Interface functions independently of the Adobe

PDF Library as a wrapper making calls to it, as opposed

to being a layer within it. That is, you can modify your

Java code without disturbing the Library code, and

update the Library release without needing to modify the

Java calls.

2.1


Requirements

For the Datalogics Java Interface itself, JRE v1.3 or higher is required. For the supported platform and

operating-system requirements, please see either the accompanying Adobe PDF Library and DLI

Installation Guide or the Adobe PDF Library System Requirements page of the Datalogics website at

http://www.datalogics.com/pdflibrary-requirements.asp

What’s in the package

~ \ l i b

• PDFLJNI.jar (Java classes)

~ \ s r c \ c o m \ d a t a l o g i c s \ s a m p l e s

• Addelem.java

• Addimage.java

• Bookmark.java

• Fontembd.java

• Flattener.java

• Gettext.java

• Helowrld.java

• Makepath.java

• Mergepdf.java

• MyPDFLLibApp.java

• Printpdf.java

• Refcount.java

• Textextr.java

• Thumbs.java

• Unfilterimage.java

http://www.datalogics.com/pdflibrary-requirements.asp

O v e r v i e w o f t h e J a v a I n t e r f a c e 2 . 3

~ \ b i n

• PDFLJNI.dll (JNI interface program)

~ \ @ d a t a

Input files for sample programs

~ \ d o c

Java documentation

Installation

Installation of the Java Interface is fairly straightforward. As it is primarily a wrapper for the Adobe PDF

Library, we recommend that you complete installation of the Adobe PDF Library (and DLI, if applicable)

first, and build one or more sample applications first to verify that the installation ran correctly, before

proceeding with the Java Interface installation. Specifics for certain platform installations follow below.

O S / 4 0 0 I n s t a l l a t i o n

1 After logging in, type

===> STRPDM

Then type 1 to work with libraries.

2 Typically you will work in PDFL60P1B. Enter a 12 to display the objects in PDFL60P1B

3 One of the objects should be the PDFLJNI012 SAVF file that you sent via ftp from your PC. To verify

its condition, enter the command

===>CHGCURLIB PDFL60P1B

to verify what you are working with.

4 Next, restore the SAVF :

===> RSTOBJ


5 Because the SAVF was created in the library PDFLJNI012, fill out the fields for RSTOBJ as follows:

Restore Object (RSTOBJ)

Type choices, press Enter.

Objects . . . . . . . . . . . . > *ALL Name, generic*, *ALL

Saved library . . . . . . . . . > PDFLJNI012 Name

Device . . . . . . . . . . . . . > *SAVF Name, *SAVF, *MEDDFN

Object types . . . . . . . . . . *ALL *ALL, *ALRTBL, *BNDDIR...

Save file . . . . . . . . . . . > SAVJNI012 Name

Library . . . . . . . . . . . > PDFLJNI012 Name, *LIBL, *CURLIB

(You may need to press F10 to see the last two parameters)

Also PAGEDOWN and change the value for "Restore to library" if you wish the PDFLJNI

service program and IFSJNI012 SAVF file to go somewhere other then PDFLJNI012.


6 Type your choices and press Enter:

Date when saved . . . . . . . . Date

Time when saved . . . . . . . . Time

Allow object differences . . . . *NONE *NONE, *ALL, *FILELVL

Force object conversion:

Convert during restore . . . . *SYSVAL *SYSVAL, *NO, *YES

Objects to convert . . . . . . *RQD, *ALL

Restore to library . . . . . . . PDFL502P3A Name, *SAVLIB

Auxiliary storage pool ID . . . *SAVASP 1-32, *SAVASP

Output . . . . . . . . . . . . . *NONE *NONE, *PRINT, *OUTFILE

Additional Parameters

File to receive output . . . . . Name

Library . . . . . . . . . . . *LIBL Name, *LIBL, *CURLIB

This should yield two files: a PDFLJNI service program (the C++ native service program) and a SAVF

file named IFSJNI012, which contains the samples.


7 Now create the IFS directory where the samples will go. Start a qshell, Change Directory (cd) to the

top level directory, and use MKDIR:

===> QSH

QSH Command Entry

$

> cd /

$

===> mkdir APDFL-JNI-0.12

F3=Exit F6=Print F9=Retrieve F12=Disconnect

8 Once the directory is created, press F3 to exit. This should return you to the Work with Objects

screen.


9 Use the RST command to install the samples.

Restore Object (RST)


Device . . . . . . . . . . . . . > '/QSYS.LIB/PDFLJNI012.LIB/IFSJNI012.FILE'

Objects:

Name . . . . . . . . . . . . . > '*'

Include or omit . . . . . . . > *INCLUDE *INCLUDE, *OMIT

New object name . . . . . . . *SAME

Directory subtree . . . . . . . *ALL *ALL, *DIR, *NONE, *OBJ

Output . . . . . . . . . . . . . *NONE

You should expect to get a message about security or permission changes.


10 At this point you should have everything in place and be ready to run some tests:

==> chgcurlib PDFL60P1B

As a good habit, make sure the new PDFLJNI service program is in your library list. It may be wise to

rename or remove any older PDFLJNI service programs to avoid confusion.

Work with Objects Using PDM S103HD4

Library . . . . . PDFL60P1B Position to . . . . . . . .

Position to type . . . . .

Type options, press Enter.

DLAPDFL60 *SRVPGM APDFL v6.1.0Plus P1b - PDFL Core

LIBASCII *SRVPGM CLE Libascii Service Program: Release 1.

PDFLJNI *SRVPGM CPPLE APDFL JNI v0.12 alpha service progra

EXTURI *MODULE CLE ADOBE

MYPDFLIBUT *MODULE CLE ADOBE

TEXTEXTR *MODULE CLE

CPP *FILE PF-SRC

H *FILE PF-SRC

More..


11 Now go into the QSH and cd to the samples directory:

===> QSH

> cd /APDFL-JNI-0.12/src/com/datalogics/samples

12 Build the samples. You can build them individually:

$

> javac -classpath "/APDFL-JNI-0.12/lib/PDFLJNI.jar:../src" MyPDFLLibApp.java Helowrld.java

$

or build them all at once:

$

> javac -classpath "/APDFL-JNI-0.12/lib/PDFLJNI.jar:../src" *.java

$

13 With that done, press F3 to return to working with objects on the main PDM screen:

===> cd "/APDFL-JNI-0.12/@data"

2 . 1 0 Datalogics Java Interface User Guide

14 Now run the sample:

===> JAVA<F4>

Run Java Program (JAVA)


Class file or JAR file . . . . . com.datalogics.samples.Helowrld

Parameters . . . . . . . . . . . *NONE

Classpath . . . . . . . . . . . /APDFL-JNI-0.12/lib/PDFLJNI.jar:../src

or

===> JAVA CLASS(com.datalogics.samples.Helowrld) CLASSPATH('/APDFL-JNI-0.12/lib

/PDFLJNI.jar:../src')

15 You will see the messages in the Java Shell display, and finally the message

Press End to end Enter

Java program completed Enter

and you will be returned to the screen that the Java command was entered on.

16 (Optional) Press F9, recall the command, change the Job Name and press Enter again.

O v e r v i e w o f t h e J a v a I n t e r f a c e 2 . 1 1

W i n d o w s I n s t a l l a t i o n

1 The Windows installation is distributed as an InstallShield product within a .ZIP file. Unzip the file to

locate and run the Setup.exe file.

2 The installation by default will install in the directory c:\Datalogics\DLJI, at the same directory

level as the default Adobe PDF Library and DLI locations (e.g. c:\Datalogics\APDFL6.1.1 and

c:\Datalogics\DLI respectively). You can relocate it elsewhere if desired.

3 After the InstallShield process has completed, you should find a tree structure of folders created under

c:\Datalogics\DLJI containing the installation files, including a collection of Java samples

corresponding to the original Adobe PDF Library sample application collection in

c:\Datalogics\APDFL6.1.1\samples

4 Move ~\bin\PDFLJNI.dll to someplace where it will be found, such as the Windows directory,

and test one or more of the Java samples to verify that your installation was successful. See the next

chapter for more details on command syntax for building and running sample applications.

2 . 1 2 Datalogics Java Interface User Guide

3
Samples
Building and Running

The Java Interface provides several samples written in

Java. We recommend verifying at least one Java sample

for proper installation and operation before proceeding

to build your own application.

3.1


Building Sample Programs

Change Directory to the \samples folder under the location where you installed your release, and issue

the javac command as shown:

cd […path here…]\src\com\datalogics\samplesjavac –classpath […path here…]\lib\PDFLJNI.jar [Java file]

Running Sample Programs

cd […path here…]\@data java –classpath […path here…]\lib\PDFLJNI.jar;[…path here…]\src com.datalogics.samples.sample

For example, if the programs were installed in c:\pdfljni, the command to run the Hello World

example would be:

cd c:\pdfljni\@datajava –classpath c:\pdfljni\lib\PDFLJNI.jar;c:\pdfljni\src com.datalogics.samples.Helowrld

4
Packages and
Method Translation

4.1


Packages

The Adobe PDF Library classes are in the packages com.datalogics.apdfl.jni.*.

The samples are in the package com.datalogics.apdfl.samples.

Method Translation

During development of the Datalogics Java Interface, the documented Adobe PDF Library methods and

structures were translated into their Java equivalents.

The central class is com.datalogics.apdfl.PDJNI. This class contains the methods that are

documented in the PDFL manual translated into their Java equivalents.

All of the methods in this class are public static. You do not need to instance this class.

C l a s s T r a n s l a t i o n s

Each Adobe PDF Library call was translated into a more object-oriented style. The specific process used

depended on the name of the original method parameter(s):

1 First, a translation was performed based on the first parameter. All methods that take a PDDoc were

added to the PDDoc class; all methods that require a PDPage as the first parameter were added to the

PDPage class, etc. The method signature was altered by removing the first parameter, removing the

first part of the name if it matched the parameter type, and changing the first letter to lower case.

For example:

PDPage PDDocCreatePage(PDDoc doc, int flags, ASFixedRect mediaBox);

was added to the PDDoc class as:

public PDPage createPage(int flags, ASFixedRect rect) throws PDFLException; 2 If the first translation was unsuccessful, the process attempted to find a class that matched the leading

characters of the method name. If a class was found, the class name was shortened and a static method

NOTE: Current releases of the Java Interface do not include Datalogics Interface (DLI)

methods. These may be added in the future.

P a c k a g e s a n d M e t h o d T r a n s l a t i o n 4 . 3

was added to the class:

For example:

PDDoc PDDocCreate();

was added to PDDoc class as:

public static PDDoc create();

R e t u r n e d P a r a m e t e r s

A holder class was substituted for any parameters that returned a value. There is a holder class that

corresponds to each Adobe PDF Library class, primitive type, and Java-supplied class. The holder

classes are named by appending “Holder” to the held Class Name (e.g. the holder for a String is

StringHolder).

Each holder class contains a public field named value. On return this field will contain the actual

object.

For example:

The Adobe PDF Library method:

Int PDWordGetString(PDWord word, char * buffer, int len);

was translated to:

(in class PDJNI)

public int PDWordGetString(PDWord word, StringHolder stringHolder);

(in class PDWord)

public int getString(StringHolder stringHolder);

On return, the string Holder.value will contain the string.

Holders for primitive and Java-supplied types are in package org.omg.CORBA (part of the standard

JDK).

5
Exceptions
and Error Handling

5.1


PDFLException Handling

All methods are declared to throw a PDFLException. You will be required to handle this exception.

This takes the place of DURING/HANDLER/END_HANDLER macros used in the Adobe PDF Library.

Index

A

Addelem.java 2.2Addimage.java 2.2Adobe PDF Library

Applications Programming Interface (API) manual 1.2

Classes 4.2Document Conventions 1.4Method and Structure Equivalents 4.2Methods

PDDocCreatePage 4.2PDWordGetString 4.3

Samples 4.2Adobe Reader 1.2, 1.4Adobe Technical Notes

#5189 (Adobe PDF Library Overview) 1.5#5190 (Acrobat Core API Overview) 1.5#5191 (Acrobat Core API Reference) 1.5#5414 (PDF Library Supplement to the Acrobat

Core API) 1.5#5425 (AcroColor API Reference) 1.5

B

Bookmark.java 2.2

C

Conventions, Document 1.4

D

Datalogics websiteSystem Requirements 2.2

Document Conventions 1.4

F

Flattener.java 2.2Fontembd.java 2.2

G

getString 4.3Gettext.java 2.2

H

Helowrld.java 2.2Holder classes 4.3

Package 4.3StringHolder 4.3value field 4.3

I

InstallationOS/400 2.3Windows 2.11

J

Java InterfaceClass Translations 4.2Code basis 1.2Contents 2.2

~\@data folder 2.3~\bin folder 2.3~\doc folder 2.3~\lib folder 2.2~\src\com\datalogicsamples folder 2.2

Documentation (folder) 2.3Exceptions and Error Handling 5.1How to Use this Book 1.3Input files for sample programs 2.3Installation 2.3

OS/400 2.3Windows 2.11

Intended Audience 1.2Introduction 1.2Java/Library code independence 2.1Method Translation 4.2Packages 4.2Related Documentation 1.4Requirements 2.2Samples 3.1What You Should Know 1.2

M

Makepath.java 2.2Mergepdf.java 2.2MyPDFLLibApp.java 2.2

I n d e x . i i D a t a l o g i c s J a v a I n t e r f a c e U s e r G u i d e

N

NotesASN membership may be required for Adobe

website access 1.5No DLI Methods in current releases 1.2, 4.2PDF Reference Manual errata file available for

download 1.5Structure Variations may exist between PDF 1.5

and earlier 1.2

P

PDDoc 4.2PDF

File format 1.4PDFLException 5.2PDFLJNI.dll 2.3PDFLJNI.jar 2.2PDJNI 4.3PDPage 4.2PDWord 4.3PDWordGetString 4.3Portable Document Format Reference Manual 1.4Printpdf.java 2.2

R

Refcount.java 2.2Resources

AdobeAcroColor API Reference 1.5Adobe Acrobat Core API Overview 1.5Adobe Acrobat Core API Reference 1.5Adobe PDF Library Overview 1.5Adobe PDF Library Supplement to the Acrobat

Core API 1.5Portable Document Format Reference

Manual 1.5Errata file 1.5

DatalogicsAdobe PDF Library Developer Overview 1.4Adobe PDF Library Installation Guide 1.4, 2.2DLI Implementation and Reference Guide 1.4Java Interface User Guide 1.4

S

Sample ProgramsBuilding 3.2Running 3.2

Hello World 3.2

T

Textextr.java 2.2Thumbs.java 2.2

U

Unfilterimage.java 2.2

V

value (Holder class public field) 4.3

W

WebsitesDatalogics

System Requirements 2.2

dl java interface - datalogics1.2 datalogics java interface user guide an introduction to the java...

Documents