org.faceless.pdf2

Class OutputProfile

java.lang.Object

org.faceless.pdf2.OutputProfile

public class OutputProfile
extends Object

An OutputProfile defines a variation on the PDF specification which a document must adhere to. PDF is a large specification and not all features are compatible with all readers. An obvious example is Acrobat 4.0 being unable to read documents created for later versions. Less obvious examples include creating documents compatible with the PDF/X standard used in the printing industry.

Each profile is made up of two lists, "denied" and "required". Trying to use a denied feature in a PDF throws an Exception. And a required feature must be in place before the PDF is written, otherwise again an Exception is thrown.

Applying an OutputProfile to a new PDF

So, how do you use them? First, you can set an OutputProfile on a PDF, which will ensure that when it's rendered it meets the requirements. This is done with the PDF.setOutputProfile() method. Setting this on a brand new PDF ensures you don't inadvertantly create a document that cannot be read on your chosen platform. If you try to use a denied feature, an Exception will be thrown detailing where and what the problem is. However the profile will only verify changes made after it was applied to the PDF, so it should always be the first thing you do to a new PDF. Here's an example - in this case an exception will be thrown on the last line, where you're trying to use an Acrobat 5.0 feature in a document destined for Acrobat 4.0.

 PDF pdf = new PDF();
 pdf.setOutputProfile(OutputProfile.Acrobat4Compatible);
 StandardEncryptionHandler handler = new StandardEncryptionHandler();
 handler.setAcrobat5Level(handler.PRINT_ALL, handler.CHANGE_NONE, handler.EXTRACT_NONE);
 pdf.setEncryptionHandler(handler);  // IllegalStateException thrown here
 

Applying an OutputProfile to an existing PDF

Setting a profile on a PDF that has been read in is a little different, as the PDF needs to be parsed to determine which features it already uses. This functionality was added in release 2.6.1, and centers around the PDF.getFullOutputProfile() method.

The first stage is to call PDF.getFullOutputProfile() on the PDF. This will scan the entire document and determines the full list of features that it uses. This can take some time, and requires the Extended Edition plus Viewer license, but the end result will be a complete list of every feature used in the PDF.

To apply a profile to the PDF you can then call PDF.setOutputProfile(). The library will then attempt to modify the PDF to match the profile - although not all features can be modified successfully (for instance, if the profile requires embedded fonts and the PDF doesn't have them, the library can't fix it). However if the method succeeds without throwing an IllegalStateException then the PDF matches the new profile and can be saved.

Verifying a PDF against an OutputProfile

You can also check to see if a PDF matches a profile in advance by calling the isCompatibleWith() method. This returns a list of Features which may cause problems during conversion. See that method for an example of how to use it.

Also new in 2.6.1 is the OutputProfile.Feature subclass, which lists the individual features which can be checked in an OutputProfile. These features, which will be added to over time, can be added to either list in a Profile via the setRequired(), setDenied(), clearRequired() and clearDenied() methods to customize it. Note that the supplied profiles cannot be modified in this way - you must make a copy with the OutputProfile(OutputProfile) constructor and modify that.

Variations on PDF/A

Finally, we have to point out that PDF/A as a standard has some ambiguities and inconsistancies. These are not major, but if you're working with PDF/A you should be aware of them. They're documented in the Javadoc file describing all the Features with the text Opinion: search for it to identify any contentious areas.

Since:

2.0, with major changes in 2.6.1

See Also:

PDF.setOutputProfile(org.faceless.pdf2.OutputProfile), PDF.getFullOutputProfile(), PDF.getBasicOutputProfile(), OutputProfile.Feature

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	OutputProfile.Feature An OutputProfile is made up of Features, which may be required or denied.
static class	OutputProfile.FontInfo Represents information about a font used in the document.
static class	OutputProfile.Separation Represents an individual "ink" used in the PDF.

Field Summary

Fields

Modifier and Type	Field and Description
static OutputProfile	Acrobat4Compatible Force the document to be Acrobat 4.0 compatible.
static OutputProfile	Acrobat5Compatible Force the document to be Acrobat 5.0 compatible.
static OutputProfile	Acrobat6Compatible Force the document to be Acrobat 6.0 compatible.
static OutputProfile	Acrobat7Compatible Force the document to be Acrobat 7.0 compatible.
static OutputProfile	Acrobat8Compatible Force the document to be Acrobat 8.0 compatible.
static OutputProfile	Acrobat9Compatible Force the document to be Acrobat 9.0 compatible.
static OutputProfile	AcrobatXCompatible Force the document to be Acrobat X compatible.
static OutputProfile	Default This is the default OutputProfile.
static OutputProfile	ImageOnly Add some features to the PDF that are useful when the PDF consists only of one big JPEG image.
static OutputProfile	NoCompression Save the document with no compression.
static OutputProfile	NotPDFX This OutputProfile removes any PDF/X information from the document - useful if a document has been altered and no longer meets that requirement.
static OutputProfile	PDFA1a_2005 An OutputProfile representing the PDF/A-1a:2005 specification (ISO 19005-1, Level A conformance).
static OutputProfile	PDFA1b_2005 An OutputProfile representing the PDF/A-1b:2005 specification (ISO 19005-1, Level B conformance).
static OutputProfile	PDFA2a An OutputProfile representing the PDF/A-2a specification (ISO 19005-2:2011, Level A conformance).
static OutputProfile	PDFA2b An OutputProfile representing the PDF/A-2b specification (ISO 19005-2:2011, Level B conformance).
static OutputProfile	PDFA2u An OutputProfile representing the PDF/A-2u specification (ISO 19005-2:2011 Level U conformance).
static OutputProfile	PDFA3a An OutputProfile representing the PDF/A-3a specification (ISO 19005-3:2012, Level A conformance).
static OutputProfile	PDFA3b An OutputProfile representing the PDF/A-3b specification (ISO 19005-3:2012, Level B conformance).
static OutputProfile	PDFA3u An OutputProfile representing the PDF/A-3u specification (ISO 19005-3, Level U conformance).
static OutputProfile	PDFA4 An OutputProfile representing the PDF/A-4 profile as defined in ISO19005-4:2020.
static OutputProfile	PDFA4e An OutputProfile representing the PDF/A-43 profile as defined in ISO19005-4:2020.
static OutputProfile	PDFA4f An OutputProfile representing the PDF/A-4f profile as defined in ISO19005-4:2020.
static OutputProfile	PDFUA1 An OutputProfile representing the PDF/UA-1 specification (ISO 14289-1).
static OutputProfile	PDFUA2_draft An OutputProfile representing the PDF/UA-2 draft profile.
static OutputProfile	PDFX1a_2001 Save the document so that it conforms to the PDF/X-1a:2001 (ISO15390-1) prepress specification.
static OutputProfile	PDFX1a_2003 Save the document so that it conforms to the PDF/X-1a:2003 (ISO15390-4) prepress specification.
static OutputProfile	PDFX3_2002 Save the document so that it conforms to the PDF/X-3:2002 (ISO15390-3) prepress specification.
static OutputProfile	PDFX3_2003 Save the document so that it conforms to the PDF/X-3:2003 (ISO15390-6) prepress specification.
static OutputProfile	PDFX3_2003_Acrobat Deprecated. use PDFX3_2003 instead
static OutputProfile	PDFX4 The profile representing the PDF/X-4:2010 (ISO15930-7:2010) specification.
static OutputProfile	ZUGFeRD1_Basic An OutputProfile representing the ZUGFeRD 1.0 (Basic Conformance) specification, as defined in http://www.ferd-net.de/front_content.php
static OutputProfile	ZUGFeRD1_Comfort An OutputProfile representing the ZUGFeRD 1.0 (Comfort Conformance) specification, as defined in http://www.ferd-net.de/front_content.php
static OutputProfile	ZUGFeRD1_Extended An OutputProfile representing the ZUGFeRD 1.0 (Extended Conformance) specification, as defined in http://www.ferd-net.de/front_content.php

Constructor Summary

Constructors

Constructor and Description
OutputProfile(OutputProfile original) Create an OutputProfile that is a clone of the specific OutputProfile.
OutputProfile(OutputProfile template, String identifier, String description, String registry, String info, ICC_Profile iccprofile) Create a new OutputProfile based on the PDF/X or PDF/A standard.

Method Summary

Modifier and Type	Method and Description
void	clearDenied(OutputProfile.Feature feature) Remove a Feature from the "Denied" list of a profile.
void	clearRequired(OutputProfile.Feature feature) Remove a Feature from the "Required" list of a profile.
Collection<OutputProfile>	getClaimedTargetProfiles() If this OutputProfile was extracted from a PDF, get the list of target OutputProfiles it claims to match.
List<OutputProfile.Separation>	getColorSeparations() Return a read-only List of color separations used in this PDF.
Set<OutputProfile.FontInfo>	getFontInfo() Returns information about all the fonts used in the document.
String	getOutputCondition(String type) Return the Output Condition for the specified Output Intent if specified, or null otherwise.
String	getOutputConditionIdentifier(String type) Return the Output Condition Identifier for the specified Output Intent.
String	getOutputConditionRegistry(String type) Return the Registry field of the specified Output Intent if specified, or null otherwise.
ICC_Profile	getOutputIntentDestinationProfile(String type) Return the embedded ICC profile for the specified Output Intent, or null if none exists.
String	getOutputIntentInfo(String type) Return the Info field of the specified Output Intent if specified, or null otherwise.
String[]	getOutputIntentTypes() Return the list of OutputIntents on this OutputProfile.
String	getProfileName() Return the descriptive name of the profile
OutputProfile.Feature[]	isCompatibleWith(OutputProfile profile) Check to see if the current OutputProfile matches the requrements of the specified OutputProfile.
boolean	isDenied(OutputProfile.Feature feature) Return true if the Feature is in the "Denied" list in this profile.
boolean	isRequired(OutputProfile.Feature feature) Return true if the Feature is in the "Required" list in this profile.
boolean	isSet(OutputProfile.Feature feature) Return true if the Feature is currently set in this profile.
void	merge(OutputProfile profile) Merge the specified OutputProfile into this one, to create an OutputProfile that represents both targets.
void	setDenied(OutputProfile.Feature feature) Add a feature to the "Denied" list of this profile.
void	setOutputIntent(String intent, String identifier, String description, String registry, String info, ICC_Profile iccprofile) Add an OutputIntent to the profile.
void	setOutputIntent(String intent, String identifier, String description, String registry, String info, ICCColorSpace iccprofile) Add an OutputIntent to the profile.
void	setRequired(OutputProfile.Feature feature) Add a feature to the "Required" list of this profile.
String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

Default

public static final OutputProfile Default

This is the default OutputProfile. The resulting document may not be readable in Acrobat 4 or 5, depending on which features are used (128-bit encryption, for instance).

Acrobat4Compatible

public static final OutputProfile Acrobat4Compatible

Force the document to be Acrobat 4.0 compatible. An error will be thrown if any non-Acrobat 4.x compatible actions are performed. Specifically this includes using alpha transparency, encrypting the document with 128-bit encryption or anything that's not allowed under a later version of Acrobat.

Acrobat5Compatible

public static final OutputProfile Acrobat5Compatible

Force the document to be Acrobat 5.0 compatible. The resulting PDF may not be readable in earlier viewers, and an error will be thrown if any non-Acrobat 5.x compatible actions are performed. The only non-Acrobat 5.x specific features are setting unencrypted metadata in the StandardEncryptionHandler, using characters requiring the UTF-16 encoding in a StandardCJKFont, using AES Encryption, embedding 16-bit or JPX-encoded images, or anything that isn't allowed in a later version of Acrobat.

Acrobat6Compatible

public static final OutputProfile Acrobat6Compatible

Force the document to be Acrobat 6.0 compatible. The resulting document will not be readable in earlier viewers, as it will be compressed using the Document Structure Compression added in Acrobat 6.0 - this results in considerably smaller documents, but which cannot be loaded in older viewers. An error will be thrown if any non-Acrobat 6.x compatible actions are performed. Currently the only Acrobat 7 specific feature is encrypting using AES encryption. See StandardEncryptionHandler.setAcrobat7Level().

Since:

2.4.3

Acrobat7Compatible

public static final OutputProfile Acrobat7Compatible

Force the document to be Acrobat 7.0 compatible. The resulting document may not be readable in earlier viewers depending on features used, and it definitely won't be readable by viewers prior to Acrobat 6.0 as it will be compressed using the Document Structure Compression added in Acrobat 6.0 - this results in considerably smaller documents, but which cannot be loaded in older viewers.

Since:

2.6.1

Acrobat8Compatible

public static final OutputProfile Acrobat8Compatible

Force the document to be Acrobat 8.0 compatible. The resulting document may not be readable in earlier viewers depending on features used, and it definitely won't be readable by viewers prior to Acrobat 6.0 as it will be compressed using the Document Structure Compression added in Acrobat 6.0 - this results in considerably smaller documents, but which cannot be loaded in older viewers.

Since:

2.7.9

Acrobat9Compatible

public static final OutputProfile Acrobat9Compatible

Force the document to be Acrobat 9.0 compatible. The resulting document may not be readable in earlier viewers depending on features used, and it definitely won't be readable by viewers prior to Acrobat 6.0 as it will be compressed using the Document Structure Compression added in Acrobat 6.0 - this results in considerably smaller documents, but which cannot be loaded in older viewers.

Since:

2.11

AcrobatXCompatible

public static final OutputProfile AcrobatXCompatible

Force the document to be Acrobat X compatible. The resulting document may not be readable in earlier viewers depending on features used, and it definitely won't be readable by viewers prior to Acrobat 6.0 as it will be compressed using the Document Structure Compression added in Acrobat 6.0 - this results in considerably smaller documents, but which cannot be loaded in older viewers.

Since:

2.11.23

NoCompression

public static final OutputProfile NoCompression

Save the document with no compression. This is useful for debugging, or (when creating new documents) when speed really matters. Setting this profile on existing documents will result in currently compressed streams being uncompressed.

ImageOnly

public static final OutputProfile ImageOnly

Add some features to the PDF that are useful when the PDF consists only of one big JPEG image. This adds several options when the document is loaded in Acrobat 6.x - specifically the ability to edit and print pictures using the standard "print picture" settings, and also the ability to order photographic prints of the specified image. This only works if the document pages contain a single JPEG image - if not, this setting is the same as Default

PDFX1a_2001

public static final OutputProfile PDFX1a_2001

Save the document so that it conforms to the PDF/X-1a:2001 (ISO15390-1) prepress specification. This places a number of restrictions on the document, including no RGB colors (including RGB alternates for spot colors), only embedded fonts, no encryption/annotations/actions/javascript/transparency, and the "Title" and "Trapped" fields must be set in the documents info dictionary. The full list of requirements is in the ISO specification.

You can use this static OutputProfile to verify documents, but creating new or converting existing documents to this standard requires that they have an Output Intent specified, in which case you should use the OutputProfile(OutputProfile,String,String,String,String,ICC_Profile) constructor to define one.

Since:

2.6.1

PDFX1a_2003

public static final OutputProfile PDFX1a_2003

Save the document so that it conforms to the PDF/X-1a:2003 (ISO15390-4) prepress specification. This is almost identical to PDF/X-1a:2001 except the spec has been brought into line with PDF 1.4

You can use this static OutputProfile to verify documents, but creating new or converting existing documents to this standard requires that they have an Output Intent specified, in which case you should use the OutputProfile(OutputProfile,String,String,String,String,ICC_Profile) constructor to define one.

Since:

2.6.1

PDFX3_2002

public static final OutputProfile PDFX3_2002

Save the document so that it conforms to the PDF/X-3:2002 (ISO15390-3) prepress specification. This profile allows device-independent color to be specified in the document (ICC or other calibrated profiles), provided a suitable profile is defined in the Output Intent. That profile may be GrayScale, RGB or CMYK.

You can use this static OutputProfile to verify documents, but creating new or converting existing documents to this standard requires that they have an Output Intent specified, in which case you should use the OutputProfile(OutputProfile,String,String,String,String,ICC_Profile) constructor to define one.

Since:

2.6.1

PDFX3_2003

public static final OutputProfile PDFX3_2003

Save the document so that it conforms to the PDF/X-3:2003 (ISO15390-6) prepress specification. This is an updated version of PDF/X-3:2002 and basically identical except the allowed PDF version is 1.4

You can use this static OutputProfile to verify documents, but creating new or converting existing documents to this standard requires that they have an Output Intent specified, in which case you should use the OutputProfile(OutputProfile,String,String,String,String,ICC_Profile) constructor to define one.

Since:

2.6.1

PDFX4

public static final OutputProfile PDFX4

The profile representing the PDF/X-4:2010 (ISO15930-7:2010) specification.

You can use this static OutputProfile to verify documents, but creating new or converting existing documents to this standard requires that they have an Output Intent specified, in which case you should use the OutputProfile(OutputProfile,String,String,String,String,ICC_Profile) constructor to define one.

Since:

2.24.3

PDFX3_2003_Acrobat

@Deprecated
public static final OutputProfile PDFX3_2003_Acrobat

Deprecated. use PDFX3_2003 instead

A deprecated profile. Preflighting corrections in 2.11.5 mean this is no longer required, so please use PDFX3_2003 instead (this is now just a synonym for that variable).

Since:

2.11.3

NotPDFX

public static final OutputProfile NotPDFX

This OutputProfile removes any PDF/X information from the document - useful if a document has been altered and no longer meets that requirement.

Since:

2.6.1

PDFA1b_2005

public static final OutputProfile PDFA1b_2005

An OutputProfile representing the PDF/A-1b:2005 specification (ISO 19005-1, Level B conformance). You can use this static OutputProfile to verify documents, but creating new or converting existing documents to this standard requires that they have an Output Intent specified, in which case you should use the OutputProfile(OutputProfile,String,String,String,String,ICC_Profile) constructor to define one - see that constructor for a detailed example. The specification is here

Since:

2.6.7

See Also:

PDFA1a_2005, PDFA2b, PDFA3b

PDFA1a_2005

public static final OutputProfile PDFA1a_2005

An OutputProfile representing the PDF/A-1a:2005 specification (ISO 19005-1, Level A conformance). This is identical to PDF/A-1b, but requires all content in the PDF to be tagged.

More strictly, it requires all document content to meet all of the requirements set forth for Tagged PDF in PDF Reference 9.7.: in practice this means that although the PDF must be marked as tagged and tagged using only the standard set of tags defined in that section, in practice most of the additional requiremetns of that section of the specification are viewed as informative; for example, table elements hierarchy rules are not enforced.

You can use this static OutputProfile to verify documents, but creating new or converting existing documents to this standard requires that they have an Output Intent specified, in which case you should use the OutputProfile(OutputProfile,String,String,String,String,ICC_Profile) constructor to define one - see that constructor for a detailed example. The specification is here

Since:

2.20

See Also:

PDFA1b_2005, PDFA2a, PDFA3a

PDFA2b

public static final OutputProfile PDFA2b

An OutputProfile representing the PDF/A-2b specification (ISO 19005-2:2011, Level B conformance). You can use this static OutputProfile to verify documents, but creating new or converting existing documents to this standard requires that they have an Output Intent specified, in which case you should use the OutputProfile(OutputProfile,String,String,String,String,ICC_Profile) constructor to define one - see that constructor for a detailed example.

The specification is available for download here

Since:

2.14.1

See Also:

PDFA1b_2005, PDFA2a, PDFA3b

PDFA2a

public static final OutputProfile PDFA2a

An OutputProfile representing the PDF/A-2a specification (ISO 19005-2:2011, Level A conformance). This is identical to PDF/A-2b, but requires all content in the PDF to be tagged.

More strictly, it requires all document content to ...meet all of the requirements set forth for Tagged PDF in ISO32000-1:2008, 14.8.. This is a more detailed requirement than the equivalent from PDF/A-1a, and Acrobat does not enforce these restrictions strictly enough. We anticipate the restrictions we apply for this feature may be revised in later revisions as we find more tools to test against.

You can use this static OutputProfile to verify documents, but creating new or converting existing documents to this standard requires that they have an Output Intent specified, in which case you should use the OutputProfile(OutputProfile,String,String,String,String,ICC_Profile) constructor to define one - see that constructor for a detailed example.

The specification is available for download here

Since:

2.20

See Also:

PDFA1a_2005, PDFA2b, PDFA3a

PDFA2u

public static final OutputProfile PDFA2u

An OutputProfile representing the PDF/A-2u specification (ISO 19005-2:2011 Level U conformance). You can use this static OutputProfile to verify documents, but creating new or converting existing documents to this standard requires that they have an Output Intent specified, in which case you should use the OutputProfile(OutputProfile,String,String,String,String,ICC_Profile) constructor to define one - see that constructor for a detailed example.

Since:

2.20.1

See Also:

PDFA2b, PDFA3u

PDFA3b

public static final OutputProfile PDFA3b

An OutputProfile representing the PDF/A-3b specification (ISO 19005-3:2012, Level B conformance). You can use this static OutputProfile to verify documents, but creating new or converting existing documents to this standard requires that they have an Output Intent specified, in which case you should use the OutputProfile(OutputProfile,String,String,String,String,ICC_Profile) constructor to define one - see that constructor for a detailed example.

The specification is available for download here

Since:

2.14.1

See Also:

PDFA1b_2005, PDFA2b, PDFA3a

PDFA3a

public static final OutputProfile PDFA3a

An OutputProfile representing the PDF/A-3a specification (ISO 19005-3:2012, Level A conformance). This is identical to PDF/A-3b, but requires all content in the PDF to be tagged.

More strictly, it requires all document content to ...meet all of the requirements set forth for Tagged PDF in ISO32000-1:2008, 14.8.. This is a more detailed requirement than the equivalent from PDF/A-1a (but basically identical to PDF/A-2a), and Acrobat does not enforce these restrictions strictly enough. We anticipate the restrictions we apply for this feature may be revised in later revisions as we find more tools to test against.

You can use this static OutputProfile to verify documents, but creating new or converting existing documents to this standard requires that they have an Output Intent specified, in which case you should use the OutputProfile(OutputProfile,String,String,String,String,ICC_Profile) constructor to define one - see that constructor for a detailed example.

The specification is available for download here

Since:

2.20

See Also:

PDFA1a_2005, PDFA2a, PDFA3b

PDFA3u

public static final OutputProfile PDFA3u

An OutputProfile representing the PDF/A-3u specification (ISO 19005-3, Level U conformance). You can use this static OutputProfile to verify documents, but creating new or converting existing documents to this standard requires that they have an Output Intent specified, in which case you should use the OutputProfile(OutputProfile,String,String,String,String,ICC_Profile) constructor to define one - see that constructor for a detailed example.

Since:

2.20.1

See Also:

PDFA3b, PDFA2u

PDFA4

public static final OutputProfile PDFA4

An OutputProfile representing the PDF/A-4 profile as defined in ISO19005-4:2020. You can use this static OutputProfile to verify documents, but creating new or converting existing documents to this standard requires that they have an Output Intent specified, in which case you should use the OutputProfile(OutputProfile,String,String,String,String,ICC_Profile) constructor to define one - see that constructor for a detailed example.

This is the first PDF/A profile based on PDF 2.0, but otherwise has the broad concepts as PDF/A-1b, PDF/A-2u and PDF/A-3u. Unlike earlier revisions, tagging of document content is not an aspect of PDF/A4, so there is no level "a" compliance as with earlier revisions.

This base level of PDF/A-4 does not allow File attachments that are not themselves PDF/A, and does not allow rich-media annotations. For those, see the other conformance levels.

Since:

2.25

See Also:

PDFA4e, PDFA4f

PDFA4e

public static final OutputProfile PDFA4e

An OutputProfile representing the PDF/A-43 profile as defined in ISO19005-4:2020. This is identical to PDF/A-4, but allows file attachments that are not themselves PDF/A (as in PDF/A-4f) and also rich-media/3D annotations - the "e" is for "engineering". This is the most permissive conformance level of PDF/A-4.

Since:

2.25

See Also:

PDFA4f, PDFA4

PDFA4f

public static final OutputProfile PDFA4f

An OutputProfile representing the PDF/A-4f profile as defined in ISO19005-4:2020. This is identical to PDF/A-4, but allows file attachments that are not themselves PDF/A.

Since:

2.25

See Also:

PDFA4e, PDFA4

PDFUA1

public static final OutputProfile PDFUA1

An OutputProfile representing the PDF/UA-1 specification (ISO 14289-1).

Since:

2.20

PDFUA2_draft

public static final OutputProfile PDFUA2_draft

An OutputProfile representing the PDF/UA-2 draft profile. This is for testing only. It should not used, and this object will disappear from the API once PDF/UA-2 is finalized.

ZUGFeRD1_Basic

public static final OutputProfile ZUGFeRD1_Basic

An OutputProfile representing the ZUGFeRD 1.0 (Basic Conformance) specification, as defined in http://www.ferd-net.de/front_content.php

Since:

2.20.1

ZUGFeRD1_Comfort

public static final OutputProfile ZUGFeRD1_Comfort

An OutputProfile representing the ZUGFeRD 1.0 (Comfort Conformance) specification, as defined in http://www.ferd-net.de/front_content.php

Since:

2.20.1

ZUGFeRD1_Extended

public static final OutputProfile ZUGFeRD1_Extended

An OutputProfile representing the ZUGFeRD 1.0 (Extended Conformance) specification, as defined in http://www.ferd-net.de/front_content.php

Since:

2.20.1

Constructor Detail

OutputProfile

public OutputProfile(OutputProfile template,
                     String identifier,
                     String description,
                     String registry,
                     String info,
                     ICC_Profile iccprofile)

Create a new OutputProfile based on the PDF/X or PDF/A standard. This constructor defines an Output Intent, which is required for valid PDF/X or PDF/A documents. If the Registry is "http://www.color.org" then technically the ICC Profile is optional, although we always recommend including it (as otherwise Separation and DeviceN colors will not work and some Acrobat 8.0 based workflows may have problems). A special exception is if the identifier is set to "sRGB", in which case the sRGB profile will be embedded automatically.

For example, to preflight a document using PDF/X-1a:2001 with an Output Condition of "CGATS TR 001":

 ICC_Profile icc = ICC_Profile.getInstance("US_Web_Coated_SWOP.icm");
 OutputProfile profile = new OutputProfile(OutputProfile.PDFX1a_2001, "CGATS TR 001", null, "http://www.color.org", null, icc);
 pdf.setOutputProfile(profile);
 

or, to create a small but perfectly formed PDF/A-1b:2005 document

 ICC_Profile icc = ICC_Profile.getInstance(ColorSpace.CS_sRGB);
 OutputProfile profile = new OutputProfile(OutputProfile.PDFA1b_2005, "sRGB", null, "http://www.color.org", null, icc);
 PDF.setLicenseKey(...);   // If no license key is set the "DEMO" stamp will invalidate the PDF
 PDF pdf = new PDF();
 pdf.setOutputProfile(profile);
 PDFPage page = pdf.newPage("A4");
 PDFStyle style = new PDFStyle();
 PDFFont font = new OpenTypeFont(new FileInputStream("font.ttf"), 2);  // Load font to embed
 style.setFont(font, 24);
 style.setFillColor(Color.black); // Must be RGB as we're using sRGB Output Intent.
 page.setStyle(style);
 page.drawText("Hello, PDF/A World", 100, 600);
 pdf.setInfo("Author", "my name");
 pdf.setInfo("Title", "my title");
 pdf.render(outputstream);
 

Parameters:

template - the OutputProfile to base this profile on. Must be PDFX1a_2001, PDFX1a_2003, PDFX3_2002, PDFX3_2003 or PDFA1b_2005

identifier - The name of the output condition, eg "CGATS TR 001" or "sRGB". Required.

description - An optional description of the condition. If the identifier is "CGATS TR 001", "IFRA22", "IFRA28", "FOGRA27", "FOGRA28", "FOGRA29" or "FOGRA30", or the profile is sRGB, then this may be null to use the standard description.

registry - The registry in which the condition is specified. If a profile is specified this is optional, otherwise it's usually the string "http://www.color.org"

info - Additional information about the condition. Optional.

iccprofile - The ICC profile to target. Optional only if a common profile (like sRGB) is used.

Since:

2.6.1

OutputProfile

public OutputProfile(OutputProfile original)

Create an OutputProfile that is a clone of the specific OutputProfile. This is necessary when setting optional flags, because the static OutputProfiles cannot be modifed. For example, to create an OutputProfile that is identical to the Default Profile but that will recompress uncompressed objects, do the following:

 OutputProfile myprofile = new OutputProfile(OutputProfile.Default);
 myprofile.setRequired(OutputProfile.Feature.RegularCompression);
 

Parameters:

original - the original OutputProfile to copy.

Since:

2.3.6

Method Detail

setOutputIntent

public void setOutputIntent(String intent,
                            String identifier,
                            String description,
                            String registry,
                            String info,
                            ICC_Profile iccprofile)

Add an OutputIntent to the profile. If the supplied identifier is in the registry of characterization data at http://www.color.org, the description and info fields will be populated if that information is available. If all values except "intent" are null, the existing intent is deleted.

Parameters:

intent - the intent, which is typically "GTS_PDFX" or "GTS_PDFA". If null, this intent will replace all existing intents on the profile.

identifier - The name of the output condition, eg "CGATS TR 001" or "sRGB". If null, the library will attempt to extract the identifier from the ICC profile

description - An optional description of the condition.

registry - The registry in which the condition is specified.

info - Additional information about the condition.

iccprofile - The ICC profile to target. Should always be specified for maximum compatibility unless the identifier is "sRGB".

Since:

2.17.1

setOutputIntent

public void setOutputIntent(String intent,
                            String identifier,
                            String description,
                            String registry,
                            String info,
                            ICCColorSpace iccprofile)

Add an OutputIntent to the profile. If the supplied identifier is in the registry of characterization data at http://www.color.org, the description and info fields will be populated if that information is available. If all values except "intent" are null, the existing intent is deleted.

Parameters:

intent - the intent, which is typically "GTS_PDFX" or "GTS_PDFA". If null, this intent will replace all existing intents on the profile.

identifier - The name of the output condition, eg "CGATS TR 001" or "sRGB". If null, the library will attempt to extract the identifier from the ICC profile

description - An optional description of the condition.

registry - The registry in which the condition is specified.

info - Additional information about the condition.

iccprofile - The ICC profile to target. Should always be specified for maximum compatibility unless the identifier is "sRGB".

Since:

2.23.2

getClaimedTargetProfiles

public Collection<OutputProfile> getClaimedTargetProfiles()

If this OutputProfile was extracted from a PDF, get the list of target OutputProfiles it claims to match. For example, if run on a document that claims to meet both PDF/A-3a and PDF/UA-1

  PDF pdf = new PDF(new PDFReaader(new File("sample.pdf")));
  OutputProfiler profiler = new OutputProfiler(new PDFParser(pdf));
  OutputProfile profile = profiler.getProfile();
  Collection<OutputProfile> targets = profile.getClaimedTargetProfiles();
  assert targets.contains(OutputProfile.PDFA3a);
  assert targets.contains(OutputProfile.PDFUA1);
 

Since:

2.20.1

isSet

public boolean isSet(OutputProfile.Feature feature)

Return true if the Feature is currently set in this profile. This is how you determine which features a PDF has. For instance, to see if a PDF contains an XFA Form, you can do

 pdf.getBasicOutputProfile().isSet(OutputProfile.Feature.XFAForm);
 

Parameters:

feature - the Feature to check

Since:

2.6.1

setDenied

public void setDenied(OutputProfile.Feature feature)

Add a feature to the "Denied" list of this profile. You can use this method to alter how the final PDF is written. For example, to cause all ICC profiles to be converted to Calibrated where possible:

 OutputProfile profile = new OutputProfile(OutputProfile.Default);
 profile.setDenied(OutputProfile.Feature.ColorSpaceICC);
 

or, to cause a PDF previously saved with a Compressed XRef table to be stored with a normal one:

 OutputProfile profile = new OutputProfile(OutputProfile.Default);
 profile.setDenied(OutputProfile.Feature.CompressedXRef);
 

Parameters:

feature - the Feature to deny

Throws:

IllegalStateException - if you try to deny a feature which is already set or which is marked as required,

Since:

2.6.1

setRequired

public void setRequired(OutputProfile.Feature feature)

Add a feature to the "Required" list of this profile. You can use this method to alter how the final PDF is written. For example, to cause all streams in the PDF to be compressed if they weren't already:

 OutputProfile profile = new OutputProfile(OutputProfile.Default);
 profile.setRequired(OutputProfile.Feature.RegularCompression);
 

Not all feature make sense to require. For instance, requiring a OutputProfile.Feature.PostScriptXObject is simply going to cause your PDFs to fail when rendering, because the library doesn't create them.

Parameters:

feature - the Feature to require

Throws:

IllegalStateException - if you try to deny a feature which is already set or which is marked as required,

Since:

2.6.1

clearDenied

public void clearDenied(OutputProfile.Feature feature)

Remove a Feature from the "Denied" list of a profile. Setting this feature in the PDF will no longer cause an exception. For example, to write Acrobat 4.0 compatible PDFs but still allow XMP Metadata, do the following:

 OutputProfile newprofile = new OutputProfile(OutputProfile.Acrobat4Compatible);
 newprofile.clearDenied(OutputProfile.Feature.XMPMetaData);
 

Parameters:

feature - the Feature to remove from the denied list

Since:

2.6.1

clearRequired

public void clearRequired(OutputProfile.Feature feature)

Remove a Feature from the "Required" list of a profile. This will no longer cause the PDF to fail when writing if the feature is not set.

Parameters:

feature - the Feature to remove from the required list

Since:

2.6.1

isDenied

public boolean isDenied(OutputProfile.Feature feature)

Return true if the Feature is in the "Denied" list in this profile.

Parameters:

feature - the Feature to check against the denied list

Since:

2.6.1

isRequired

public boolean isRequired(OutputProfile.Feature feature)

Return true if the Feature is in the "Required" list in this profile.

Parameters:

feature - the Feature to check against the required list

Since:

2.6.1

merge

public void merge(OutputProfile profile)

Merge the specified OutputProfile into this one, to create an OutputProfile that represents both targets. This is primarily useful when used with PDF/UA, to allow the creation of a PDF that is compliant with both PDF/UA and another profile, such as PDF/A

Here's how to do just that, by merging the PDF/UA-1 profile with the PDF/A-3a profile before applying it to a new PDF.

 ICC_Profile icc = ICC_Profile.getInstance(ColorSpace.CS_sRGB);
 OutputProfile profile = new OutputProfile(OutputProfile.PDFA3a, "sRGB", null, "http://www.color.org", null, icc);
 profile.merge(OutputProfile.PDFUA1);
 PDF pdf = new PDF(profile);
 

Since:

2.20

getProfileName

public String getProfileName()

Return the descriptive name of the profile

isCompatibleWith

public OutputProfile.Feature[] isCompatibleWith(OutputProfile profile)

Check to see if the current OutputProfile matches the requrements of the specified OutputProfile. This method returns null if this profile is compatible, otherwise it returns a List of the features that caused this profile not to match. Those features will either be set and denied in the specified profile, or not set but required in the specified profile.

This is best demonstrated with an example. Here is how you would run a pre-flight check on a PDF for PDF/X-1a:2001 compatibility.

 PDF pdf = new PDF(new PDFReader(new File("test.pdf")));
 OutputProfile profile = pdf.getFullOutputProfile();
 OutputProfile.Feature[] mismatch = profile.isCompatibleWith(OutputProfile.PDFX1a_2001);
 if (mismatch == null) {
     System.out.println("PDF verified against PDF/X-1a");
 } else {
    for (int i=0;i<mismatch.length;i++) {
        if (profile.isSet(mismatch[i])) {
            System.out.println(mismatch[i]+" is not allowed in PDF/X-1a");
        } else {
            System.out.println(mismatch[i]+" is required in PDF/X-1a but not set");
        }
    }
 }
 

Note that as some features aren't set until a PDF is rendered, checking a new PDF to see if it matches it's profile won't always succeed.

If the supplied profile has an Output Intent set, it is assumed that that Intent will be used to replace any OutputIntent on this profile. So, for example, if this profile has DeviceRGB content and the supplied profile has a CMYK OutputIntent, the feature OutputProfile.Feature.DeviceRGBWithCMYKIntent will be considered. This is new functionality in 2.24.4 - prior to that, the Intent on the supplied profile was not considered.

Returns:

an array of Features that don't match the supplied profile, or null if there is no mismatch

Since:

2.6.1

getOutputIntentTypes

public String[] getOutputIntentTypes()

Return the list of OutputIntents on this OutputProfile. The returns types can be passed into methods like getOutputIntentDestinationProfile(java.lang.String) for more details If there are no intents, since 2.24.3 a zero-length array is returned (prior to that it was null).

Since:

2.18

getOutputIntentDestinationProfile

public ICC_Profile getOutputIntentDestinationProfile(String type)

Return the embedded ICC profile for the specified Output Intent, or null if none exists.

Parameters:

type - the Output Intent to get the field from - currently either "GTS_PDFX", "GTS_PDFA1" or "ISO_PDFE1"

Since:

2.6.1

getOutputConditionIdentifier

public String getOutputConditionIdentifier(String type)

Return the Output Condition Identifier for the specified Output Intent.

Parameters:

type - the Output Intent to get the field from - currently either "GTS_PDFX" or "GTS_PDFA1"

Since:

2.6.1

getOutputCondition

public String getOutputCondition(String type)

Return the Output Condition for the specified Output Intent if specified, or null otherwise.

Parameters:

type - the Output Intent to get the field from - currently either "GTS_PDFX" or "GTS_PDFA1"

Since:

2.6.1

getOutputIntentInfo

public String getOutputIntentInfo(String type)

Return the Info field of the specified Output Intent if specified, or null otherwise.

Parameters:

type - the Output Intent to get the field from - currently either "GTS_PDFX" or "GTS_PDFA1"

Since:

2.6.1

getOutputConditionRegistry

public String getOutputConditionRegistry(String type)

Return the Registry field of the specified Output Intent if specified, or null otherwise.

Parameters:

type - the Output Intent to get the field from - currently either "GTS_PDFX" or "GTS_PDFA1"

Since:

2.6.1

getFontInfo

public Set<OutputProfile.FontInfo> getFontInfo()

Returns information about all the fonts used in the document. This information is only available from the result of calling PDF.getFullOutputProfile(), and may return null otherwise.

Returns:

a read-only set of OutputProfile.FontInfo objects

Since:

2.11.9

getColorSeparations

public List<OutputProfile.Separation> getColorSeparations()

Return a read-only List of color separations used in this PDF. Process colors are not included, unless they are explicitly referenced from a Separation or DeviceN colorspace. The order of the returned colors is undefined, unless the OutputProfile.Feature.NChannelPrintingOrder property is set.

If a Separation name is specified multiple times in the PDF and the definitions are not identical, then it will be listed multiple times in the returned array. Note this will also result in the OutputProfile.Feature.RedefinedSeparation being set, and so would not be allowed in PDF/A-4 and PDF/X-4

Since:

2.24.3

toString

public String toString()

Overrides:

toString in class Object