<?xml version="1.0" encoding="UTF-8"?>

<sample>

  <name>pdfa</name>
  <title>PDF/A Conformance Sample</title>
  <description>Shows how to generate PDF/A compliant documents.</description>

  <mainFeature ref="pdfa"/>
  
  <!-- pdfa -->
  
  <feature name="pdfa" title="Generating PDF/A compliant documents">
    <description>
How to use PDF/A conformance settings to generate various levels of PDF/A documents.
    </description>
    <since>3.1.2</since>
    <documentedBy>
      <author>
    	<name>Sanda Zaharia</name>
    	<email>shertage@users.sourceforge.net</email>
      </author>
    </documentedBy>
    <otherSample ref="accessible"/>
    <otherSample ref="jasper"/>
    <otherSample ref="table"/>
    <otherSample ref="tabular"/>
    <content>
<br/><br/>
<subtitle>PDF/A conformance overview</subtitle>
<br/>
<br/>
In general, PDF/A refers to an ISO standardized set of guidance rules that a rendered PDF document must follow in order to ensure the archiving and long-term 
safeguarding of that document. The PDF/A standard was necessary in order to address the expanding need to ensure that documents intended for preservation 
over a long period of time could be retrieved and rendered in a consistent mode in the future. This requirement is essential for a large variety of 
documents produced in the government, industry and academic environments worldwide.
<br/>
Some features are mandatory to met the PDF/A standard. For instance: specific color management guidelines, support for embedded fonts, support for reading embedded annotations.
All features that are unsuitable for long-term archiving are prohibited. For instance, unembedded fonts, PDF encryption, audio and video content, etc. 

<br/>
<br/>
The PDF/A standards attempts to maximize:
<ul>
<li>Device independence</li>
<li>Self-containment of the document</li>
<li>Self-documentation</li>
</ul>
The constraints include:
<ul>
<li>Fonts must be embedded and also must be legally embeddable for unlimited, universal rendering</li>
<li>Colorspaces must be specified in a device-independent manner</li>
<li>Javascript and executable file triggering are not allowed</li>
<li>Audio and video content are prohibited</li>
<li>Encryption is forbidden</li>
<li>Use of standards-based metadata is mandatory</li>
</ul>
<br/>
<subtitle>PDF/A conformance levels</subtitle>
<br/>
<ol>
<li>PDF/A-1b (<b>b</b>asic PDF/A-1 conformance level represents the minimal compliance required to ensure the preservability over long terms of 
the rendered visual appearance of a document). Level B is a lower level of conformance, including the general requirements of 
<a href="https://www.iso.org/standard/38920.html">ISO 19005-1:2005</a> standard 
regarding the visual appearance of electronic documents, but not their internal structure or semantic properties. All constraints described in the section 
above must be applied to PDF/A-1b compliant documents. <br/>Also, PDF/A-1b documents may contain only scanned images without any representation of text. 
OCR text that supports indexing or extraction of text is permitted, but only if it is invisible.<br/>This conformance level requires the use of PDF 1.4<br/><br/></li>
<li>PDF/A-1b (<b>a</b>ccessible PDF/A-1 conformance level includes all the PDF/A-1b rules, plus a set of rules regarding the document accessibility and reading order). 
PDF/A-1a requires a representation of the logical structure of the document as specified in section 6.8 of <a href="https://www.iso.org/standard/38920.html">ISO 19005-1:2005</a>. 
It is recommended to capture a document's logical structure hierarchy to the finest granularity possible. The standard also indicates that "PDF/A-1 writers should not 
add structural or semantic information that is not explicitly or implicitly present in the source material solely for the purpose of achieving conformance." 
The logical structure of a document will only include the minimal relevant structural tagging.
<br/>In order to obtain persistent accessible documents one should:
<ul>
<li>make use of simple layouts</li>
<li>use alternate text for graphics</li>
<li>never use color or contrast alone to indicate meaning</li>
<li>never convey meaning through design in a way that can't be expressed with the document's text</li>
<li>avoid spanning table cells and complex table structures</li>
<li>avoid table tags without tabular data</li>
<li>avoid illustrations consisted of many small vector graphics</li>
<li>avoid elements overlapping</li>
<li>avoid background images</li>
</ul>
PDF/A-1a requires the use of PDF 1.4.<br/><br/>
</li>
<li>PDF/A-2b (<b>b</b>asic PDF/A-2 conformance level) requires the use of PDF 1.7 (see also <a href="https://www.iso.org/standard/51502.html">ISO 32000-1:2008</a>). 
Conformance rules are described in <a href="https://www.iso.org/standard/50655.html">ISO 19005-2:2011</a> and encapsulates all rules for PDF/A-1b. Additionally includes support for: 
<ul>
<li>compressed Object and XRef streams (for smaller file sizes)</li>
<li>PDF/A-compliant file attachments, portable collections and PDF packages, archiving of sets of documents as individual documents in one file</li>
<li>transparency for graphical elements</li>
<li>JPEG 2000 compression</li>
</ul>
PDF/A-2 imposes a few additional constraints on number of color channels, bit depth, and colorspaces for compatibility with versions of PDF/X and PDF/E current in 2010.<br/><br/>
</li>
<li>PDF/A-2u (<b>u</b>nicode PDF/A-2 conformance level) represents the PDF/A-2b conformance level with the additional requirement that all text in the document have Unicode equivalents.<br/><br/></li>
<li>PDF/A-2a (<b>a</b>ccessible PDF/A-2 conformance level) defines rules for enhanced accessibility and includes the representation of the logical structure of 
the document, as specified in section 6.8 of <a href="https://www.iso.org/standard/50655.html">ISO 19005-2:2011</a>.<br/><br/>
</li>
<li>PDF/A-3b (<b>b</b>asic PDF/A-2 conformance level) requires the use of PDF 1.7 (see also <a href="https://www.iso.org/standard/51502.html">ISO 32000-1:2008</a>). 
Conformance rules are described in <a href="https://www.iso.org/standard/50655.html">ISO 19005-2:2011</a> and encapsulates all rules for PDF/A-2b. PDF/A-3 is equivalent to PDF/A-2, 
except for allowing files in any format to be embedded. Each embedded file in a PDF/A-3 document must be identified in a file specification dictionary (as described 
in section 7.11.3 of <a href="https://www.iso.org/standard/51502.html">ISO 32000-1:2008</a>). The inclusion of a human-readable description of the file is recommended. <br/><br/>
</li>
<li>PDF/A-3u (<b>u</b>nicode PDF/A-3 conformance level) represents the PDF/A-34b conformance level with the additional requirement that all text in the document have Unicode equivalents.<br/><br/></li>
<li>PDF/A-3a (<b>a</b>ccessible PDF/A-3 conformance level) rules are similar to PDF/A-2a.<br/><br/></li>
</ol>
For more information and guidance related to PDF/A conformance levels, also see the following:
<ul>
<li><a href="https://www.loc.gov/preservation/digital/formats/fdd/fdd000125.shtml">PDF/A-1</a></li>
<li><a href="https://www.loc.gov/preservation/digital/formats/fdd/fdd000319.shtml">PDF/A-2</a></li>
<li><a href="https://www.loc.gov/preservation/digital/formats/fdd/fdd000360.shtml">PDF/A-3</a></li>
</ul>
The conformance level for the generated PDF report can be set in JasperReports using the following configuration properties:
<ul>
<li><api href="net/sf/jasperreports/export/PdfExporterConfiguration.html#getPdfaConformance()">getPdfaConformance()</api> - 
Exporter configuration setting used to specify the conformance level of the PDF/A document. Possible values are: 
<br/><br/>
<ul>
<li><code>pdfa1a</code></li>
<li><code>pdfa1b</code></li>
<li><code>pdfa2a</code></li>
<li><code>pdfa2b</code></li>
<li><code>pdfa2u</code></li>
<li><code>pdfa3a</code></li>
<li><code>pdfa3b</code></li>
<li><code>pdfa3u</code></li>
<li><code>none (default)</code></li>
</ul><br/>
</li>
<li><api href="net/sf/jasperreports/export/PdfExporterConfiguration.html#PROPERTY_PDFA_CONFORMANCE">net.sf.jasperreports.export.pdfa.conformance</api> 
- Configuration property used as default for the <code>getPdfaConformance()</code> setting above. It can be set per context or report level.<br/><br/></li>
</ul>
<subtitle name="iccprofile">Color Management Guidelines</subtitle>
<br/>
<br/>
In order to ensure the same appearance for the document on every device, we need to associate a color management profile to the report. An ICC profile is a 
set of data that characterizes a color input or output device, or a color space, according to standards promulgated by the 
<a href="https://en.wikipedia.org/wiki/International_Color_Consortium">International Color Consortium</a> (ICC).
<br/>
ICC profiles are available for both RGB and CMYK color spaces. They can also be embedded in the generated PDF/A compliant document.
<br/>
<br/>
In order to customize the color spaces we can use the following properties:
<ul>
<li><a href="../../config.reference.html#net.sf.jasperreports.export.pdfa.icc.profile.path" target="_blank">net.sf.jasperreports.export.pdfa.icc.profile.path</a> - 
Specifies the path to the ICC profile file for the PDF/A compliant documents. Its value is used as default for the 
<api href="net/sf/jasperreports/export/PdfExporterConfiguration.html#getIccProfilePath()">getIccProfilePath()</api> export configuration setting. </li>
<li><a href="../../config.reference.html#net.sf.jasperreports.export.pdfa.embed.icc.profile" target="_blank">net.sf.jasperreports.export.pdfa.embed.icc.profile</a> 
- Specifies whether the ICC profile, which in this case must be provided by <api href="net/sf/jasperreports/export/PdfExporterConfiguration.html#getIccProfilePath()">getIccProfilePath()</api>, 
is embedded into the PDF. PDFA compliance requires embedding the ICC profile, which inhibits this setting.</li>
<li><a href="../../config.reference.html#net.sf.jasperreports.export.pdf.use.cmyk.colors" target="_blank">net.sf.jasperreports.export.pdf.use.cmyk.colors</a> 
- Specifies whether the ICC profile, which in this case must be provided by <api href="net/sf/jasperreports/export/PdfExporterConfiguration.html#getIccProfilePath()">getIccProfilePath()</api>, 
is used to convert colors from RGB to CMYK color space.<br/><br/></li>
</ul>
<subtitle name="metadata">Additional Properties for PDF/A-1a</subtitle>
<br/>
<br/>
There are 2 more properties to be considered in order to ensure the accessibility requirements for PDF/A level "a" documents:
<ul>
<li><a href="../../config.reference.html#net.sf.jasperreports.export.pdf.metadata.title" target="_blank">net.sf.jasperreports.export.pdf.metadata.title</a> - 
<b>Required.</b> Contains the title information to use for the generated PDF metadata. Its value is used as default for the 
<api href="net/sf/jasperreports/export/PdfExporterConfiguration.html#getMetadataTitle()">getMetadataTitle()</api> export configuration setting. </li>
<li><a href="../../config.reference.html#net.sf.jasperreports.components.table.accessible" target="_blank">net.sf.jasperreports.components.table.accessible</a> 
- Property that enables/disables the automatic addition of specific custom properties to the elements that make up the table and its cells.<br/><br/></li>
</ul>
<subtitle name="section508">Section 508 conformance in Tagged PDF Reports</subtitle>
<br/>
<br/>
A PDF document can be internally structured in order to enable accessibility tools in PDF readers. Based on specific hidden tags in their content, documents can be read 
aloud to people with disabilities. Tagged PDF files comply with the requirements of the Section 508 of the U.S. Rehabilitation Act
(see <a href="https://www.section508.gov">https://www.section508.gov</a>).
<br/>
JasperReports supports Section 508 compliant PDF documents based on the PDF tags. According to a set of built-in configuration properties, 
PDF tags required for accessibility are incorporated into the structure of generated documents.
<br/>
<br/><br/>
<subtitle name="tagged">Tagged PDF Output</subtitle>
<br/>
<br/>
To enable accessibility in generated documents a set of export parameters are available in JasperReports along with their related exporter hint properties:
<ul>
<li>Tagged Documents
<ul>
<li><api href="net/sf/jasperreports/export/PdfExporterConfiguration.html#isTagged()">isTagged()</api> - 
Exporter configuration setting used to turn on the creation of hidden structural tags. By default the feature is turned off.</li>
<li><api href="net/sf/jasperreports/export/PdfExporterConfiguration.html#PROPERTY_TAGGED">net.sf.jasperreports.export.pdf.tagged</api> 
- Configuration property used as default for the <code>isTagged()</code> setting above. It can be set at global or report level.<br/><br/></li>
</ul>
</li>
<li>Tag Language
<ul>
<li><api href="net/sf/jasperreports/export/PdfExporterConfiguration.html#getTagLanguage()">getTagLanguage()</api> - 
Export configuration setting used to specify the language to be used in the language tag of the generated PDF.</li>
<li><api href="net/sf/jasperreports/export/PdfExporterConfiguration.html#PROPERTY_TAG_LANGUAGE">net.sf.jasperreports.export.pdf.tag.language</api> 
- Configuration property used as default for the <code>getTagLanguage()</code> setting above. It can be set at global or report level.<br/><br/></li>
</ul>
</li>
<li>Accessibility Tags
<br/><br/>
The following property can be set per element in JRXML:
<br/><br/>
<api href="net/sf/jasperreports/export/AccessibilityUtil.html#PROPERTY_ACCESSIBILITY_TAG">net.sf.jasperreports.export.accessibility.tag</api> 
<br/><br/>
This property that specifies the type of accessible content introduced by the element. Possible values are:
<br/><br/>
<ul>
<li><code>H1</code></li>
<li><code>H2</code></li>
<li><code>H3</code></li>
<li><code>H4</code></li>
<li><code>H5</code></li>
<li><code>H6</code></li>
<li><code>TABLE</code></li>
<li><code>TABLE_LAYOUT</code></li>
<li><code>COLUMN_HEADER</code></li>
<li><code>ROW_HEADER</code></li>
</ul><br/>
All the next consecutive properties can be set per element and share the same set of possible values (excepting the column span and row span 
properties, which accept numeric values only):<br/><br/>
<ul>
<li><code>start</code> - if this value is set, the element will be marked with a starting PDF tag corresponding to the property.</li>
<li><code>full</code> - if this value is set, the element will be wrapped in a full PDF tag corresponding to the property.</li>
<li><code>end</code> - if this value is set, the element will be marked with an ending PDF tag corresponding to the property.<br/><br/></li>
</ul>
Available properties related to PDF accessibility tags are enumerated below:<br/><br/>
<ul>
<li><api href="net/sf/jasperreports/engine/export/JRPdfExporterTagHelper.html#PROPERTY_TAG_H1">net.sf.jasperreports.export.pdf.tag.h1</api> 
- Property used to mark a text field as a level 1 heading.</li>
<li><api href="net/sf/jasperreports/engine/export/JRPdfExporterTagHelper.html#PROPERTY_TAG_H2">net.sf.jasperreports.export.pdf.tag.h2</api> 
- Property used to mark a text field as a level 2 heading.</li>
<li><api href="net/sf/jasperreports/engine/export/JRPdfExporterTagHelper.html#PROPERTY_TAG_H3">net.sf.jasperreports.export.pdf.tag.h3</api> 
- Property used to mark a text field as a level 3 heading.</li>
<li><api href="net/sf/jasperreports/engine/export/JRPdfExporterTagHelper.html#PROPERTY_TAG_TABLE">net.sf.jasperreports.export.pdf.tag.table</api> 
- Property used to indicate where the table starts and where it ends in the report template.</li>
<li><api href="net/sf/jasperreports/engine/export/JRPdfExporterTagHelper.html#PROPERTY_TAG_TH">net.sf.jasperreports.export.pdf.tag.th</api> 
- Property used to mark heading cells in a table.</li>
<li><api href="net/sf/jasperreports/engine/export/JRPdfExporterTagHelper.html#PROPERTY_TAG_TR">net.sf.jasperreports.export.pdf.tag.tr</api> 
- Property used to indicate where a table row starts and where it ends in the report template.</li>
<li><api href="net/sf/jasperreports/engine/export/JRPdfExporterTagHelper.html#PROPERTY_TAG_TD">net.sf.jasperreports.export.pdf.tag.td</api> 
- Property used to mark detail cells in a table.</li>
<li><api href="net/sf/jasperreports/engine/export/JRPdfExporterTagHelper.html#PROPERTY_TAG_COLSPAN">net.sf.jasperreports.export.pdf.tag.colspan</api> 
- Property used to indicate the column span of a table cell. Allowed values are positive integers.</li>
<li><api href="net/sf/jasperreports/engine/export/JRPdfExporterTagHelper.html#PROPERTY_TAG_ROWSPAN">net.sf.jasperreports.export.pdf.tag.rowspan</api> 
- Property used to indicate the row span of a table cell. Allowed values are positive integers.</li>
</ul>
The use of these individual tag properties is illustrated in the TabularPdfA1Report JRXML sample report.
</li>
</ul>
<br/>
<subtitle name="reading">Alternate Text for Images and Reading Order</subtitle>
<br/>
<br/>
Accessible documents must provide also an alternate text for images and an appropriate reading order. In JasperReports the alternate text for images 
is specified in the <code>&lt;hyperlinkTooltipExpression/&gt;</code> of the image element.
<br/>
The reading order is processed using the Z-order of elements as present in the report template. No additional processing is necessary here.
<br/><br/>
To find out more about tagged PDF output see the "Section 508 conformance" chapter in the JasperReports Ultimate Guide.
<br/> 
<br/>
<br/>
<subtitle name="samples">Sample Reports</subtitle>
<br/>
<br/>
To illustrate various levels of PDF/A conformance, this sample contains the following reports:
<ul>
<li>PdfA1Report - a PDF/A-1a compliant report. It contains an embedded true type font (LiberationSans), a non transparent image of the JasperReports logo and a 
SVG image. All images provide alternate texts. It embeds a RGB type ICC profile</li>
<li>PdfA2Report - a PDF/A-2a compliant report. It contains an embedded true type font (LiberationSans), 2 transparent images of the JasperReports logo and some overlapped elements. 
All images provide alternate texts. It embeds a RGB type ICC profile</li>
<li>PdfA3Report - a PDF/A-3a compliant report, which is in fact similar to PdfA2Report, since there are no other document attachments.</li>
<li>TabularPdfA1Report - a PDF/A-1a compliant report. It contains a table-like structure, with elements tagged individually to generate an accessible PDF table</li>
<li>TaggedPdfA1Report - a PDF/A-1a compliant report. It contains several elements configured for accessibility,  and an accessible table element that automatically 
generates table tags when it is exported to PDF<br/><br/></li>
</ul> 
 
<b>Running the Sample</b>
<br/>
<br/>
Running the sample requires the <a href="http://ant.apache.org/">Apache Ant</a> library. Make sure that <code>ant</code> is already installed on your system (version 1.5 or later).
<br/>
In a command prompt/terminal window set the current folder to <code>demo/samples/table</code> within the JasperReports source project and run the <code>&gt; ant test view</code> command.
<br/>
It will generate The PDF/A compliant documents containing the sample report in the <code>demo/samples/pdfa1/build/reports</code> directory. 
<br/>
Then the report will open in the JasperReports internal viewer.
  
</content>
  </feature>
</sample>
