Creating Multiple Output Files

The Output service can create separate documents for each record within an XML data source or a single file that contains all records (this functionality is the default). For example, assume that ten records are located within an XML data source and you instruct the Output service to create separate PDF documents (or other types of output) for each record by using the Output Service API. As a result, the Output service generates ten PDF documents. (Instead of creating documents, you can send multiple print streams to a printer.)

The following illustration also shows the Output service processing an XML data file that contains multiple records. However, assume that you instruct the Output service to create a single PDF document that contains all data records. In this situation, the Output service generates one document that contains all of the records.

The following illustration shows the Output service processing an XML data file that contains multiple records. Assume that you instruct the Output service to create a separate PDF document for each data record. In this situation, the Output service generates a separate PDF document for each data record.

The following XML data shows an example of a data file that contains three data records.

<?xml version="1.0" encoding="UTF-8"?> 
<batch> 
<LoanRecord> 
    <mortgageAmount>500000</mortgageAmount> 
    <lastName>Blue</lastName> 
    <firstName>Tony</firstName> 
    <SSN>555666777</SSN> 
    <PositionTitle>Product Manager</PositionTitle> 
    <Address>555 No Where Dr</Address> 
    <City>New York</City> 
    <StateProv>New York</StateProv> 
    <ZipCode>51256</ZipCode> 
    <Email>TBlue@NoMailServer.com</Email> 
    <PhoneNum>555-7418</PhoneNum> 
    <FaxNum>555-9981</FaxNum> 
    <Description>Buy a home</Description> 
</LoanRecord> 
<LoanRecord> 
    <mortgageAmount>300000</mortgageAmount> 
    <lastName>White</lastName> 
    <firstName>Sam</firstName> 
    <SSN>555666222</SSN> 
    <PositionTitle>Program Manager</PositionTitle> 
    <Address>557 No Where Dr</Address> 
    <City>New York</City> 
    <StateProv>New York</StateProv> 
    <ZipCode>51256</ZipCode> 
    <Email>SWhite@NoMailServer.com</Email> 
    <PhoneNum>555-7445</PhoneNum> 
    <FaxNum>555-9986</FaxNum> 
    <Description>Buy a home</Description> 
</LoanRecord> 
<LoanRecord> 
    <mortgageAmount>700000</mortgageAmount> 
    <lastName>Green</lastName> 
    <firstName>Steve</firstName> 
    <SSN>55566688</SSN> 
    <PositionTitle>Project Manager</PositionTitle> 
    <Address>445 No Where Dr</Address> 
    <City>New York</City> 
    <StateProv>New York</StateProv> 
    <ZipCode>51256</ZipCode> 
    <Email>SGreeb@NoMailServer.com</Email> 
    <PhoneNum>555-2211</PhoneNum> 
    <FaxNum>555-2221</FaxNum> 
    <Description>Buy a home</Description> 
</LoanRecord> 
</batch>

Notice that the XML element that starts and ends each data record is LoanRecord. This XML element is referenced by the application logic that generates multiple files.

Note: For more information about the Output service, see Services Reference for LiveCycle.

Summary of steps

To create multiple PDF files based on an XML data source, 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 multiple PDF files.

  7. Retrieve the results of the operation.

Include project files

Include necessary files in your development project. If you are creating a client application using Java, include the necessary JAR files. If you are using web services, make sure that you include the proxy files.

The following JAR files must be added to your project’s class path:

  • adobe-livecycle-client.jar

  • adobe-usermanager-client.jar

  • adobe-output-client.jar

  • adobe-utilities.jar (required if LiveCycle is deployed on JBoss)

  • jbossall-client.jar (required if LiveCycle is deployed on JBoss)

if LiveCycle is deployed on a supported J2EE application server that is not JBoss, you will need to replace the adobe-utilities.jar and jbossall-client.jar files with JAR files that are specific to the J2EE application server on which LiveCycle is deployed.

Create an Output Client object

Before you can programmatically perform an Output service operation, you must create an Output service client object. If you are using the Java API, create an OutputClient object. If you are using the Output web service API, create an OutputServiceService object.

Reference an XML data source

Reference an XML data source that contains multiple records. An XML element must be used to separate the data records. For example, in the example XML data source that is shown earlier in this section, the XML element that separates data records is named LoanRecord.

An XML element must exist for every form field that you want 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.

Set PDF run-time options

You must set the following run-time options for the Output service to successfully create multiple files based on an XML data source:

  • Many Files: Specifies whether the Output service creates a single document or multiple documents. You can specify true or false. To create a separate document for each data record in the XML data source, specify true.

  • File URI: Specifies the location of the files that the Output service generates. For example, assume that you specify C:\\Adobe\forms\Loan.pdf. In this situation, the Output service creates a file named Loan.pdf and places the file in the C:\\Adobe\forms folder. When there are multiple files, the file names are Loan0001.pdf, Loan0002.pdf, Loan0003.pdf and so on. If you specify a file location, the files are placed on the server, not the client computer.

  • Record Name: Specifies the XML element name in the data source that separates the data records. For example, in the example XML data source that is shown earlier in this section, the XML element that separates data records is called LoanRecord. (Instead of setting the Record Name run-time option, you can set the Record Level by assigning it a numeric value that indicates the element level that contains data records. However, you can set only the Record Name or the Record Level. You cannot set both values.)

Set rendering run-time options

You can set rendering run-time options while creating multiple files. Although these options are not required (unlike output run-time options, which are required), you can perform tasks such as improving the performance of the Output service. For example, you can cache the form design that the Output service uses in order to improve performance.

When the Output service processes batch records, it reads data that contains multiple records in an incremental manner. That is, the Output service reads the data into memory and releases the data as the batch of records is processed. The Output service loads data in an incremental manner when either one of two run-time options are set. If you set the Record Name run-time option, the Output service reads data in an incremental manner. Likewise, if you set the Record Level run-time option to 2 or greater, the Output service reads data in an incremental manner.

You can control whether the Output service performs incremental loading by using the PDFOutputOptionsSpec or the PrintedOutputOptionSpec object’s setLazyLoading method. You can pass the value false to this method which turns off incremental loading.

Generate multiple PDF files

After you reference a valid XML data source that contains multiple data records and set run-time options, you can invoke the Output service, which causes it to generate multiple files. When generating multiple records, the OutputResult object’s getGeneratedDoc method returns null.

Retrieve the results of the operation

After the Output service performs an operation, it returns XML data that specifies whether the operation was successful. The following XML is returned by the Output service. In this situation, the Output service generated 42 documents.

<?xml version="1.0" encoding="UTF-8"?> 
<printResult> 
<status>0</status> 
<requestId>4ad85f9e2</requestId> 
<context/> 
<messages> 
<message>Printed all 42 records successfully.</message> 
</messages> 
<printSpec> 
<input> 
<validated>true</validated> 
<dataFile recordIdField="" recordLevel="0" recordName="LoanRecord"/> 
<sniffRules lookAhead="300"/> 
<formDesign>Loan.xdp</formDesign> 
<contentRoot>C:\Adobe</contentRoot> 
<metadata-spec record="false"/> 
</input> 
<output> 
<format>PDF</format> 
<fileURI>C:\Adobe\forms\Loan.pdf</fileURI> 
<optionString>cacheenabled=true&amp;padebug=false&amp;linearpdf=false&amp;pdfarevisionnumber=1&amp;pdfaconformance=A&amp;taggedpdf=false&amp;TransactionTimeOut=180</optionString> 
<waitForResponse>true</waitForResponse> 
<outputStream>multiple</outputStream> 
</output> 
</printSpec> 
</printResult>

Create multiple PDF files using the Java API

Create multiple PDF files 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 contains multiple records 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 and passing the java.io.FileInputStream object.

  4. Set PDF run-time options

    • Create a PDFOutputOptionsSpec object by using its constructor.

    • Set the Many Files option by invoking the PDFOutputOptionsSpec object’s setGenerateManyFiles method. For example, pass the value true to instruct the Output service to create a separate PDF file for each record in the XML data source. (If you pass false, the Output service generates a single PDF document that contains all records).

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

    • Set the Record Name option by invoking the OutputOptionsSpec object’s setRecordName method and passing a string value that specifies the XML element name in the data source that separates the data records. (For example, consider the XML data source shown earlier in this section. The name of the XML element that separates data records is LoanRecord).

  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 a Boolean value of true.

  6. Generate multiple PDF files

    Generate multiple PDF files by invoking the OutputClient object’s generatePDFOutput method and passing the following values:

    • A TransformationFormat enum 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.

  7. Retrieve the results of the operation

    • Create a java.io.File object that represents an XML file that will contain the results of the generatePDFOutput method. 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 applyUsageRights method).

Create multiple PDF files using the web service API

Create multiple PDF files 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 form data that contains multiple records.

    • Create a System.IO.FileStream object by invoking its constructor. Pass a string value that represents the file location of the XML file that contains multiple records.

    • 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 Many Files option by assigning a Boolean value to the OutputOptionsSpec object’s generateManyFiles data member. For example, assign the value true to this data member to instruct the Output service to create a separate PDF file for each record in the XML data source. (If you assign false to this data member, then the Output service generates a single PDF that contains all records).

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

    • Set the record name option by assigning a string value that specifies the XML element name in the data source that separates the data records to the OutputOptionsSpec object’s recordName data member.

    • Set the copies option by assigning an integer value that specifies the number of copies that the Output service generates to the OutputOptionsSpec object’s copies data member.

  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.

  6. Generate multiple PDF files.

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

    • A TransformationFormat enum 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.

    • A BLOB object that is populated by the generatePDFOutput method. The generatePDFOutput method populates this object with result data.

    • An OutputResult object that contains the results of the operation.

  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 binaryData data member.

    • 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.

// Ethnio survey code removed