Specifying multiple input streams

In most of the examples in this document, a PDF source element represents a single PDF document. This section describes how you can also map multiple documents to a single PDF source element.

Names are mapped to streams by means of an inputs map. An inputs map contains entries with names and corresponding values. The values can represent either a single input stream or an ordered list of input streams. See Programmatically Assembling PDF Documents for details.

A source element can have a sourceMatch attribute instead of a source attribute. (If neither is present, the DDX is invalid.) The Assembler service uses these attributes and other PDF source attributes to generate an ordered input list of one or more streams to generate content for the element.

The Assembler service uses the following process to create the input list:

•	If source is present and the name is found in the inputs map (or matches the name of a previous PDF result element), the input is initially set to the stream or ordered list of streams mapped to the name.

If source is present and the name is not found in the inputs map or from a previous result, then sourceMatch is used if present. If sourceMatch is not present, an error is thrown if required="true", otherwise the PDF source element is ignored and it contributes no content to the result.

•	If source is not present, sourceMatch must be present. sourceMatch specifies a regular expression whose syntax is implemented in the java.util.regex package for Java. This regular expression is used to select one or more source names from the inputs map.

Once the names are matched, matchMode indicates whether the matched names are the names from the inputs to include or exclude so that a list of one or more names can be created. This list of names is then sorted according to sortOrder to result in an ordered list of names.

The matching names are sorted based on the value of the sortOrder attribute, either Ascending (the default) or Descending. The Assembler service creates an ordered list of streams by taking each name in the sorted list and adding each of its streams in order to the input list. (The sort order can be refined for different languages by using the sortLocale attribute.)

•

The final input list is created by applying the select attribute, which specifies a range of documents in the list. Its syntax is the same as that used for page ranges (see Page ranges). For example, "2-last" selects the second through last document in the list. If the range results in no documents being selected, the input list is empty.

If the value of matchMode is Exclude, the select attribute value is inverted. That is, the input list includes all streams other than those specified by select.

If the final input list is empty (consists of no streams), the PDF source element will add no pages to the assembly. This occurs, for example, if the select attribute is set to "3" and there are only two source documents in the inputs map. You can specify that an empty list is acceptable by setting the value of the required attribute to false. If the value of required is true (the default), an error occurs.

The following example specifies both a source and sourceMatch attribute for some of the source elements.

The following are two examples of inputs maps that could be used with this DDX document. The first one maps each logical name to a single data stream as follows:

Logical name	Data stream
intro	stream_1
chap1	stream_2
chap2	stream_3
chap3	stream_4
chap4	stream_5
appendix1	stream_6
appendix2	stream_7
index	stream_8

In the example, the source attributes of the first and last PDF source element (intro and index) match names in the inputs map, so those streams are used.

The source attributes of the other PDF source elements (Chapters and Appendices) do not match any of the names in the inputs map. Therefore, the sourceMatch attribute is checked. The regular expression "chap[\d]+" matches chap1, chap2, chap3, and chap4 in the inputs map. The select attribute "1" selects the first of those streams (chap1) and "2-last" selects the rest of them. (If there was only one name matching "chap[\d]+", "2-last" would generate an error unless the value of required was false.)

Similarly, the sourceMatch expression "appendix[\d]+" matches appendix1 and appendix2.

In the next example, the inputs map maps each logical name to an ordered list of data streams.

Logical name	Data streams
intro	stream_1
Chapters	stream_2, stream_3, stream_4, stream_5
Appendices	stream_6, stream_7
index	stream_8

In this case, all of the names match source attributes in the DDX. In the case of Chapters and Appendices, multiple streams are used for the source elements.

Whenever a PDF source element represents multiple streams, it is as if they were each specified individually in the DDX. The other attributes are treated as follows:

bookmarkTitle - If present, the value should be a built-in key (see Built-in keys); otherwise, the bookmarks are identical for all selected input documents. For example, bookmarkTitle="_SourceTitle" uses the metadata title of each PDF document as the bookmark title.

access - If set, the same password specified by PasswordAccessProfile is used to open each selected input document.