Home Page FO Designer user guide. XSL-FO tool for Oracle APEX and the Java[TM] platform
                                                    FO Designer guide
                                                  • First steps
                                                  • Introduction
                                                  • The user interface
                                                  • Working with the interface
                                                  • Structure of the template
                                                  • Executing the template to create PDF files
                                                  • Learn by doing
                                                  • The invoice IDOC example
                                                  • The Group by example
                                                  • The two columns example
                                                  • Barcodes
                                                  • Charts
                                                  • The running totals example
                                                  • Interactive forms
                                                  • Flavours
                                                  • The base template
                                                  • Long texts and HTML fields
                                                  • The memo field explained
                                                  • Advanced functionalities
                                                  • FOP Could Server
                                                  • Migration of existing XSL-FO files
                                                  • FAQS
                                                  • Troubleshooting
                                                  • Licenses
                                                  • Executing the template to create PDF files

                                                    5. Executing the template to create PDF files

                                                    Once you have generated the XSL-FO file you can use Apache FOP for converting your XML files to PDF.

                                                    However we provide the following class:


                                                    which has a very simple interface:


                                                    • generate PDF file for XML document

                                                      @param xmlStream input XML document
                                                      xsltStream XSL-FO file as created by the designer
                                                      os output PDF file


                                                    public void process(InputStream xmlStream, InputStream xsltStream,OutputStream os) throws Exception {

                                                    for example:

                                                    FOProcessor processor=new FOProcessor();

                                                    processor.process(new FileInputStream("Order.xml"), new FileInputStream("order.fo") , new FileOutputStream("report.pdf"));

                                                    FOP web server (servlet)

                                                    The delivery includes a WAR file which can be deployed on a web server. This includes a servlet that operates as follows:

                                                    1. It receives a HTTP request using the POST method.
                                                      • The body of the request contains the XML document to be converted
                                                      • or the body contains a FORM and in the form there is a text field that contains the XML data. In this case the parameter DATAFIELD must provide the name of the field (see file Example.html)
                                                    2. In the URL of the servlet you provide the name of the XSL-FO file to be used for the conversion, using the TEMPLATE parameter. The template must be the name of the file and it must be placed in the default working directory of the server (it is also possible to provide the file as a relative or absolute file name). As an alternative the file can be located within the war file in the WEB-INF/classes subdirectory or below it.
                                                    3. the servlet returns the PDF file

                                                    The delivery includes the following files that you can use for testing:

                                                    •     departmentEmployees.included inside the war file (directory WEB-INF/classes).
                                                    •     the war file: web/J4LFOPServer.war

                                                    You can test the servlet by deploying the war file and then executing the URL:


                                                    When you click on the button the following URL will be openned:

                                                    http://localhost:8080/J4LFOPServer/servlet? TEMPLATE=departmentEmployees.fo&ENCODIN G=iso-8859-1&DATAFIELD=S1


                                                    • the file departmentEmployees.fo is inside the war file
                                                    • encoding ISO-8859-1 is the encoding of the input data
                                                    • S1 is the name of the text field that contains the XML data. Note, if the DATAFIELD is missing, the servlet assumes the body of the HTTP request contains the XML payload.

                                                    Additionally the REMOVENS=YES parameter must be used if your input XML file contains namespace information.

                                                    Java objects to PDF conversion

                                                    This section describes how to convert Java objects to PDF. This description is based on the example contained in the examples\JavaClass_to_PDF subdirectory of the delivery.

                                                    This example simulates a sales Java application which works with purchase order objects. These purchase order objects are composed of 3 classes:

                                                    • com/java4less/examples/po/PurchaseOrderHeader.java
                                                    • com/java4less/examples/po/BuyerInformation.java
                                                    • com/java4less/examples/po/PurchaseOrderItem.java

                                                    This application needs to provide a mean to print a purchase order document out of a Java purchase order object. As a solution this example proposes using Apache FOP for creating a PDF file which can be printed and using J4L FO Designer for designing the layout of the document. Since FOP requires an XML document as input, the Java objects will be first converted to XML using the JAXB (Java XML Binding) API. Note this means you require Java 1.5 with JAXB or Java 1.6.

                                                    The steps to be performed are:

                                                    1. run JAXB schema tool to generate a XML schema for your Java classes. In our example the file generateSchema.bat was used for that and the schema1.xsd file was generated
                                                    2. Use FO Designer to generate a document template using the schema. The created file is JavaPurchaseOrder.xre. This file can be imported in FO Designer.
                                                    3. Use FO Designer to generate a FO file which will be used at runtime. The generated file is JavaPOExample.fo
                                                    4. At runtime you have to
                                                      1. create your Java objects
                                                      2. convert them to XML using JAXB
                                                      3. convert the XML to PDF using JavaPOExample.fo and Apache FOP.

                                                        You can see how this is done in the POTest.java file. The source code is aproximately:

                                                    //1. create order object

                                                    PurchaseOrderHeader po=new PurchaseOrderHeader("1");
                                                    po.setBuyer(new BuyerInformation("John Solo","Street ABC 1","Manchester","AB 673","UK"));
                                                    PurchaseOrderItem[] items={ new PurchaseOrderItem("X1","Printer Injet",1), new PurchaseOrderItem("R4","Optic mouse",1),

                                                    // 2. create now XML representation of the order

                                                    JAXBContext jc = JAXBContext.newInstance(PurchaseOrderHeader.class);
                                                    Marshaller marshaller=jc.createMarshaller();
                                                    ByteArrayOutputStream ba=new ByteArrayOutputStream();

                                                    7/3. create now the PDF output for the XML data
                                                    FOProcessor processor=new FOProcessor();
                                                    processor.process(new ByteArrayInputStream(ba.toByteArray()), new FileInputStream("JavaPOExample.fo") , new FileOutputStream("JavaPOExample.pdf"));

                                                    You can use the file POTest.bat for testing the delivered files.

                                                    Sending the PDF as an email attachment

                                                    This option is currently available only for the APEX server, please check the APEX specific documentation.

                                                    Adding a digital signature to the PDF file

                                                    You can add a digital signature to the PDF files you generate. This signature ensures the integrity of your document and its authentication. In other words, the receiver of the document knows you have created that document (authentication) and no one has modified it (integrity). The signature created will use the algorithms RSA signature, SHA1 hash and PKCS7 encoding.

                                                    The signature can be created in the design environment for testing purposes and of course also in the runtime environment. Please read the environment specific document (for example Apex) to learn how to activate the signature.

                                                    The rest of this section describes how to test the digital signature in the designer and view it in Acrobat reader.

                                                    In order to activate the digital signature you use the preferences window. In this window you activate the signature and select the p12 or pfx file which contains the private key used for the signature. Note our product contains a test certification authority (CA) and a test certificate in the certs subdirectory. You can use these for testing purposes.

                                                    If you have enabled the signature in the settings window, each time you generate a PDF file with the PDF button, the designer will ask for the password of the p12 file. The password of the test file we provide is test.

                                                    Note, if you click on the cancel button, the PDF file will be created without the signature.

                                                    Once you open the created file, you will notice Acrobat reader warns you with the text "the signature has problems". The reason for this is, Acrobat does not know the certificate authority (CA) we have used for creating the test certificate. Looking at the signature closely in the signatures panel you will see:

                                                    • The PDF reader says the document has not been modified since the signature has been applied (integrity of the document).
                                                    • The signer's identity is unknown since the reader does not know our test CA.

                                                    If you however click on the certificate details link and add the CA certificate as a trusted certificate, you will see the reader now accepts the signature.