Package org.faceless.pdf2

Class 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

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

      • 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

      • 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

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

    • 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 
         OutputProfile profile = new OutputProfile(OutputProfile.PDFA1b_2005);
 profile.getOutputIntents().add(new OutputIntent("GTS_PDFA1", "sRGB", ColorSpace.getInstance(ColorSpace.CS_sRGB)));
 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)
        Deprecated.
        manage the OutputIntents through the getOutputIntents() method and OutputIntent class.
        Add an OutputIntent to the profile. Calls setOutputIntent(String,String,String,String,String,ICCColorSpace)
        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 type,
                            String identifier,
                            String description,
                            String registry,
                            String info,
                            ICCColorSpace colorspace)
        Deprecated.
        manage the OutputIntents through the getOutputIntents() method and OutputIntent class.
        Add an OutputIntent to the profile. Since 2.26 we have an OutputIntent class and a getOutputIntents() method, which is a better way to manage OutputIntents. We strong recommend you migrate to those methods. The internals of this method now look (roughly) like this: 
         if (type == null) {
   getOutputIntents().clear();
   for (String s : getRequiredOutputIntentTypes()) {
     OutputIntent intent = new OutputIntent(s, identifier, colorspace, description, info, registry);
     getOutputIntents().add(intent);
   }
 } else {
   OutputIntent intent = new OutputIntent(type, identifier, colorspace, description, info, registry);
   for (Iterator<OutputIntent> i = getOutputIntents().iterator();i.hasNext();) {
     if (i.next().getType().equals(intent.getType())) {
       i.remove();
     }
   }
   getOutputIntents.add(intent);
 }
        Parameters:
        type - 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.
        colorspace - The ICC profile to target. Should always be specified for maximum compatibility unless the identifier is "sRGB".
        Since:
        2.23.2

      • isClosed

        public boolean isClosed()
        Return true if the profile is closed and cannot be modified without cloning first
        Since:
        2.26

      • 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);
        Returns:
        the list of profiles, or an zero-length list if none are claimed.
        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 target)

        Merge the specified OutputProfile into this one, to create an OutputProfile that represents both targets. Calls merge(OutputProfile, OutputProfile) with the second argument set to null.

        Parameters:
        target - the new target profile to merge into this target profile
        Throws:
        ProfileComplianceException - if the target cannot be merged with this profile
        Since:
        2.20

      • merge

        public void merge​(OutputProfile target,
                  OutputProfile extracted)

        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.

        Attempting to merge invalid combinations will throw a ProfileComplianceException - for example, it's not possible to merge ZUGFeRD1_Basic info PDFA1b_2005, as the first requires a file attachment, and the second denies it. Some combinations can only be checked in combination with the extracted OutputProfile of the PDF this profile will be applied to, so for most accurate results we recommend supplying this as the "extracted" parameter.

        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. 

         OutputProfile target = new OutputProfile(OutputProfile.PDFA1b_2005);
 target.getOutputIntents().add(new OutputIntent("GTS_PDFA1", "sRGB", ColorSpace.getColorSpace(ColorSpace.CS_sRGB)));
 try {
     target.merge(OuputProfile.PDFUA1, null);
 } catch (ProfileComplianceException e) {
     System.out.println("Can't combine PDF/UA-1 with " + target.getProfileName());
 }
 PDF pdf = new PDF(target);

        And here's how you might create the same target profile, but to be applied to an existing PDF - almost identical to above, except the features set in the PDF can influence the decision. 

         OutputProfiler profiler = new OutputProfiler(new PDFParser(pdf));
 OutputProfile extracted = profiler.getProfile();

 OutputProfile target = new OutputProfile(OutputProfile.PDFA1b_2005);
 target.getOutputIntents().add(new OutputIntent("GTS_PDFA1", "sRGB", ColorSpace.getColorSpace(ColorSpace.CS_sRGB)));
 try {
     target.merge(OuputProfile.PDFUA1, extracted);
 } catch (ProfileComplianceException e) {
     System.out.println("Can't combine PDF/UA-1 with " + target.getProfileName());
 }
 // Skipping the various setup options of OutputProfiler for brevity
 profiler.apply(target);
        Parameters:
        target - the new target profile to merge into this target profile
        extracted - the extracted profile of the PDF this will be applied to. Optional, may be null.
        Throws:
        ProfileComplianceException - if the target cannot be merged with this profile
        Since:
        2.26

      • denyClaim

        public void denyClaim​(OutputProfile profile)

        Remove any claims made by the specified OutputProfile from this target OutputProfile, by setting the appropriate feature to denied. This is the opposite of merge(org.faceless.pdf2.OutputProfile), and can be used to remove a claim from a PDF.

        For example, to remove a claim of PDF/UA-1 compliance from any PDF which this profile is applied to: 

          OutputProfile target = ...
  target.denyClaim(OutputProfile.PDFUA1)
  outputprofiler.apply(target);
        Since:
        2.26

      • 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

      • getOutputIntents

        public Collection<OutputIntent> getOutputIntents()
        Return a Collection of all OutputIntent objects for this profile. The collection is live and can be modified
        Since:
        2.26

      • getRequiredOutputIntentTypes

        public Collection<String> getRequiredOutputIntentTypes()
        Return a collection of Strings listing the OutputIntent types required for this Profile. For example, if this profile is a PDF/A profile, the retured list will include "GTS_PDFA1". If no intents are required, returns an empty list.
        Since:
        2.26;

      • getOutputIntent

        public OutputIntent getOutputIntent​(String type)
        Return the first OutputIntent with the specified Type, or null if none exists.
        Since:
        2.26;

      • getOutputIntentTypes

        public String[] getOutputIntentTypes()
        Deprecated.
        manage the OutputIntents through the getOutputIntents() method and OutputIntent class.
        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)
        Deprecated.
        manage the OutputIntents through the getOutputIntents() method and OutputIntent class.
        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)
        Deprecated.
        manage the OutputIntents through the getOutputIntents() method and OutputIntent class.
        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)
        Deprecated.
        manage the OutputIntents through the getOutputIntents() method and OutputIntent class.
        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)
        Deprecated.
        manage the OutputIntents through the getOutputIntents() method and OutputIntent class.
        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)
        Deprecated.
        manage the OutputIntents through the getOutputIntents() method and OutputIntent class.
        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

      • getExtensions

        public List<OutputProfile.Extension> getExtensions()
        Return the list of Extensions on the PDF. The returned list can be modified, it will be applied to the PDF when it's saved. Extensions that are required for particular features (eg OutputProfile.Feature.SignatureWithSHA3_256) will be managed automatically by the PDF Library, and added to this list on save if required.
        Returns:
        the list of PDF extensions
        Since:
        2.27.2
        See Also:
        PDF#getOutputProfile, OutputProfile.Extension

      • 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

      • getAssociatedFiles

        public Collection<EmbeddedFile> getAssociatedFiles()

        Return a modifiable collection containing all EmbeddedFile objects found while profiling the PDF. Unlike the Map returned from PDF.getEmbeddedFiles(), this collection also contains any AnnotationFile EmbeddedFiles, and any EmbeddedFiles attached to pages, structure elements or other objects in the PDF: including potentially many objects that are not publicly accessible via the API.

        Because of this, this method is not useful for much except traversing and - if necessary - removing EmbeddedFiles. Remove them from this collection will completely remove them from the PDF.

        Since:
        2.26
        See Also:
        EmbeddedFile.getOwners()

      • getXMPs

        public Collection<XMP> getXMPs()

        Return a modifiable collection containing all XMP objects found while profiling the PDF. XMP Metadata may be grafted onto any object in the PDF hierarchy; while we have methods to retrieve the common ones (eg from the PDF or the PDFPage), this method is the only way to retrieve all of them, including those attached to objects that are not publicly accessible via the API.

        Because of this, this method is not useful for much except traversing and - if necessary - removing XMP. Remove them from this collection will completely remove them from the PDF.

        Since:
        2.26
        See Also:
        XMP.getOwners()

      • getICCColorSpaces

        public Collection<ICCColorSpace> getICCColorSpaces()
        Return a read-only collection of every ICC ColorSpace used in the PDF. This collection is populated when a full OutputProfile is generated by the OutputProfiler class, and will be empty until then
        Since:
        2.26