Creating PDF Documents

To create a PDF document, perform the following steps:

1. Include project files.

2. Create an Output Client object.

3. Reference an XML data source.

4. Set PDF run-time options.

5. Set rendering run-time options.

6. Generate a PDF document.

7. Retrieve the results of the operation.

Reference an XML data source

To merge data with the form design, you must reference an XML data source that contains data. An XML element must exist for every form field that you plan to populate with data. The XML element name must match the field name. An XML element is ignored if it does not correspond to a form field or if the XML element name does not match the field name. It is not necessary to match the order in which the XML elements are displayed if all XML elements are specified.

Consider the following example loan application form.

View full size graphic

To merge data into this form design, you must create an XML data source that corresponds to the form. The following XML represents an XDP XML data source that corresponds to the example mortgage application form.

<?xml version="1.0" encoding="UTF-8" ?>  
- <xfa:datasets xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"> 
- <xfa:data> 
- <data> 
    - <Layer> 
        <closeDate>1/26/2007</closeDate>  
        <lastName>Johnson</lastName>  
        <firstName>Jerry</firstName>  
        <mailingAddress>JJohnson@NoMailServer.com</mailingAddress>  
        <city>New York</city>  
        <zipCode>00501</zipCode>  
        <state>NY</state>  
        <dateBirth>26/08/1973</dateBirth>  
        <middleInitials>D</middleInitials>  
        <socialSecurityNumber>(555) 555-5555</socialSecurityNumber>  
        <phoneNumber>5555550000</phoneNumber>  
    </Layer> 
    - <Mortgage> 
        <mortgageAmount>295000.00</mortgageAmount>  
        <monthlyMortgagePayment>1724.54</monthlyMortgagePayment>  
        <purchasePrice>300000</purchasePrice>  
        <downPayment>5000</downPayment>  
        <term>25</term>  
        <interestRate>5.00</interestRate>  
    </Mortgage> 
</data> 
</xfa:data> 
</xfa:datasets>

Generate a PDF document

After you reference a valid XML data source that contains form data and you set run-time options, you can invoke the Output service, which results in it generating a PDF document.

When generating a PDF document, you specify URI values that are required by the Output service to create a PDF document. A form design can be stored in locations such as the server file system or as part of a LiveCycle application. A form design (or other resources such as an image file) that exists as part of a LiveCycle application can be referenced by using the content root URI value repository:///. For example, consider the following form design named Loan.xdp located within a LiveCycle application named Applications/FormsApplication:

View full size graphic

To access the Loan.xdp file shown in the previous illustration, specify repository:///Applications/FormsApplication/1.0/FormsFolder/ as the third parameter passed to the OutputClient object’s generatePDFOutput method. Specify the form name (Loan.xdp) as the second parameter passed to the OutputClient object’s generatePDFOutput method.

If the XDP file contains images (or other resources such as fragments), place the resources in the same application folder as the XDP file. LiveCycle uses the content root URI as the base path to resolve references to images. For example, if the Loan.xdp file contains an image, ensure that you place the image in Applications/FormsApplication/1.0/FormsFolder/.

Note: You can reference a LiveCycle application URI when invoking the OutputClient object’s generatePDFOutput or generatePrintedOutput methods.

Note: To see a complete quick start that creates a PDF document by referencing a XDP located in a LiveCycle application, see Quick Start (EJB mode): Creating a PDF document based on an application XDP file using the Java API.

Create a PDF document by using the Output API (Java):

1. Include project files.

   Include client JAR files, such as adobe-output-client.jar, in your Java project’s class path.

2. Create an Output Client object.

   • Create a ServiceClientFactory object that contains connection properties.

   • Create an OutputClient object by using its constructor and passing the ServiceClientFactory object.

3. Reference an XML data source.

   • Create a java.io.FileInputStream object that represents the XML data source that is used to populate the PDF document by using its constructor and passing a string value that specifies the location of the XML file.

   • Create a com.adobe.idp.Document object by using its constructor. Pass the java.io.FileInputStream object.

4. Set PDF run-time options.

   • Create a PDFOutputOptionsSpec object by using its constructor.

   • Set the File URI option by invoking the PDFOutputOptionsSpec object’s setFileURI method. Pass a string value that specifies the location of the PDF file that the Output service generates. The File URI option is relative to the J2EE application server hosting LiveCycle, not the client computer.

5. Set rendering run-time options.

   • Create a RenderOptionsSpec object by using its constructor.

   • Cache the form design to improve the performance of the Output service by invoking the RenderOptionsSpec object’s setCacheEnabled and passing true.

   Note: You cannot set the version of the PDF document by using the RenderOptionsSpec object’s setPdfVersion method if the input document is an Acrobat form (a form created in Acrobat) or an XFA document that is signed or certified. The output PDF document retains the original PDF version. Likewise, you cannot set the tagged Adobe PDF option by invoking the RenderOptionsSpec object’s setTaggedPDF method if the input document is an Acrobat form or a signed or certified XFA document.
   Note: You cannot set the linearized PDF option by using the RenderOptionsSpec object’s setLinearizedPDF method if the input PDF document is certified or digitally signed. (See Digitally Signing PDF Documents.)

6. Generate a PDF document.

   Create a PDF document by invoking the OutputClient object’s generatePDFOutput method and passing the following values:

   • A TransformationFormat enumeration value. To generate a PDF document, specify TransformationFormat.PDF.

   • A string value that specifies the name of the form design.

   • A string value that specifies the content root where the form design is located.

   • A PDFOutputOptionsSpec object that contains PDF run-time options.

   • A RenderOptionsSpec object that contains rendering run-time options.

   • The com.adobe.idp.Document object that contains the XML data source that contains data to merge with the form design.

   The generatePDFOutput method returns an OutputResult object that contains the results of the operation.

   Important: When generating a PDF document by invoking the generatePDFOutput method, be aware that you cannot merge data with an XFA PDF form that is signed or certified. (See Digitally Signing and Certifying Documents.)
   Note: The OutputResult object’s getRecordLevelMetaDataList method returns null.
   Note: You can also create a PDF document by invoking the OutputClient object’s generatePDFOutput2 method. (See Passing Documents located in Content Services (deprecated) to the Output Service.)

7. Retrieve the results of the operation.

   • Retrieve a com.adobe.idp.Document object that represents the status of the generatePDFOutput operation by invoking the OutputResult object’s getStatusDoc method. This method returns status XML data that specifies whether the operation was successful.

   • Create a java.io.File object that contains the results of the operation. Ensure that the file name extension is .xml.

   • Invoke the com.adobe.idp.Document object’s copyToFile method to copy the contents of the com.adobe.idp.Document object to the file (ensure that you use the com.adobe.idp.Document object that was returned by the getStatusDoc method).

   Although the Output service writes the PDF document to the location specified by the argument that is passed to the PDFOutputOptionsSpec object’s setFileURI method, you can programmatically retrieve the PDF/A document by invoking the OutputResult object’s getGeneratedDoc method.

Create a PDF document by using the Output API (web service):

1. Include project files.

   Create a Microsoft .NET project that uses MTOM. Ensure that you use the following WSDL definition: http://localhost:8080/soap/services/OutputService?WSDL&lc_version=9.0.1.

   Note: Replace localhost with the IP address of the server hosting LiveCycle.

2. Create an Output Client object.

   • Create an OutputServiceClient object by using its default constructor.

   • Create an OutputServiceClient.Endpoint.Address object by using the System.ServiceModel.EndpointAddress constructor. Pass a string value that specifies the WSDL to the LiveCycle service (for example, http://localhost:8080/soap/services/OutputService?blob=mtom.) You do not need to use the lc_version attribute. This attribute is used when you create a service reference. However, specify ?blob=mtom to use MTOM.

   • Create a System.ServiceModel.BasicHttpBinding object by getting the value of the OutputServiceClient.Endpoint.Binding field. Cast the return value to BasicHttpBinding.

   • Set the System.ServiceModel.BasicHttpBinding object’s MessageEncoding field to WSMessageEncoding.Mtom. This value ensures that MTOM is used.

   • Enable basic HTTP authentication by performing the following tasks:

     • Assign the LiveCycle user name to the field OutputServiceClient.ClientCredentials.UserName.UserName.

     • Assign the corresponding password value to the field OutputServiceClient.ClientCredentials.UserName.Password.

     • Assign the constant value HttpClientCredentialType.Basic to the field BasicHttpBindingSecurity.Transport.ClientCredentialType.

     • Assign the constant value BasicHttpSecurityMode.TransportCredentialOnly to the field BasicHttpBindingSecurity.Security.Mode.

3. Reference an XML data source.

   • Create a BLOB object by using its constructor. The BLOB object is used to store XML data that will be merged with the PDF document.

   • Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the XML file that contains form data.

   • Create a byte array that stores the content of the System.IO.FileStream object. You can determine the size of the byte array by getting the System.IO.FileStream object’s Length property.

   • Populate the byte array with stream data by invoking the System.IO.FileStream object’s Read method and passing the byte array, the starting position, and the stream length to read.

   • Populate the BLOB object by assigning its MTOM field with the contents of the byte array.

4. Set PDF run-time options.

   • Create a PDFOutputOptionsSpec object by using its constructor.

   • Set the File URI option by assigning a string value that specifies the location of the PDF file that the Output service generates to the PDFOutputOptionsSpec object’s fileURI data member. The File URI option is relative to the J2EE application server hosting LiveCycle, not the client computer.

5. Set rendering run-time options.

   • Create a RenderOptionsSpec object by using its constructor.

   • Cache the form design to improve the performance of the Output service by assigning the value true to the RenderOptionsSpec object’s cacheEnabled data member.

   Note: You cannot set the version of the PDF document by using the RenderOptionsSpec object’s setPdfVersion method if the input document is an Acrobat form (a form created in Acrobat) or an XFA document that is signed or certified. The output PDF document retains the original PDF version. Likewise, you cannot set the tagged Adobe PDF option by invoking the RenderOptionsSpec object’s setTaggedPDF method if the input document is an Acrobat form or a signed or certified XFA document.
   Note: You cannot set the linearized PDF option by using the RenderOptionsSpec object’s linearizedPDF member if the input PDF document is certified or digitally signed. (See Digitally Signing PDF Documents.)

6. Generate a PDF document.

   Create a PDF document by invoking the OutputServiceService object’s generatePDFOutput method and passing the following values:

   • A TransformationFormat enumeration value. To generate a PDF document, specify TransformationFormat.PDF.

   • A string value that specifies the name of the form design.

   • A string value that specifies the content root where the form design is located.

   • A PDFOutputOptionsSpec object that contains PDF run-time options.

   • A RenderOptionsSpec object that contains rendering run-time options.

   • The BLOB object that contains the XML data source that contains data to merge with the form design.

   • A BLOB object that is populated by the generatePDFOutput method. The generatePDFOutput method populates this object with generated metadata that describes the document. (This parameter value is required only for web service invocation).

   • A BLOB object that is populated by the generatePDFOutput method. The generatePDFOutput method populates this object with result data. (This parameter value is required only for web service invocation).

   • An OutputResult object that contains the results of the operation. (This parameter value is required only for web service invocation).

   Important: When generating a PDF document by invoking the generatePDFOutput method, be aware that you cannot merge data with an XFA PDF form that is signed or certified. (See Digitally Signing and Certifying Documents.)
   Note: You can also create a PDF document by invoking the OutputClient object’s generatePDFOutput2 method. (See Passing Documents located in Content Services (deprecated) to the Output Service.)

7. Retrieve the results of the operation.

   • Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents an XML file location that contains result data. Ensure that the file name extension is .xml.

   • Create a byte array that stores the data content of the BLOB object that was populated with result data by the OutputServiceService object’s generatePDFOutput method (the eighth parameter). Populate the byte array by getting the value of the BLOB object’s MTOMfield.

   • Create a System.IO.BinaryWriter object by invoking its constructor and passing the System.IO.FileStream object.

   • Write the contents of the byte array to the XML file by invoking the System.IO.BinaryWriter object’s Write method and passing the byte array.

   See also

   Summary of steps

   Quick Start (MTOM): Creating a PDF document using the web service API

   Quick Start (SwaRef): Creating a PDF document using the web service API

   Invoking LiveCycle using MTOM

   Invoking LiveCycle using SwaRef

   Note: The OutputServiceService object’s generateOutput method is deprecated.