StarO!ce 9 Server - PDF Converter
Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054 U.S.A.
Part No: 820–5898 Apr 2009 Copyright 2009 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, CA 95054 U.S.A. All rights reserved.
Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more U.S. patents or pending patent applications in the U.S. and in other countries. U.S. Government Rights – Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. This distribution may include materials developed by third parties. Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd. Sun, Sun Microsystems, the Sun logo, the Solaris logo, the Java Co!ee Cup logo, docs.sun.com, StarO"ce, Java, and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. or its subsidiaries in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc. The OPEN LOOK and SunTM Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering e!orts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun's licensees who implement OPEN LOOK GUIs and otherwise comply with Sun's written license agreements. Products covered by and information contained in this publication are controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical or biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities identi#ed on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited. DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.
Copyright 2009 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, CA 95054 U.S.A. Tous droits réservés. Sun Microsystems, Inc. détient les droits de propriété intellectuelle relatifs à la technologie incorporée dans le produit qui est décrit dans ce document. En particulier, et ce sans limitation, ces droits de propriété intellectuelle peuvent inclure un ou plusieurs brevets américains ou des applications de brevet en attente aux Etats-Unis et dans d'autres pays. Cette distribution peut comprendre des composants développés par des tierces personnes. Certaines composants de ce produit peuvent être dérivées du logiciel Berkeley BSD, licenciés par l'Université de Californie. UNIX est une marque déposée aux Etats-Unis et dans d'autres pays; elle est licenciée exclusivement par X/Open Company, Ltd. Sun, Sun Microsystems, le logo Sun, le logo Solaris, le logo Java Co!ee Cup, docs.sun.com, StarO"ce, Java et Solaris sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc., ou ses #liales, aux Etats-Unis et dans d'autres pays. Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC International, Inc. aux Etats-Unis et dans d'autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc. L'interface d'utilisation graphique OPEN LOOK et Sun a été développée par Sun Microsystems, Inc. pour ses utilisateurs et licenciés. Sun reconnaît les e!orts de pionniers de Xerox pour la recherche et le développement du concept des interfaces d'utilisation visuelle ou graphique pour l'industrie de l'informatique. Sun détient une licence non exclusive de Xerox sur l'interface d'utilisation graphique Xerox, cette licence couvrant également les licenciés de Sun qui mettent en place l'interface d'utilisation graphique OPEN LOOK et qui, en outre, se conforment aux licences écrites de Sun. Les produits qui font l'objet de cette publication et les informations qu'il contient sont régis par la legislation américaine en matière de contrôle des exportations et peuvent être soumis au droit d'autres pays dans le domaine des exportations et importations. Les utilisations #nales, ou utilisateurs #naux, pour des armes nucléaires, des missiles, des armes chimiques ou biologiques ou pour le nucléaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou réexportations vers des pays sous embargo des Etats-Unis, ou vers des entités #gurant sur les listes d'exclusion d'exportation américaines, y compris, mais de manière non exclusive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une façon directe ou indirecte, aux exportations des produits ou des services qui sont régis par la legislation américaine en matière de contrôle des exportations et la liste de ressortissants spéci#quement designés, sont rigoureusement interdites. LA DOCUMENTATION EST FOURNIE "EN L'ETAT" ET TOUTES AUTRES CONDITIONS, DECLARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES, DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y COMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L'APTITUDE A UNE UTILISATION PARTICULIERE OU A L'ABSENCE DE CONTREFACON.
090529@22510 Contents
Preface ...... 5
1 Installation ...... 9 System Requirements ...... 9 Installing the StarO"ce 9 Server - PDF Converter ...... 10
2 Con"guring the StarO!ce 9 Server - PDF Converter ...... 13 Tomcat con#guration ...... 13 StarO"ce 9 Server - PDF Converter ...... 13
3 Startup and Shutdown ...... 15 Running StarO"ce 9 Server - PDF Converter ...... 15
4 Sample Code ...... 17 Sample JSP ...... 17 Sample Java Web Service client ...... 25
5 Web Service Speci"cation ...... 29 Web service overview ...... 29 Description of the API ...... 30 WSDL #le ...... 35
6 Application Server Integration ...... 39 WAR File ...... 39 Glass#sh V2 ...... 40 M To run the PDF Converter in a Glass#sh environment ...... 40
3 Contents
Shared libraries for Glass#sh ...... 40 Install the application for Glass#sh ...... 41 Apache Tomcat 6.0.16 ...... 42 M To run the PDF Converter in a Tomcat environment ...... 42 Shared libraries for Tomcat ...... 42 Install the application for Tomcat ...... 43 IBM Websphere 6.1 ...... 43 M To run the PDF Converter in an IBM Websphere environment ...... 44 Installing the application for Websphere ...... 44 Installing the shared libraries for Websphere ...... 47 Con#gure PDF Converter Application ...... 48 Con#gure Websphere Server ...... 50
A Appendix ...... 53
4 StarOf!ce 9 Server - PDF Converter • Apr 2009 Preface
The StarO"ce 9 Server - PDF Converter is a set of software tools which delivers documents in PDF #le format. The PDF #le format was designed by Adobe Systems Inc. as a general, read-only #le format for publishing documents. The StarO"ce 9 Server - PDF Converter runs on a #le server that can be accessed on the Internet or within a network system.
This book describes how to install and setup the StarO"ce 9 Server - PDF Converter.
An example implementation of a user interface is presented. When deploying the StarO"ce 9 Server - PDF Converter you most possibly will develop your own user interface.
Who Should UseThis Book The StarO"ce 9 Server - PDF Converter provides a #le conversion service on the Web or within a network system. Users will upload a document in a #le format known to StarO"ce 9, and get back a PDF #le of the same document. The converter is installed by a system administrator on a #le server. Some experience with installing software on the server system is needed and this book will not cover commands and procedures that a system administrator is expected to know.
BeforeYouReadThis Book As a system administrator, you should also read the OpenO!ce.org Administration Guide at http://wiki.services.openo"ce.org/wiki/Documentation/Administration_Guide. This guide has steps and tips for the installation of StarO"ce 9 on a #le server. The OpenO!ce.org Developer's Guide at http://wiki.services.openo"ce.org/wiki/Documentation/DevGuide contains information about the #le import #lters and the PDF export #lter, among others. I OpenO"ce.org Administration Guide I OpenO"ce.org Developer's Guide
5 Preface
RelatedThird-PartyWeb Site References
Third-party URLs are referenced in this document and provide additional, related information.
Note – Sun is not responsible for the availability of third-party web sites mentioned in this document. Sun does not endorse and is not responsible or liable for any content, advertising, products, or other materials that are available on or through such sites or resources. Sun will not be responsible or liable for any actual or alleged damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through such sites or resources.
Documentation, Support, andTraining
The Sun web site provides information about the following additional resources: I Documentation (http://www.sun.com/documentation/) I Support (http://www.sun.com/support/) I Training (http://www.sun.com/training/)
Typographic Conventions
The following table describes the typographic conventions that are used in this book.
TABLE P–1 Typographic Conventions
Typeface Meaning Example
AaBbCc123 The names of commands, #les, and directories, Edit your .login #le. and onscreen computer output Use ls -a to list all #les. machine_name% you have mail.
AaBbCc123 What you type, contrasted with onscreen machine_name% su computer output Password:
aabbcc123 Placeholder: replace with a real name or value The command to remove a #le is rm "lename.
6 StarO"ce 9 Server - PDF Converter • Apr 2009 Preface
TABLE P–1 Typographic Conventions (Continued) Typeface Meaning Example
AaBbCc123 Book titles, new terms, and terms to be Read Chapter 6 in the User's Guide. emphasized A cache is a copy that is stored locally. Do not save the #le. Note: Some emphasized items appear bold online.
Shell Prompts in Command Examples The following table shows the default UNIX® system prompt and superuser prompt for the C shell, Bourne shell, and Korn shell.
TABLE P–2 Shell Prompts
Shell Prompt
C shell machine_name%
C shell for superuser machine_name#
Bourne shell and Korn shell $
Bourne shell and Korn shell for superuser #
7 8 1C H A P T E R 1 Installation
The StarO"ce 9 Server - PDF Converter can run on any combination of hardware and operating system which is capable to support StarO"ce 9 and for which the Java Runtime Environment Version 1.5 is available.
Note – Some Sun Java Runtime Environment versions cause errors when used on the client side. (see Appendix)
The system support includes all versions of the Windows operating system (Windows 98, Windows 2000, Windows 2003, Windows XP,Windows NT, Windows Vista) as well as several Linux operating systems, the Solaris Operating Systems (for SPARC and x86 platforms), and Mac OS X.
System Requirements In detail the minimum operating system requirements are:
Microsoft Windows I Microsoft Windows: Windows 98, Windows ME, Windows NT (Service Pack 6), Windows 2000 (Service Pack 2), Windows 2003, Windows XP,Windows Vista I Pentium compatible PC I 1 GB RAM I 300 MB free space on hard drive
Linux I Linux kernel version 2.2.13 I Glibc2 version 2.2.0 I 1 GB RAM
9 Installing the StarO"ce 9 Server - PDF Converter
I Pentium compatible PC I 350 MB free space on hard drive
Note – StarO"ce 9 Server - PDF Converter cannot be installed on a (V)FAT partition
Solaris Operating System I Solaris 8 Operating System (SPARC or x86 platform edition) I 1 GB RAM I 350 MB free space on hard drive
Mac OS X Operating System I A recent Mac OS X 10 operating system I 1 GB RAM I 250 MB free space on hard disc
Installing the StarO!ce 9 Server - PDF Converter
Installation #le formats: I Microsoft Windows Microsoft Windows Installer format. Execute the setup.exe #le that is part of the product distributable. I Solaris Operating System Solaris Package format. Use Solaris Package Manager or execute the setup script that is part of the product distributable. I Linux RPM package format. Use the rpm command or execute the setup script that is part of the product distributable. I Mac OS X DMG package format. Open the dmg package to install the product by drag and drop.
The StarO"ce 9 Server - PDF Converter installer installs the following modules: I The StarO"ce Server Engine, which contains all core components needed to provide StarO"ce functionality as GUI-less services. I The StarO"ce Webservice Engine, which is essentially an installation of a customized version of Tomcat 5.
10 StarO"ce 9 Server - PDF Converter • Apr 2009 Installing the StarO"ce 9 Server - PDF Converter
I The StarO"ce 9 Server - PDF Converter Web Application. For Windows, Solaris, and Linux, it is contained in the directory
The default installation directory for the StarO"ce 9 Server - PDF Converter is as follows: I On Linux and Solaris Operating Systems: /opt/staroffice9pdfconverter I On Windows:
You can select any other directory for installation.
During runtime, StarO"ce 9 Server - PDF Converter needs to have write access to the following directories on Solaris, Linux and Windows:
I
During runtime, StarO"ce 9 Server - PDF Converter needs to have write access to the following directories on Mac OS X:
I
Chapter 1 • Installation 11 12 C2 H A P T E R 2 Con!guring the StarO"ce 9 Server - PDF Converter
After installation, you can con#gure the supplied Tomcat Web server and StarO"ce 9 Server - PDF Converter.
Tomcat con"guration For the con#guration of Tomcat see documentation on www.apache.org. Basic con#guration instructions can be found in the #le
StarO!ce 9 Server - PDF Converter The con#guration of the StarO"ce 9 Server - PDF Converter is speci#ed in the #le
The config.properties #le contains a number of entries of key-value-pairs, one line for each entry, which are described in the following:
I workdir This is the directory that is used by StarO"ce 9 Server - PDF Converter to store intermediate #les. Example: workdir=/tmp Default:
13 StarO"ce 9 Server - PDF Converter
I maxAge Every StarO"ce Server Engine instance has a certain lifetime, that is, number of conversions, the instance is allowed to do. After that number of conversions the converting instance is terminated automatically, and a fresh instance of the StarO"ce Server Engine is created. Example: maxAge=50 Default: 50 I maxLatency Describes the overall time in seconds, in which a conversion job must have #nished. If a conversion is not #nished in time, an error will be generated. Example: maxLatency=180 Default: 180 I converterServiceURL The URL for the StarO"ce 9 Server - PDF Converter Webservice. Example: converterServiceURL=http://localhost:8080/soserv/SOConverter Default: http://localhost:8080/soserv/SOConverter
14 StarO"ce 9 Server - PDF Converter • Apr 2009 C3 H A P T E R 3 Startup and Shutdown
During installation of StarO"ce 9 Server - PDF Converter several startup and shutdown scripts are installed in the directory
Running StarO!ce 9 Server - PDF Converter The StarO"ce 9 Server - PDF Converter requires a Java Runtime Environment in version 1.5. Ensure that the Java Runtime Environment binary is located in the application path or set an environment variable JAVA_HOME to point to a Java Runtime Environment 1.5. To test, whether the Java Runtime Environment is present and accessible, enter java -version in a terminal.
Startup and Shutdown Scripts I Microsoft Windows The startup/shutdown script is called soserv.bat. I Linux and Solaris Operating Systems The startup/shutdown script is called soserv.sh.
The startup/shutdown script does understand the command line parameters start and stop to start or stop the server.
15 16 C4 H A P T E R 4 Sample Code
As a web service, StarO"ce 9 Server - PDF Converter is mainly triggered by programming. In the following, you will #nd two example ways to use the web service and an overview of the service parameters.
Sample JSP A sample JSP #le for a PDF conversion web application can be found in
The following images show the parts of the web page from top to bottom.
File selector
Use the Browse button to select a #le to be converted, and click the Convert button to send the #le to the server for conversion. After conversion, a dialog opens, where you can choose to download or open the converted #le.
17 Sample JSP
General section
I Page Range Exports the pages that you type in the box. To export a range of pages, use the format, 3-6. To export single pages, use the format, 7;9;11. To export a combination of page ranges and single pages, use the format, 3-6;8;10;12. To export all of the pages, leave the box empty. I PDF/A-1 Export the document as PDF/A-1. This speci#cation stores all required information, for example fonts, in the #le. This is needed for archive documents and used in governmental environments. I Tagged PDF Write tags in the converted document. Some tags that are exported are table of contents, hyperlinks, and controls.
Note – The PDF/A-1 and Tagged PDF options can signi#cantly increase the #le size of the PDF document.
I Export notes Exports notes in Writer and Calc documents as PDF notes. I Use transition e!ects Converts an Impress slide transition e!ect to the equivalent PDF e!ect. I Create hybrid "le Hybrid #les are PDF documents with the original ODF document embedded.
18 StarO"ce 9 Server - PDF Converter • Apr 2009 Sample JSP
Images section
I Lossless compression Preserves all pixels in the original image. I JPEG compression Compresses the pixels in the original image. To preserve the appearance of the image, use the high quality setting. If you want to reduce the #le size, but with the risk of introducing #le artefacts, use the low quality setting. I Reduce image resolution Reduces the size of the image by reducing the number of pixels per inch. Use this option to select the target resolution for the converted images.
Encryption section
I Encrypt the PDF document Requires that you enter a password to open the converted PDF document. I Set open password / Con"rm Speci#es the password for the converted document. Enter the same password to con#rm.
Note – This option is only available when you select the Encrypt the PDF Document option.
Chapter 4 • Sample Code 19 Sample JSP
Permissions section
I Restrict permissions Sets the permissions for opening the converted document. I Set permission password / Con"rm Sets the password that you need to enter to change the restrictions of the PDF document.
Note – This option is only available when you select the Restrict permissions option.
I Printing Sets the printing permissions for the PDF document.
Note – This option is only available when you select the Restrict permissions option.
I Not permitted Does not allow you to print the PDF document. I Low resolution Allows you to print the PDF document only at a low resolution. I High resolution Allows you to print the PDF document in high resolution. I Changes
20 StarO"ce 9 Server - PDF Converter • Apr 2009 Sample JSP
Note – This option is only available when you select the Restrict permissions option.
I Not permitted Prevents changes to the PDF document. I Inserting, deleting and rotating pages Allows you to insert, delete, and rotate pages in the PDF document. I Filling in form "elds Allows you to type in form #elds in the PDF document. I Commenting, "lling in form "elds Allows you to add comments to the PDF document. I Any, except extracting pages Allows you to make changes to the PDF document, but does not allow you to extract pages. I Enable copying of content Allows you to copy the content of the PDF document.
Note – This option is only available when you select the Restrict permissions option.
I Enable text access for accessibility tools Allows you to access the text content of the PDF document with accessibility tools.
Note – This option is only available when you select the Restrict permissions option.
Initial View section
Chapter 4 • Sample Code 21 Sample JSP
I Panes Speci#es how the PDF document should be displayed when opened. I Page only Selects the default viewer mode, no outlines and no thumbnails. I Bookmarks and page The document is opened with the outline pane visible. I Thumbnails and page The document is opened with the thumbnails pane visible. I Open on page Enter the page number to open initially. I Magni"cation Speci#es the action to be performed when the PDF document is opened. I Default Opens with the default zoom magni#cation. I Fit in window Opens magni#ed to# t the entire page within the window. I Fit width Opens magni#ed to# t the entire page width within the window. I Fit visible Opens magni#ed to# t the entire width of the page bounding box within the window (cuts out margins). I Zoom factor
22 StarO"ce 9 Server - PDF Converter • Apr 2009 Sample JSP
Opens with the zoom level speci#ed. I Page layout Speci#es the page layout to be used when the document is opened. I Default Displays the pages according to the reader con#guration. I Single page Displays one page at a time. I Continuous Displays all pages in one column. I Continuous facing Displays the pages in two columns odd pages on the right. To display o!pages on the left side, the FirstPageOnLeft property should be set.
User interface section
I Window options Speci#es the behavior when the document is opened. I Resize window to initial page Speci#es that the PDF viewer window is opened full-screen when the document is opened. I Center window on screen Speci#es that the PDF viewer window is centered to the screen when the document is opened. I Open in fullscreen mode
Chapter 4 • Sample Code 23 Sample JSP
Speci#es that the PDF viewer window is opened full-screen, on top of all windows. I Display document title Speci#es that the title of the document, if present in the document properties, is displayed in the PDF viewer title bar. I User interface options Toggle viewer controls. I Hide menubar Speci#es whether to hide the PDF viewer menu bar when the document is active. I Hide toolbar Speci#es whether to hide the PDF viewer toolbar when the document is active. I Hide window controls Speci#es whether to hide the PDF viewer controls when the document is active. I Bookmarks Speci#es how many bookmark levels should be shown in the PDF viewer application when the document is opened. I All bookmark levels The document shows all available bookmarks. I Visible bookmark levels Speci#es the number of visible bookmark levels.
Links section
I Window options I Export bookmarks as named destinations Speci#es that the named bookmarks contained in the source ODF #le should be exported to the PDF #le as Named Destination (see PDF 1.4 section 8.2.1). I Convert document references to PDF targets
24 StarO"ce 9 Server - PDF Converter • Apr 2009 Sample JavaWeb Service client
Speci#es if bookmarks are exported to PDF. I Cross-document links Speci#es the way the exported PDF will be viewed by the user. I Default mode Speci#es that the PDF will be exported with all the links external to the document treated as URI. I Open with PDF reader application Speci#es that the PDF will be exported in order to be viewed through a PDF reader application only. Valid only if not exporting to PDF/A-1. I Open with Internet browser Speci#es that the PDF will be exported in order to be viewed through an Internet browser, using the PDF plug-in provided with it. The bookmark of the URI will be rendered compatible with the target bookmark generated with the PDF Export feature.
Sample JavaWeb Service client The main way to use the web service is by custom clients, embedded in specialized applications. It does not make sense to discuss every particular language binding here, but shown is the way to obtain a connection to the web service using the JAX-WS implementation of Web Services provided by Sun Microsystems.
The best way to create a JAX-WS client is to use Netbeans. Create a new #le with the “Web Service Client” template in Netbeans with the provided wsdl.
A client could look like the following. package soserverclient; import java.io.ByteArrayInputStream; import java.io.ByteArrayOutputStream; import java.io.File; import java.io.FileInputStream; import java.io.FileOutputStream; import java.io.InputStream; import java.io.UnsupportedEncodingException; import java.net.URLEncoder; import javax.xml.ws.BindingProvider; import javax.xml.ws.Holder; public class ConversionClient {
Chapter 4 • Sample Code 25 Sample JavaWeb Service client
String serviceURL="http://localhost:8080/soserv/SOConverter"; ConverterSEI converter = null; ConvertMime params = null;
/** Creates a new instance of ConversionClient */ public ConversionClient(String serviceUrl) { if (serviceUrl != null) serviceURL = serviceUrl;
try { converter = new Converter(wsdlLocation, new QName("urn:soserv:Converter/wsdl","Converter")).getConverterSEIPort(); ((BindingProvider)converter).getRequestContext().put( BindingProvider.ENDPOINT_ADDRESS_PROPERTY, serviceURL);
params = new ConvertMime(); params.setTargetType("PDF"); } catch (Throwable e) { System.out.println("caught exception: " + e.getClass().getName()); e.printStackTrace(); } }
/** * @param args the command line arguments */ public static void main(String[] args) { if (args.length < 2) {
System.out.println("usage: ConversionClient
String serviceUrl = null; if (args.length > 2) serviceUrl = args[2];
System.out.println("ConversionClient..."); ConversionClient dc = new ConversionClient(serviceUrl); dc.convertDocs(args[0], args[1] ); }
public void convertDocs(String input, String output) { File dir = new File(input);
String[] children = dir.list(); for (int i=0; i 26 StarO"ce 9 Server - PDF Converter • Apr 2009 Sample JavaWeb Service client = dir.getAbsolutePath() + File.separator + children[i]; File f = new File(childurl); if (f.isDirectory()) { File o = new File(output + File.separatorChar + children[i]); if (o.exists()) { // TODO: error handling } else { o.mkdir(); } convertDocs( childurl, output + File.separatorChar + children[i]); } else { String name = children[i].substring( 0, children[i].lastIndexOf(’.’)) + ".pdf"; File o = new File(output + File.separatorChar + name); convertDoc(f, o); } } } public void convertDoc(File input, File output) { try { System.out.print( "conversion of \"" + input.getAbsolutePath() + "\"... "); byte[] fileStream = getByteArray( input ); Holder // Important: If possible, supply original source file extension // with conversion request. Otherwiese, some input file formats // will not be recognized properly and conversion will fail. String options = createFileExtensionOption(input); if (options != null) params.setOptionString(options); ConvertMimeResponse response = converter.convertMime(params, mimeAttachment); InputStream in = new ByteArrayInputStream(mimeAttachment.value); FileOutputStream fout = new FileOutputStream(output); int n = 0; byte[] buf = new byte[4096]; while ((n = in.read(buf))!=-1) fout.write(buf, 0, n); Chapter 4 • Sample Code 27 Sample JavaWeb Service client fout.close(); String status = response.getStatus(); System.out.println("... done: status: " + status); } catch (Throwable e) { System.out.println("caught exception: " + e.getClass().getName()); e.printStackTrace(); } } private byte[] getByteArray(File file) throws Exception { ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream(); FileInputStream fin = new FileInputStream(file); byte[] buffer = new byte[16384]; for (int len = fin.read(buffer); len > 0; len = fin.read(buffer)) { byteArrayOutputStream.write(buffer, 0, len); } fin.close(); return byteArrayOutputStream.toByteArray(); } private static String createFileExtensionOption(File srcFile) { String ext = srcFile.getName(); int idx = ext.lastIndexOf(’.’); if (idx >= 0) { ext = ext.substring(idx+1); if (!ext.equals("")) { String options = "settings.sourceFileExtension="; try { options += URLEncoder.encode(ext, "UTF-8"); } catch (UnsupportedEncodingException e) { options += ext; } return options; } } return null; } } 28 StarO"ce 9 Server - PDF Converter • Apr 2009 C5 H A P T E R 5 Web Service Speci!cation StarO"ce 9 Server - PDF Converter exposes its interface as a SOAP [SOAP=http://www.w3.org/TR/soap/] web service. As such, the interface description is provided as a WSDL [WSDL=http://www.w3.org/TR/wsdl] #le. The schema of the messages exchanged by the SOAP interface are described in more detail below. Web service overview The interface has two main entry points: convert and convertMime. While the convert interface uses URLs or base64 encoded versions of the request and result #les, the convertMime interface uses the mime extensions of WSDL to transfer documents as binary attachments. The convert interface can also handle documents attached by the WS-I attachment pro#le, wherein an additional mime part is referenced by a cid: (content-id) URL See www.ws-i.org/Pro#les/AttachmentsPro#le-1.0.html Most language bindings will provide tools to generate language speci#c proxy classes from the WSDL descriptions, which can than be used to call the service in a client. Should an environment not provide such a binding, it is possible, to generate and parse the SOAP XML messages according to the SOAP and WSDL speci#cation and the message schema given as part of the WSDL #le. The WSDL can either be obtained from a running StarO"ce 9 Server - PDF Converter by appending ?WSDL to the service URL (for example, http://localhost:8080/soserv/SOConverter?WSDL) or directly from the StarO"ce 9 Server - PDF Converter installation, where it can be found at 29 Description of the API Description of the API Note – For StarO"ce 8 Server – PDF Converter Update 10 the API of the Conversion Webservice had to be changed. In case your client applications do not work any longer, you need to recompile the client applications using the current WSDL #le. To obtain the version of your StarO"ce 9 Server - PDF Converter installation, refer to the #le The XML that the StarO"ce 9 Server - PDF Converter uses to send and to receive requests from the server is de#ned in a WSDL# le. This #le contains de#nitions for the following elements. 1. 30 StarO"ce 9 Server - PDF Converter • Apr 2009 Description of the API I 1: inserting, deleting, rotating pages permitted. I 2: #lling in form #elds permitted. I 3: commenting permitted. I 4: any changes permitted, except extraction of content. I pdf.enableCopyingOfContent Values true or false, or omitted, default false, see Sample JSP.This property value is ignored unless pdf.restrictPermissions is set to true. I pdf.enableTextAccessForAccessibilityTools Values true or false, or omitted, default false, see Sample JSP.This property value is ignored unless pdf.restrictPermissions is set to true. I pdf.compression Possible values are lossless or jpeg, default is lossless. If the value is set to jpeg, the additional option. I pdf.jpegQuality is evaluated, which de#nes the JPEG compression of images. I pdf.tagged Values true or false, or omitted, default false, see Sample JSP. I pdf.archive Create PDF/A-1. Values true or false, or omitted, default false, see Sample JSP. I pdf.hybrid Values true or false, or omitted, default false, see Sample JSP. I pdf.exportNotes Values true or false, or omitted, default false, see Sample JSP. I pdf.useTransitions Values true or false, or omitted, default false, see Sample JSP. I pdf.reduceResolution Values true or false, or omitted, default false, see Sample JSP. I pdf.maxResolution A string that contains the maximum number of pixels per inch. I pageRange A string with a format that is described in Sample JSP. I pdf.isSkipEmptyPages Speci#es that automatically inserted empty pages are suppressed. This option is active only when storing Writer documents. I pdf.exportNotesPages Chapter 5 • Web Service Speci!cation 31 Description of the API Speci#es whether notes pages are exported to PDF. Notes pages are available in Impress only. I pdf.exportFormFields Speci#es whether form #elds are exported as widgets or only their #xed print representation is exported. I pdf.formsType Speci#es the submitted format of a PDF form. “0” –> Speci#es that forms type FDF is used. “1” –> Speci#es that forms type PDF is used. “2” –> Speci#es that forms type HTML is used. “3” –> Speci#es that forms type XML is used. I pdf.hideViewerToolbar Speci#es whether to hide the PDF viewer toolbar when the document is active. I pdf.hideViewerMenubar Speci#es whether to hide the PDF viewer menu bar when the document is active. I pdf.hideViewerWindowControls Speci#es whether to hide the PDF viewer controls when the document is active. I pdf.resizeWindowToInitialPage Speci#es that the PDF viewer window is opened full screen when the PDF document is opened. I pdf.centerWindow Speci#es that the PDF viewer window is centered to the screen when the PDF document is opened. I pdf.openInFullScreenMode Speci#es that the PDF viewer window is opened full-screen, on top of all windows. I pdf.displayPDFDocumentTitle Speci#es that the title of the document, if present in the document properties, is displayed in the PDF viewer title bar. I pdf.initialView Speci#es how the PDF document should be displayed when opened. “0” –> Select the default viewer mode, no outlines and no thumbnails. “1” –> The document is opened with the outline pane open. “2” –> The document is opened with the thumbnail pane open. I pdf.magnification Speci#es the action to be performed when the PDF document is opened. 32 StarO"ce 9 Server - PDF Converter • Apr 2009 Description of the API “0” –> Opens with default zoom magni#cation. “1” –> Opens magni#ed to #t the entire page within the window. “2” –> Opens magni#ed to #t the entire page width within the window. “3” –> Opens magni#ed to #t the entire width of its bounding box within the window (cuts out margins). “4” –> Opens with the zoom level speci#ed in the Zoom property. I pdf.zoom Speci#es the zoom level a PDF document is opened with. Only valid if Magni#cation is set to “4”. I pdf.initialPage Speci#es the page number on which a PDF document should be opened in the viewer application. I pdf.pageLayout Speci#es the page layout to be used when the document is opened. “0” –> Display the pages according to the reader con#guration. “1” –> Display one page at a time. “2” –> Display the pages in one column. “3” –> Display the pages in two columns, odd pages to the right. If you need odd pages to the left, the FirstPageOnLeft property should be set. I pdf.firstPageOnLeft Used with the value “3” of the PageLayout property, set to TRUE if the #rst page (odd) should be on the left side of the screen. I pdf.pdfViewSelection Speci#es the way the exported PDF document will be viewed. “0” –> The PDF will be exported with all links external to the document treated as URI. This is the default. “1” –> The PDF will be exported to be read by a PDF viewer application only. Valid only if not exporting to PDF/A-1. “2” –> The PDF will be exported to be viewed in an Internet browser, using the PDF plug-in provided with the browser. The bookmark of the URI will be rendered compatible with the target bookmark generated from the PDF Export feature (see ExportBookmarksToPDFDestination below). I pdf.convertOOoTargetToPDFTarget Speci#es that the target documents with an ODF# le name extension will be renamed to a PDF extension when the link is exported to PDF. The source document remains untouched. I pdf.exportBookmarksToPDFDestination Chapter 5 • Web Service Speci!cation 33 Description of the API Speci#es that the bookmarks contained in the ODF source# le should be exported to the PDF #le as Named Destination (see PDF 1.4 section 8.2.1). I pdf.exportBookmarks Speci#es if bookmarks are exported to PDF. I pdf.openBookmarkLevels Speci#es how many bookmark levels should be opened in the reader application when the PDF gets opened (default: –1). For language bindings that do not support the array structure of the option element, you can use the optionString element. This element takes a string encoded form of the options array. The encoding is similar to that of an HTTP query, that is, opt_name1=value1&opt_name2=value2&... If both an array of option elements and an optionString are in a message, the content of the optionString element is ignored and the values of the option elements are used. 2. Contains the I ERROR_UNEXPECTED = -1 I ERROR_OPEN = 1 I ERROR_PROCESS = 2 I ERROR_EXPORT = 3 I ERROR_POSTPROCESS = 4 I ERROR_LICENSE = 5 I ERROR_MULTI_FILE_RESULT = 6 34 StarO"ce 9 Server - PDF Converter • Apr 2009 WSDL !le Note – Only ERROR_OPEN, cannot read the document, is currently relevant to a user. 7. The above elements are then used to de#ne the messages “convertRequest”, “convertMimeRequest” which also contains a base64Binary de#ning the source document, “convertResponse”, “convertMimeResponse”, and “conversionError”. WSDL "le Chapter 5 • Web Service Speci!cation 35 WSDL !le 36 StarO"ce 9 Server - PDF Converter • Apr 2009 WSDL !le Chapter 5 • Web Service Speci!cation 37 WSDL !le 38 StarO"ce 9 Server - PDF Converter • Apr 2009 C6 H A P T E R 6 Application Server Integration The StarO"ce 9 Server - PDF Converter uses its own Tomcat web server to provide the converter functionality, but it is also possible to run the StarO"ce 9 Server - PDF Converter in an already installed application server environment. To work with an already installed application server attention should be paid to the following elements: I The config.properties #le in the war #le. I The native libraries used by the StarO"ce 9 Server - PDF Converter. Both elements are considered in the following sub chapters. WAR File The war #le is designed to run in the StarO"ce 9 Server - PDF Converter Tomcat environment. For the use in another environment the war #le needs some adjustments to run correctly. The war #le contains a con#g#le called config.properties. The #le can be found in the WEB-INF directory. The following settings should be adjusted to your needs: I soinstalldir (path to the PDF Converter “program” directory) I workdir (path to the PDF Converter “temp” directory) I converterServiceURL (URL to the PDF Converter web service) The war #le can be found in 39 Glass!shV2 Glass"shV2 You can run the StarO"ce 9 Server - PDF Converter in a Glass#sh environment. M To run the PDF Converter in a Glass"sh environment 1 De!ne the path to the native shared libraries. 2 Install the application. Shared libraries for Glass"sh 40 StarO"ce 9 Server - PDF Converter • Apr 2009 Glass!shV2 M To de"ne the path to the native shared libraries 1 Navigate to“Application Server”–>“JVM Settings”–>“Path Settings”. 2 Specify the“Native Library Path Pre!x”option with a valid URE library path. (for example, D:/Demos/pdfconverter/OpenOffice.org/URE/bin/ for Windows or /opt/openoffice.org/ure/lib for Linux or UNIX operating systems). More Information After changing the library path After changing the native library path the Glass#sh server needs a restart. Restart the server and continue with the next step. Install the application for Glass"sh M To install the application 1 Navigate to“Application”–>“Web Applications”. 2 “Deploy”new application. Chapter 6 • Application Server Integration 41 ApacheTomcat 6.0.16 M To deploy the PDF Converter application "le 1 Specify PDF Converter application !le. 2 Press OK. Now the PDF Converter is ready to use. ApacheTomcat 6.0.16 M To run the PDF Converter in aTomcat environment 1 De!ne the path to the native shared libraries. 2 Install the application. Shared libraries forTomcat Before startup: 42 StarO"ce 9 Server - PDF Converter • Apr 2009 IBMWebsphere 6.1 Use the JAVA_OPTS variable in catalina.bat for Windows or catalina.sh for Linux/UNIX respectively to de#ne the location of the native libraries. To do this add -Djava.library.path="[NATIVE_LIB_PATH]" (NATIVE_LIB_PATH for example D:\Demos\pdfconverter\OpenOffice.org\URE\bin\) to the JAVA_OPTS variable. After you add the option to JAVA_OPTS the line should be like this: ’set JAVA_OPTS=%JAVA_OPTS% -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djava.util.logging.config.file="%CATALINA_BASE%\conf\logging.properties" -Djava.library.path=D:\Demos\pdfconverter\OpenOffice.org\URE\bin\’. Now start the Tomcat server as usual. Install the application forTomcat M To deploy theWAR "le 1 Navigate to the“TomcatWeb Application Manager”web page. 2 Use the“WAR !le to deploy”method and select the PDF Converter war !le. 3 Click the“Deploy”button. IBMWebsphere 6.1 Consider three steps to use the PDF Converter inside an IBM Websphere environment. Chapter 6 • Application Server Integration 43 IBMWebsphere 6.1 M To run the PDF Converter in an IBMWebsphere environment 1 Install the application. 2 De!ne the path to the shared libraries. 3 Con!gure the PDF Converter application and environment. Installing the application forWebsphere M To install the application ("rst screen) 1 Select the PDF Converter war !le. 2 Click Next to continue with the next step. 44 StarO"ce 9 Server - PDF Converter • Apr 2009 IBMWebsphere 6.1 M To install the application (following screens) 1 De!ne the directory to install the PDF Converter. 2 Optionally de!ne a proper display name for the application. 3 Check the option to deploy the PDF Converter web service. 4 Click Next to continue with the next step. Chapter 6 • Application Server Integration 45 IBMWebsphere 6.1 5 Click Finish (“1”in the image) to install the application 6 Click on the Save hyperlink (“1”in the image) to save the con!guration. 46 StarO"ce 9 Server - PDF Converter • Apr 2009 IBMWebsphere 6.1 The PDF Converter is now installed. The application is marked as not started. Do not start the application now! Before starting the shared library needs to be installed. Installing the shared libraries forWebsphere M To install shared libraries part 1 Go to “Environment” –> “Shared libraries”. G Create a new shared library. M To install shared libraries part 2 1 Type a name for the shared library. Chapter 6 • Application Server Integration 47 IBMWebsphere 6.1 2 Setting up the classpath to the libraries which use native libraries. 3 Setting up the path to the native libraries. 4 Click OK to commit the shared library. Con"gure PDF Converter Application 48 StarO"ce 9 Server - PDF Converter • Apr 2009 IBMWebsphere 6.1 M To con"gure the PDF Converter application part 1 1 Check the PDF Converter application. 2 Click the Reference Shared Libraries button to map the shared library. M To con"gure the PDF Converter application part 2 1 Set the class loader order to Parent Class Loader First. 2 Set theWAR class loader policy to For EachWar File In Application. Chapter 6 • Application Server Integration 49 IBMWebsphere 6.1 Con"gureWebsphere Server M To con"gure theWebsphere server part 1 1 Go to“Servers”->“Application servers”. 2 Set the server settings for the class loader policy as in the image above. Settings are: Access set to Allow, Classloader policy set to Single, Class loading mode set to Parent #rst. M To con"gure theWebsphere server part 2 1 Con!gure the StarO"ce Server shared library. 50 StarO"ce 9 Server - PDF Converter • Apr 2009 IBMWebsphere 6.1 2 Select theWith Parent Class Loader First list entry. 3 Restart the IBMWebphere Application Server. Chapter 6 • Application Server Integration 51 52 APPENDIXAA Appendix Issues with JAX-RPC On the client side, use JAX-WS. Starting with StarO"ce 9 Server - PDF Converter Update 10, JAX-RPC is no longer supported. There are several severe known issues with JAX-RPC. TABLE A–1 Issues with JAX-RPC Sun JRE version JAX–RPC version OK / NOK 1.5 1.5 OK 1.5 1.6 NOK, no workaround known 1.6 1.5 OK 1.6 1.6 NOK, unless you use saaj-impl.jar from updated SAAJ 1.3 package, see below the table The URL for an updated SAAJ 1.3 package is https://saaj.dev.java.net/#les/documents/52/32730/saaj1.3.zip 53 54