|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.faceless.pdf2.OutputProfile
public class OutputProfile
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.
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 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. 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
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.
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.
PDF.setOutputProfile(org.faceless.pdf2.OutputProfile)
,
PDF.getFullOutputProfile()
,
PDF.getBasicOutputProfile()
,
OutputProfile.Feature
Nested Class Summary | |
---|---|
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. |
Field Summary | |
---|---|
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 |
PDFA1b_2005
An OutputProfile representing the PDF/A-1b:2005 specification. |
static OutputProfile |
PDFA1b_2005_Acrobat
An OutputProfile representing the PDF/A-1b:2005 specification, as interpreted by Acrobat. |
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 |
Constructor Summary | |
---|---|
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 | |
---|---|
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. |
Set |
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 |
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 |
setDenied(OutputProfile.Feature feature)
Add a feature to the "Denied" list of this 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 |
---|
public static final OutputProfile Default
public static final OutputProfile Acrobat4Compatible
public static final OutputProfile Acrobat5Compatible
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.
public static final OutputProfile Acrobat6Compatible
StandardEncryptionHandler.setAcrobat7Level()
.
public static final OutputProfile Acrobat7Compatible
public static final OutputProfile Acrobat8Compatible
public static final OutputProfile Acrobat9Compatible
public static final OutputProfile AcrobatXCompatible
public static final OutputProfile NoCompression
public static final OutputProfile ImageOnly
Default
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.
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.
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.
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.
public static final OutputProfile PDFX3_2003_Acrobat
PDFX3_2003
insteadPDFX3_2003
instead (this is now
just a synonym for that variable).
public static final OutputProfile NotPDFX
public static final OutputProfile PDFA1b_2005
An OutputProfile representing the PDF/A-1b:2005 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 - see that constructor for a detailed example.
The specification is here
PDFA1b_2005_Acrobat
public static final OutputProfile PDFA1b_2005_Acrobat
An OutputProfile representing the PDF/A-1b:2005 specification, as interpreted by Acrobat.
This is identical to PDFA1b_2005
but requires an OutputIntent of GTS_PDFA
rather than GTS_PDFA1
. This is required to meet the PDF/A-1b preflight test in
Acrobat 7 and 8, although it doesn't match the official PDF/A specification.
Constructor Detail |
---|
public OutputProfile(OutputProfile template, String identifier, String description, String registry, String info, ICC_Profile iccprofile)
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);
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.public OutputProfile(OutputProfile original)
Default
Profile but that will recompress uncompressed objects, do the following:
OutputProfile myprofile = new OutputProfile(OutputProfile.Default); myprofile.setRequired(OutputProfile.Feature.RegularCompression);
original
- the original OutputProfile to copy.Method Detail |
---|
public boolean isSet(OutputProfile.Feature feature)
pdf.getBasicOutputProfile().isSet(OutputProfile.Feature.XFAForm);
feature
- the Feature to checkpublic void setDenied(OutputProfile.Feature feature)
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);
feature
- the Feature to deny
IllegalStateException
- if you try to deny a feature which is already
set or which is marked as required,public void setRequired(OutputProfile.Feature feature)
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.
feature
- the Feature to require
IllegalStateException
- if you try to deny a feature which is already
set or which is marked as required,public void clearDenied(OutputProfile.Feature feature)
OutputProfile newprofile = new OutputProfile(OutputProfile.Acrobat4Compatible); newprofile.clearDenied(OutputProfile.Feature.XMPMetaData);
feature
- the Feature to remove from the denied listpublic void clearRequired(OutputProfile.Feature feature)
feature
- the Feature to remove from the required listpublic boolean isDenied(OutputProfile.Feature feature)
feature
- the Feature to check against the denied listpublic boolean isRequired(OutputProfile.Feature feature)
feature
- the Feature to check against the required listpublic String getProfileName()
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.
public ICC_Profile getOutputIntentDestinationProfile(String type)
null
if none exists.
Currently the only supported Output Intent is PDF/X, so type
must be "GTS_PDFX"
type
- the Output Intent to get the field from - currently either "GTS_PDFX" or "GTS_PDFA1"public String getOutputConditionIdentifier(String type)
type
- the Output Intent to get the field from - currently either "GTS_PDFX" or "GTS_PDFA1"public String getOutputCondition(String type)
null
otherwise.
type
- the Output Intent to get the field from - currently either "GTS_PDFX" or "GTS_PDFA1"public String getOutputIntentInfo(String type)
null
otherwise.
type
- the Output Intent to get the field from - currently either "GTS_PDFX" or "GTS_PDFA1"public String getOutputConditionRegistry(String type)
null
otherwise.
type
- the Output Intent to get the field from - currently either "GTS_PDFX" or "GTS_PDFA1"public Set getFontInfo()
PDF.getFullOutputProfile()
, and may return null
otherwise.
OutputProfile.FontInfo
objectspublic String toString()
toString
in class Object
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |