|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.faceless.pdf2.PDFObject
org.faceless.pdf2.PDFMap
org.faceless.pdf2.PDF
A PDF
describes a single document in Adobe's Portable
Document Format. It is the highest-level object in the package.
The life-cycle of a PDF generally consists of being created, adding
new pages, optionally adding information about the document structure
(e.g. bookmarks), and finally rendering to an OutputStream
.
This class only deals with the structure of the document. To actually
create some content see the PDFPage
class.
import org.faceless.pdf2.*; // Create a new PDF PDF p = new PDF(); // Create a new page PDFPage page = p.newPage(PDF.PAGESIZE_A4); // Create a new "style" to write in - Black 24pt Times Roman. PDFStyle mystyle = new PDFStyle(); mystyle.setFont(new StandardFont(StandardFont.TIMES), 24); mystyle.setFillColor(java.awt.Color.black); // Put something on the page page.setStyle(mystyle); page.drawText("Hello, PDF-viewing World!", 100, 100); // Automatically go to this page when the document is opened. p.setAction(Event.OPEN, PDFAction.goTo(page)); // Add some document info p.setInfo("Author", "Joe Bloggs"); p.setInfo("Title", "My Document"); // Add a bookmark java.util.List bookmarks = p.getBookmarks(); bookmarks.add(new PDFBookmark("Hello World page", PDFAction.goTo(page))); // Write the document to a file OutputStream out = new FileOutputStream("test.pdf"); p.render(out); out.close();
PDFPage
,
PDFReader
Field Summary | |
static String |
PAGESIZE_A4
A parameter to newPage(String) to create a new A4 page - 210x297mm |
static String |
PAGESIZE_A4_LANDSCAPE
A parameter to newPage(String) to create a new landscape A4 page - 297x210mm |
static String |
PAGESIZE_A5
A parameter to newPage(String) to create a new A5 page - 148x210mm |
static String |
PAGESIZE_A5_LANDSCAPE
A parameter to newPage(String) to create a new landscape A5 page - 210x148mm |
static String |
PAGESIZE_LETTER
A parameter to newPage(String) to create a new US Letter page - 8.5x11in |
static String |
PAGESIZE_LETTER_LANDSCAPE
A parameter to newPage(String) to create a new landscape US Letter page - 11x8.5in |
static String |
VERSION
This variable contains the version number of the current build. |
Constructor Summary | |
PDF()
Create a new, empty PDF document |
|
PDF(PDF pdf)
Create a PDF that's a clone of the specified PDF. |
|
PDF(PDFReader reader)
Create a PDF from the specified PDFReader .
|
|
PDF(PDFReader reader,
int revision)
Create a PDF from the specified PDFReader , using the specified
revision of the document. |
Method Summary | |
boolean |
equals(Object o)
|
PDFAction |
getAction(Event event)
Return the action that's performed when the specified event occurs on the document, as set by setAction . |
List |
getBookmarks()
Return the List of bookmarks at the top level of the document. |
String |
getDocumentID(boolean primary)
Returns a String representing this documents unique ID. |
EncryptionHandler |
getEncryptionHandler()
Return the EncryptionHandler used to encrypt the document, or null
if no encryption handler is in use. |
Form |
getForm()
Return the Interactive Form or "AcroForm" object which is part
of each PDF document.
|
Map |
getInfo()
Return the PDF meta information, as set by setInfo() . |
String |
getInfo(String key)
Return document meta information, as set by setInfo() , represented
as a String.
|
String |
getJavaScript()
Return the document-wide JavaScript, as set by setJavaScript(java.lang.String) ,
or null if no JavaScript is defined for this document. |
PDFPage |
getLastPage()
Return the last page of this PDF. |
Locale |
getLocale()
Return the PDF's Locale, as set by setLocale |
Reader |
getMetaData()
Return any XML Metadata associated with the document. |
Map |
getNamedActions()
Return a Map containing all the named actions in the PDF. |
int |
getNumberOfPages()
Return the number of pages in this PDF. |
int |
getNumberOfRevisions()
Return the number of revisions made to the document. |
PDFPage |
getPage(int pagenumber)
Return the specified page. |
List |
getPages()
Returns a List of the documents pages which may be manipulated to reorder, delete or append pages to the document. |
int |
getPDFVersion()
Get the version of the PDF. |
boolean |
getViewerPreference(String key)
Return the value of the specified viewer preference, as set by setViewerPreference . |
void |
importFDF(FDF fdf)
Import the contents of the specified FDF into the PDF document.
|
PDFPage |
newPage(int w,
int h)
Create a new PDFPage object of the specified size and add it to
this PDF. |
PDFPage |
newPage(PDFPage page)
Create a new PDFPage object that is a clone of the specified page, and
add it to this PDF. |
PDFPage |
newPage(String pagesize)
Create a new page of the specified page size and add it to this PDF. |
void |
render(OutputStream out)
This method renders the completed PDF to an OutputStream . |
void |
setAction(Event event,
PDFAction action)
Specify an action to perform when the specified event occurs on the document. |
static void |
setCache(Cache cache)
Set the Cache to be used by the library. |
void |
setEncryptionHandler(EncryptionHandler encrypt)
Set the EncryptionHandler to encrypt this document with. |
void |
setInfo(String key,
Object val)
Set an item of PDF meta-information, such as author or title. |
void |
setJavaScript(String javascript)
Set the document-wide JavaScript. |
void |
setLayout(String layout,
String leftpane)
Controls how the document is initially laid out in the PDF viewer. |
static void |
setLicenseKey(String key)
Set the license key for the library. |
void |
setLocale(Locale locale)
Set the default locale for this document. |
void |
setMetaData(String xmldata)
Set the XML Metadata associated with this document. |
void |
setOutputProfile(OutputProfile profile)
Set the Output Profile to use when rendering this PDF document. |
void |
setViewerPreference(String key,
boolean val)
Set some preferences as to how the document is displayed on screen. |
String |
toString()
|
Methods inherited from class java.lang.Object |
getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
public static final String VERSION
public static final String PAGESIZE_A4
newPage(String)
to create a new A4 page - 210x297mm
public static final String PAGESIZE_A4_LANDSCAPE
newPage(String)
to create a new landscape A4 page - 297x210mm
public static final String PAGESIZE_LETTER
newPage(String)
to create a new US Letter page - 8.5x11in
public static final String PAGESIZE_LETTER_LANDSCAPE
newPage(String)
to create a new landscape US Letter page - 11x8.5in
public static final String PAGESIZE_A5
newPage(String)
to create a new A5 page - 148x210mm
public static final String PAGESIZE_A5_LANDSCAPE
newPage(String)
to create a new landscape A5 page - 210x148mm
Constructor Detail |
public PDF()
public PDF(PDF pdf)
PDFReader
public PDF(PDFReader reader)
PDFReader
.
The PDFReader
class is available as part
of the "Extended Edition" of the PDF library, and
is included with this package. If the document
contains multiple revisions, the latest revision is
loaded.
public PDF(PDFReader reader, int revision)
PDFReader
, using the specified
revision of the document. The PDFReader
class is available as
part of the "Extended Edition" of the PDF library, and is included with
this package. The revision number must be between 0 and
PDFReader.getNumberOfRevisions()
-1, otherwise an IllegalArgumentException
is thrown.
reader
- the PDFReader
to userevision
- the revision number to use - between
PDFReader.getNumberOfRevisions()
-1 to load the latest or 0 to load the oldest revision.
IllegalArgumentException
- if the revision is outside the specified rangeMethod Detail |
public int getPDFVersion()
setOutputProfile(org.faceless.pdf2.OutputProfile)
public void setOutputProfile(OutputProfile profile)
Set the Output Profile to use when rendering this PDF document. Output Profiles
allow you to limit the features used in a document to a specified subset - for
example, Acrobat 4 compatible, PDF/X-1 compatible and so on. See the OutputProfile
class for more information.
getPDFVersion()
public int getNumberOfRevisions()
PDFReader
- all other PDFs
(and many of these too) will return zero. See the PDFReader
class
for more information on revisions.
PDFReader
public PDFPage newPage(String pagesize)
Create a new page of the specified page size and add it to this PDF.
The page size is specified as a string of the form "WxHU", where W is the width
of the page, H is the height of the page, and U is an optional units
specifier - it may be "mm", "cm" or "in", and if it's not specified it's assumed
to be points. The resulting page size is rounded to the nearest integer unless the
units are specified as points (eg. 595.5x842
- fractional sizes added in 2.2.3).
For convenience we've defined several standard sizes that you can pass in,
like PAGESIZE_A4
, PAGESIZE_A4_LANDSCAPE
, PAGESIZE_LETTER
,
PAGESIZE_LETTER_LANDSCAPE
and so on.
Since 2.2.3 you can also pass in a String containing the common name of the paper size, optionally with a "-landscape" suffix, eg "A4", "Letter", "A2-landscape", "DL" and so on. All ISO sizes and most US and JIS paper (and some envelope) sizes are recognised.
Example values include "210x297mm", "595x842" or "A4", which would both produce an A4 page, and "8.5x11in", "612x792" or "Letter", which would both produce a US Letter page.
This method is identical to calling:
PDFPage page = new PDFPage(pagesize); pdf.getPages().add(page);
pagesize
- the size of the page to create
IllegalArgumentException
- if the specified page size cannot be parsedpublic PDFPage newPage(int w, int h)
PDFPage
object of the specified size and add it to
this PDF. The size is specified in points. This method is identical to
calling:
PDFPage page = new PDFPage(w, h); pdf.getPages().add(page);
The arguments are integers for API compatibilty reasons only. If required you can create
pages sized to a fraction of a point using the newPage(String)
method.
w
- the width of the page, in pointsh
- the height of the page, in points
PDFPage
objectgetPages()
public PDFPage newPage(PDFPage page)
PDFPage
object that is a clone of the specified page, and
add it to this PDF. This method is identical to calling:
PDFPage page = new PDFPage(originalpage); pdf.getPages().add(page);
page
- the PDFPage object to clone
PDFPage
object which is a clone of the specified pagegetPages()
public List getPages()
List
methods.
For example, to reverse the pages in the document, you could do something like this:
List pages = pdf.getPages(); List temp = new ArrayList(pages); pages.clear(); for (int i=temp.size()-1;i>=0;i--) { pages.add(temp.get(i)); }or to move (not copy) all the pages from one PDF to another, try
pdf1.getPages().addAll(pdf2.getPages());
public int getNumberOfPages()
pdf.getPages().size()
getPages()
public PDFPage getPage(int pagenumber)
pdf.getPages().get(pagenumber)
pagenumber
- the page number, between 0 and getNumberOfPages()
-1
getPages()
public PDFPage getLastPage()
pdf.getPage(pdf.getNumberOfPages()-1)
getPages()
public void setEncryptionHandler(EncryptionHandler encrypt)
EncryptionHandler
to encrypt this document with. This method
allows you to limit access to the document, either by requiring a password to
open it, preventing the document from being printed and so on, or more.
encrypt
- the EncryptionHandler to be used to encrypt and limit access to the documentEncryptionHandler
,
StandardEncryptionHandler
public EncryptionHandler getEncryptionHandler()
EncryptionHandler
used to encrypt the document, or null
if no encryption handler is in use.
EncryptionHandler
,
StandardEncryptionHandler
public void setInfo(String key, Object val)
Set an item of PDF meta-information, such as author or title.
Although any key or value is valid (except Producer
,
CreationDate
and ModDate
, which are set
by the library internally), the following fields are recognised
by Acrobat:
Title | The document's title. This value must be set for PDF/X documents |
---|---|
Author | The name of the person who created the document. |
Subject | The subject of the document. |
Keywords | Keywords associated with the document. |
Creator | If the document was converted to PDF from another format, the name of the application that created the original document from which it was converted. |
Trapped | The document's trapping status. Must be "True", "False" or "Unknown". This has to be set to "True" or "False" for PDF/X documents |
The value must be String
, Date
, Boolean
or Float
, or
null
to remove that item of meta-information.
Note that this meta-information can be set independently of any XML
meta information as set by setMetaData()
. If no XML
meta-information is set, these values are used to create some basic XML values.
key
- the meta-information field to setval
- the value to set it topublic String getInfo(String key)
Return document meta information, as set by setInfo()
, represented
as a String.
Note that this meta-information can be used independently of any XML
meta information as returned by getMetaData()
.
key
- the field to get
public Map getInfo()
Return the PDF meta information, as set by setInfo()
. This
is in the form of an unmodifable Map
, where the keys are
String
objects, and values may be String
, Date
,
Boolean
, Calendar
or Float
objects. If no
meta information is available, returns an empty Map.
Since version 2.1.2, any keys representing Dates (such as "ModDate" or "CreationDate")
will also have an equivalent entry with a leading underscore, eg. "_ModDate".
These give the same information but as a Calendar
rather than a
Date
. This is to allow extraction of TimeZone information, sadly lacking
from the Date
class.
Note that this meta-information can be used independently of any XML
meta information as returned by getMetaData()
.
public void setLocale(Locale locale)
public Locale getLocale()
setLocale
public void setAction(Event event, PDFAction action)
Event.OPEN
and Event.CLOSE
, which occur
within every version Acrobat, and Event.PRE_SAVE
, Event.POST_SAVE
,
Event.PRE_PRINT
and Event.POST_PRINT
, which only occur
in Acrobat 5.0 or newer viewers.
event
- the event on which to perform the actionaction
- the action to perform, or null
to remove any current actionpublic PDFAction getAction(Event event)
setAction
. If no
action is specified for that event, return null
public void setJavaScript(String javascript)
<HEAD>
of an HTML document.
javascript
- the JavaScript to use for the entire documentgetJavaScript()
,
PDFAction.formJavaScript(java.lang.String)
public String getJavaScript()
setJavaScript(java.lang.String)
,
or null
if no JavaScript is defined for this document.
setJavaScript(java.lang.String)
,
PDFAction.formJavaScript(java.lang.String)
public Map getNamedActions()
Return a Map containing all the named actions in the PDF. Named actions (which must always be "GoTo" type actions) can be referenced from outside the PDF, which allows the document to be opened at a specific location. Here's how to do this:
In the PDF, add the following code:pdf.getNamedActions().put("Myaction", PDFAction.goTo(somepage));Then in your HTML document, add the following code:
<a href="http://www.mycompany.com/mypdf.pdf#Myaction">
The Map returned from this method can be manipulated using the
normal Map
methods to add or delete actions. The only
restrictions is that keys must always be String
objects
and values must always be PDFAction
objects that jump
to a location in the document, like those returned from one of the
PDFAction.goTo...
methods.
public void setMetaData(String xmldata)
Set the XML Metadata associated with this document. This is a PDF 1.4 feature, so it will only be used by Acrobat 5.0 or later - although it should be ignored by earlier viewers.
The value is specified as a String, but as it's XML it will probably be created as a java.io.Writer. Here's an example showing how to use this with SAX and the org.apache.xml.serialize classes. The lines marked in bold could apply to any method of serializing the XML.
void addMetaData(PDF pdf, InputSource source) { // Create a java.io.Writer StringWriter meta = new StringWriter(); // Create a SAX XML serializer using the apache classes // We must not include the XML Declaration in the output. OutputFormat outformat = new OutputFormat(); outformat.setOmitXMLDeclaration(true); Serializer serial = new XMLSerializer(out, outformat); // Create the XML parser and parse the input source XMLReader parser = XMLReaderFactory.createXMLReader(); parser.setContentHandler(serial.asContentHandler()); parser.parse(inputsource); pdf.setMetaData(meta.toString()); }
For more information on XML metadata in PDF documents, see http://www.adobe.com/products/xmp
.
xmldata
- the XML data to embed into the document. No validation is performed
on this input.public Reader getMetaData() throws IOException
Return any XML Metadata associated with the document. XML Metadata is a PDF 1.4 (Acrobat 5.x) feature, so this method will return null for all documents matching earlier specifications or if no metadata is specified.
Here's an example of how to extract the MetaData into a DOM tree. Lines in bold could apply to any parsing method.
InputSource source = new InputSource(pdf.getMetaData()); DOMParser parser = new DOMParser(); parser.parse(source); Document doc = parser.getDocument();
For more information on XML metadata in PDF documents, see http://www.adobe.com/products/xmp
Reader
containing the source of the XML
IOException
public void setLayout(String layout, String leftpane)
pdf.setLayout("OneColumn", "UseOutlines");
layout
- How to display the document if there is more than one page.
Valid values are "SinglePage"
(the default),
"OneColumn"
, "TwoColumnLeft"
or
"TwoColumnRight"
.leftpane
- What to display in the left pane, if anything. Valid values
are "UseNone"
to not show the left pane (the default),
"UseOutlines"
to show the Bookmarks tab, "UseThumbs"
to show the Thumbnails tab or, in Acrobat 6, "UseOC"
to show the
Layers tab.public void setViewerPreference(String key, boolean val)
Set some preferences as to how the document is displayed on screen.
Along with the setLayout
method (which controls
some of the more conventional viewer preferences), this method
allow you to turn on or off some of the more obscure features of the
users PDF viewer application. By default, all these options are set
to false
. Valid options are:
FullScreen | Open the document in full-screen mode |
---|---|
DisplayDocTitle | The window's title bar should display the document title taken from the the Title entry of the getInfo() map. If false the title bar should display the filename instead (only works in Acrobat 5 and later). |
HideToolbar | Hide the viewer application's tool bars when the document is active. |
HideMenubar | Hide the viewer application's menu bar when the document is active. |
HideWindowUI | Hide user interface elements in the document' window (such as scroll bars and navigation controls), leaving only the document's contents displayed. |
FitWindow | Resize the document's window to fit the size of the first displayed page. Note this resizes the window to fit the document, not the other way round. |
CenterWindow | Position the document's window in the center of the screen. Note this moves the whole viewer to the center of the screen, not the document to the center of the viewer. |
Viewers other than Acrobat Reader will probably ignore these options.
key
- the option to set, from the list aboveval
- whether to turn that option on or offpublic boolean getViewerPreference(String key)
setViewerPreference
.
key
- the option to query
public List getBookmarks()
List
contains zero or more PDFBookmark
objects, and can be altered using any
of the standard List
methods to order the documents bookmarks in any way
you see fit. New documents start with an empty list.
PDFBookmark
public String getDocumentID(boolean primary)
Returns a String representing this documents unique ID. The PDF specification recommends (but not requires) that every document is given a unique ID when it's created which is stored in two parts. The primary ID stays constant throughout the life of the document, the secondary should be updated on every revision - although in the first revision of a document they should be the same. So when comparing the IDs of two documents, if the primary and secondary both match you've found the same document, and when only the primary ID matches you've found a different version of the same document.
This method return either the primary or secondary ID,
depending on whether the primary
parameter is true
or false
. The ID is generally just random characters.
Calling this method before the document is created (ie when you've just
created a new PDF but not called render()
) will result in
this method returning null
. It may also return
null
for PDFs that do not have an ID specified, although they
are fairly rare these days.
Although the IDs are stored internally as 16 bytes, we return a String of 32 hex-characters to make them easier to display and compare.
primary
- whether to return the primary or secondary ID
null
if no ID is setpublic Form getForm()
Form
or "AcroForm" object which is part
of each PDF document.
Note that using interactive forms requires the "Extended Edition"
of the library - although the classes are supplied with the package an "Extended
Edition" license must be purchased to activate this functionality.
public void importFDF(FDF fdf)
Import the contents of the specified FDF
into the PDF document.
Any form values specified in the FDF file will be used to set the
corresponding form fields in the PDF, and since 2.2.2 any annotations in
the FDF will be imported as well.
If a field doesn't exist, a warning is printed and the field is ignored.
public void render(OutputStream out) throws IOException
This method renders the completed PDF to an OutputStream
. The stream
is left open on completion. A document may be rendered more than once.
Rendering the document merges all the revisions of a document, so after
rendering the getNumberOfRevisions()
method will always return zero.
out
- the output stream to write the PDF to
IOException
- if the process could not be completedpublic static void setLicenseKey(String key)
Set the license key for the library. When the library is purchased, the Big Faceless Organization supplies a key which removes the "DEMO" stamp on each of the documents.
Please note this method is static - it should be called BEFORE the first PDF is created, like so:
PDF.setLicenseKey(.....); PDF pdf = new PDF();
key
- the license keypublic static void setCache(Cache cache)
Cache
to be used by the library. Note this is a static,
method, which means a single cache is used for all PDFs. This also means you do
not need to call this method more than once, and doing so is not only
inefficient, it could theoretically cause problems in multi-threaded environments
like servlet engines. To repeat - if you are going to call this method, do it once
in an initialization routine before the first PDF is created.
public String toString()
public boolean equals(Object o)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |