java.lang.Object
- com.pd4ml.pdf.PdfDocumentBase

Direct Known Subclasses:

PdfDocument
```
public abstract class PdfDocumentBase
extends java.lang.Object
```
The base class of PdfDocument: an existing PDF document that can be inspected, changed and saved.
The document is parsed when it is first needed (or by an explicit read() call). Changes are kept in memory until write(OutputStream) is called. A document can be combined with one other document per write: either appended (append(PdfDocumentBase)) or laid over or under it (overlay(PdfDocumentBase, int), underlay(PdfDocumentBase, int)). To combine more documents, write the result and load it again.
Page numbers are 1-based, except in getPageContent(int).

Constructor Summary

Constructors
Constructor	Description
`PdfDocumentBase(byte[] bytes, java.lang.String password)`	Creates a document from PDF bytes.
`PdfDocumentBase(java.io.InputStream stream, java.lang.String password)`	Creates a document from a stream.
`PdfDocumentBase(java.net.URL url, java.lang.String password)`	Creates a document from a URL.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`void`	`append(PdfDocumentBase toMerge)`	Appends the pages of another document after the pages of this one.
`static boolean[]`	`computeScope(java.lang.String scope, int pageNum)`	Evaluates a page scope: tells for each page of a document whether the scope selects it.
`int`	`deletePage(int pageNumber)`	Deletes a page.
`java.lang.String`	`dumpOutlines()`	Returns a text dump of the bookmark (outline) tree, for diagnostics.
`java.lang.String`	`getAuthor()`	Returns the author from the document properties.
`java.lang.String`	`getCreationDate()`	Returns the creation date from the document properties.
`java.lang.String`	`getCreator()`	Returns the creator from the document properties: the application the original document was created with.
`java.lang.String`	`getKeywords()`	Returns the keywords from the document properties.
`java.lang.String`	`getMetadata()`	Returns the XMP metadata of the document, for example to check its PDF/A conformance declaration.
`java.lang.String`	`getModDate()`	Returns the modification date from the document properties.
`int`	`getNumberOfPages()`	Returns the number of pages, including the pages of an appended document.
`float[]`	`getPageBox(int pageIndex, java.lang.String boxName)`	Returns a page boundary box.
`java.lang.String`	`getPageContent(int pageIndex)`	Returns the decoded content stream of a page: the PDF drawing operators, for diagnostics or simple text checks.
`PageSize`	`getPageSize(int pageIndex)`	Returns the size of a page: the size of its crop box (the area viewers show), or of its media box if it has no crop box.
`java.lang.String`	`getPdfFormatVersion()`	Returns the PDF version of the document, from its file header.
`int`	`getPermissions()`	Returns the access permissions of the document, as a combination of the `Constants.Allow*` flags.
`java.lang.String`	`getProducer()`	Returns the producer from the document properties: the software that wrote the PDF.
`java.lang.String`	`getSubject()`	Returns the subject from the document properties.
`java.lang.String`	`getTitle()`	Returns the title from the document properties.
`void`	`overlay(PdfDocumentBase anotherDoc, int opacity)`	Draws the pages of another document over the pages of this one, for example to stamp a watermark or a "COPY" label.
`void`	`overlay(PdfDocumentBase anotherDoc, java.lang.String srcScope, java.lang.String destScope, int opacity)`	Draws selected pages of another document over selected pages of this one.
`void`	`read()`	Loads and parses the document.
`void`	`setAuthor(java.lang.String author)`	Sets the author in the document properties.
`void`	`setCreator(java.lang.String creator)`	Sets the creator in the document properties.
`void`	`setKeywords(java.lang.String keywords)`	Sets the keywords in the document properties.
`void`	`setModDate()`	Sets the modification date in the document properties to the current time.
`void`	`setSubject(java.lang.String subject)`	Sets the subject in the document properties.
`void`	`setTitle(java.lang.String title)`	Sets the title in the document properties.
`void`	`underlay(PdfDocumentBase anotherDoc, int opacity)`	Draws the pages of another document under the pages of this one, for example a letterhead or a page background.
`void`	`underlay(PdfDocumentBase anotherDoc, java.lang.String srcScope, java.lang.String destScope, int opacity)`	Draws selected pages of another document under selected pages of this one.
`void`	`write(java.io.OutputStream out)`	Writes the document with all changes, unencrypted, and closes the stream.
`void`	`write(java.io.OutputStream out, java.lang.String password, int permissions)`	Writes the document with all changes and closes the stream, optionally encrypted.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - PdfDocumentBase
```
public PdfDocumentBase(byte[] bytes,
                       java.lang.String password)
                throws InvokeException
```
    Creates a document from PDF bytes.
    
    Parameters:
    
    bytes - the PDF document; the array is used directly, not copied
    
    password - the password of an encrypted document, or null if it is not encrypted
    
    Throws:
    
    InvokeException - if bytes is null or too short to be a PDF document
  - PdfDocumentBase
```
public PdfDocumentBase(java.io.InputStream stream,
                       java.lang.String password)
                throws InvokeException
```
    Creates a document from a stream. The stream is read completely and closed when the document is first needed.
    
    Parameters:
    
    stream - the PDF document stream
    
    password - the password of an encrypted document, or null if it is not encrypted
    
    Throws:
    
    InvokeException - if stream is null
  - PdfDocumentBase
```
public PdfDocumentBase(java.net.URL url,
                       java.lang.String password)
                throws InvokeException
```
    Creates a document from a URL. The document is loaded when it is first needed.
    
    Parameters:
    
    url - the PDF document location
    
    password - the password of an encrypted document, or null if it is not encrypted
    
    Throws:
    
    InvokeException - if url is null
- Method Detail
  - write
```
public void write(java.io.OutputStream out)
           throws java.io.IOException,
                  InvokeException
```
    Writes the document with all changes, unencrypted, and closes the stream. A pending append, overlay or underlay is applied. The Producer property is set to PD4ML.
    
    Parameters:
    
    out - the stream to write the PDF to; it is closed afterwards
    
    Throws:
    
    java.io.IOException - if the document cannot be read, processed or written
    
    InvokeException - if this document has been appended to, or laid over or under, another document; it is then part of that document and cannot be written on its own
  - write
```
public void write(java.io.OutputStream out,
                  java.lang.String password,
                  int permissions)
           throws java.io.IOException,
                  InvokeException,
                  InvalidPasswordException
```
    Writes the document with all changes and closes the stream, optionally encrypted. A pending append, overlay or underlay is applied. The Producer property is set to PD4ML.
    Encryption is skipped for documents that declare PDF/A conformance, as PDF/A does not allow it. The password is used both as the user and the owner password.
    
    Parameters:
    
    out - the stream to write the PDF to; it is closed afterwards
    
    password - the password needed to open the written document, or null for none
    
    permissions - the allowed operations, a combination of the Constants.Allow* flags, for example Constants.AllowPrint | Constants.AllowCopy; a value of 0 or less, together with a null password, writes the document unencrypted
    
    Throws:
    
    java.io.IOException - if the document cannot be read, processed or written
    
    InvalidPasswordException - if the document is encrypted and the password given to the constructor is missing or wrong
    
    InvokeException - if this document has been appended to, or laid over or under, another document
    
    See Also:
    
    Constants.DefaultPermissions
  - append
```
public void append(PdfDocumentBase toMerge)
            throws java.io.IOException
```
    Appends the pages of another document after the pages of this one. The documents are combined when this document is written; bookmarks of both are kept, and the document properties of this document are used. Afterwards toMerge is part of this document and cannot be written on its own.
    
    Parameters:
    
    toMerge - the document to append
    
    Throws:
    
    java.io.IOException - if a document cannot be read or parsed
    
    InvalidPasswordException - if a document is encrypted and its password is missing or wrong
    
    InvokeException - if another document has already been appended, laid over or laid under this one
  - overlay
```
public void overlay(PdfDocumentBase anotherDoc,
                    int opacity)
             throws java.io.IOException
```
    Draws the pages of another document over the pages of this one, for example to stamp a watermark or a "COPY" label. The first page of anotherDoc goes over the first page of this document, the second over the second, and so on; if anotherDoc has fewer pages, its pages are repeated from the beginning. The documents are combined when this document is written; afterwards anotherDoc is part of this document and cannot be written on its own.
    
    Parameters:
    
    anotherDoc - the document whose pages to draw over this one
    
    opacity - the opacity of the overlay, from 0 (invisible) to 255 (opaque); a negative value also means opaque
    
    Throws:
    
    java.io.IOException - if a document cannot be read or parsed
    
    InvalidPasswordException - if a document is encrypted and its password is missing or wrong
    
    InvokeException - if another document has already been appended, laid over or laid under this one
    
    See Also:
    
    overlay(PdfDocumentBase, String, String, int)
  - overlay
```
public void overlay(PdfDocumentBase anotherDoc,
                    java.lang.String srcScope,
                    java.lang.String destScope,
                    int opacity)
             throws java.io.IOException
```
    Draws selected pages of another document over selected pages of this one. The selected source pages are applied to the selected target pages in order, and repeated from the first one if there are fewer of them; for example overlay(stamp, "1", "1+", 255) draws the first page of stamp over every page.
    
    Parameters:
    
    anotherDoc - the document whose pages to draw over this one
    
    srcScope - the pages of anotherDoc to use (see computeScope(String, int) for the syntax), or null for all
    
    destScope - the pages of this document to draw on, or null for all
    
    opacity - the opacity of the overlay, from 0 (invisible) to 255 (opaque); a negative value also means opaque
    
    Throws:
    
    java.io.IOException - if a document cannot be read or parsed
    
    InvalidPasswordException - if a document is encrypted and its password is missing or wrong
    
    InvokeException - if another document has already been appended, laid over or laid under this one
  - underlay
```
public void underlay(PdfDocumentBase anotherDoc,
                     int opacity)
              throws java.io.IOException
```
    Draws the pages of another document under the pages of this one, for example a letterhead or a page background. Pages are paired as in overlay(PdfDocumentBase, int).
    
    Parameters:
    
    anotherDoc - the document whose pages to draw under this one
    
    opacity - the opacity of the underlay, from 0 (invisible) to 255 (opaque); a negative value also means opaque
    
    Throws:
    
    java.io.IOException - if a document cannot be read or parsed
    
    InvalidPasswordException - if a document is encrypted and its password is missing or wrong
    
    InvokeException - if another document has already been appended, laid over or laid under this one
    
    See Also:
    
    underlay(PdfDocumentBase, String, String, int)
  - underlay
```
public void underlay(PdfDocumentBase anotherDoc,
                     java.lang.String srcScope,
                     java.lang.String destScope,
                     int opacity)
              throws java.io.IOException
```
    Draws selected pages of another document under selected pages of this one. Pages are paired as in overlay(PdfDocumentBase, String, String, int).
    
    Parameters:
    
    anotherDoc - the document whose pages to draw under this one
    
    srcScope - the pages of anotherDoc to use (see computeScope(String, int) for the syntax), or null for all
    
    destScope - the pages of this document to draw under, or null for all
    
    opacity - the opacity of the underlay, from 0 (invisible) to 255 (opaque); a negative value also means opaque
    
    Throws:
    
    java.io.IOException - if a document cannot be read or parsed
    
    InvalidPasswordException - if a document is encrypted and its password is missing or wrong
    
    InvokeException - if another document has already been appended, laid over or laid under this one
  - getNumberOfPages
```
public int getNumberOfPages()
                     throws java.io.IOException,
                            InvalidPasswordException
```
    Returns the number of pages, including the pages of an appended document.
    
    Returns:
    
    the number of pages
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - getPermissions
```
public int getPermissions()
                   throws java.io.IOException,
                          InvalidPasswordException
```
    Returns the access permissions of the document, as a combination of the Constants.Allow* flags.
    
    Returns:
    
    the permission flags; all bits set (0xFFFFFFFF) if the document is not encrypted
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - getTitle
```
public java.lang.String getTitle()
                          throws java.io.IOException,
                                 InvalidPasswordException
```
    Returns the title from the document properties.
    
    Returns:
    
    the title, or null if not set
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - setTitle
```
public void setTitle(java.lang.String title)
              throws java.io.IOException,
                     InvalidPasswordException
```
    Sets the title in the document properties. Also makes PDF viewers show the title instead of the file name in the window title.
    
    Parameters:
    
    title - the new title
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - getAuthor
```
public java.lang.String getAuthor()
                           throws java.io.IOException,
                                  InvalidPasswordException
```
    Returns the author from the document properties.
    
    Returns:
    
    the author, or null if not set
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - setAuthor
```
public void setAuthor(java.lang.String author)
               throws java.io.IOException
```
    Sets the author in the document properties.
    
    Parameters:
    
    author - the new author
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed, or the password is wrong
  - getPdfFormatVersion
```
public java.lang.String getPdfFormatVersion()
                                     throws java.io.IOException,
                                            InvalidPasswordException
```
    Returns the PDF version of the document, from its file header.
    
    Returns:
    
    the version, for example "1.7"; the decimal separator follows the default locale
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - getMetadata
```
public java.lang.String getMetadata()
                             throws java.io.IOException,
                                    InvalidPasswordException
```
    Returns the XMP metadata of the document, for example to check its PDF/A conformance declaration.
    
    Returns:
    
    the XMP metadata as an XML string, or null if the document has none
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - getCreationDate
```
public java.lang.String getCreationDate()
                                 throws java.io.IOException,
                                        InvalidPasswordException
```
    Returns the creation date from the document properties.
    
    Returns:
    
    the date as a PDF date string, for example "D:20240131120000+01'00'", or null if not set
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - dumpOutlines
```
public java.lang.String dumpOutlines()
                              throws java.io.IOException,
                                     InvalidPasswordException
```
    Returns a text dump of the bookmark (outline) tree, for diagnostics.
    
    Returns:
    
    the dump, or an empty string if the document has no catalog
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - getKeywords
```
public java.lang.String getKeywords()
                             throws java.io.IOException,
                                    InvalidPasswordException
```
    Returns the keywords from the document properties.
    
    Returns:
    
    the keywords, or null if not set
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - setKeywords
```
public void setKeywords(java.lang.String keywords)
                 throws java.io.IOException,
                        InvalidPasswordException
```
    Sets the keywords in the document properties.
    
    Parameters:
    
    keywords - the new keywords, for example a comma-separated list
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - getCreator
```
public java.lang.String getCreator()
                            throws java.io.IOException,
                                   InvalidPasswordException
```
    Returns the creator from the document properties: the application the original document was created with.
    
    Returns:
    
    the creator, or null if not set
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - setCreator
```
public void setCreator(java.lang.String creator)
                throws java.io.IOException,
                       InvalidPasswordException
```
    Sets the creator in the document properties.
    
    Parameters:
    
    creator - the name of the application the document was created with
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - getProducer
```
public java.lang.String getProducer()
                             throws java.io.IOException,
                                    InvalidPasswordException
```
    Returns the producer from the document properties: the software that wrote the PDF. Note that write(OutputStream) replaces it with PD4ML (or the value of the pd4ml.producer.application system property).
    
    Returns:
    
    the producer, or null if not set
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - getSubject
```
public java.lang.String getSubject()
                            throws java.io.IOException,
                                   InvalidPasswordException
```
    Returns the subject from the document properties.
    
    Returns:
    
    the subject, or null if not set
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - setSubject
```
public void setSubject(java.lang.String subject)
                throws java.io.IOException,
                       InvalidPasswordException
```
    Sets the subject in the document properties.
    
    Parameters:
    
    subject - the new subject
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - setModDate
```
public void setModDate()
                throws java.io.IOException,
                       InvalidPasswordException
```
    Sets the modification date in the document properties to the current time. Not done automatically by write(OutputStream).
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - getModDate
```
public java.lang.String getModDate()
                            throws java.io.IOException,
                                   InvalidPasswordException
```
    Returns the modification date from the document properties.
    
    Returns:
    
    the date as a PDF date string, or null if not set
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - getPageSize
```
public PageSize getPageSize(int pageIndex)
                     throws InvalidPasswordException,
                            java.io.IOException
```
    Returns the size of a page: the size of its crop box (the area viewers show), or of its media box if it has no crop box.
    
    Parameters:
    
    pageIndex - the page number, starting from 1
    
    Returns:
    
    the page size in points, or null if the page does not exist or has no valid size
    
    Throws:
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
    
    java.io.IOException - if the document cannot be read
  - getPageBox
```
public float[] getPageBox(int pageIndex,
                          java.lang.String boxName)
                   throws InvalidPasswordException,
                          java.io.IOException
```
    Returns a page boundary box. A box not set on the page itself is inherited from its parent nodes in the page tree.
    
    Parameters:
    
    pageIndex - the page number, starting from 1
    
    boxName - the box: "MediaBox" (the full page, the size of the medium it is printed on), "CropBox" (the area viewers show), or one of the print production boxes "BleedBox", "TrimBox" and "ArtBox"
    
    Returns:
    
    the box as [x1, y1, x2, y2] in points, with the origin at the bottom left of the page, or null if the page does not exist or does not define the box
    
    Throws:
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
    
    java.io.IOException - if the document cannot be read
  - read
```
public void read()
          throws java.io.IOException,
                 InvokeException,
                 InvalidPasswordException
```
    Loads and parses the document. Calling it is optional: every method that needs the document content loads it on first use. Call it explicitly to check early that the document is valid and the password is correct.
    
    Throws:
    
    java.io.IOException - if the document cannot be loaded or is not a valid PDF
    
    InvokeException - if no document data is available
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - getPageContent
```
public java.lang.String getPageContent(int pageIndex)
                                throws InvalidPasswordException,
                                       java.io.IOException
```
    Returns the decoded content stream of a page: the PDF drawing operators, for diagnostics or simple text checks. A page with several content streams returns them joined, one per line.
    Note that, unlike the other page methods, this one takes a 0-based page index.
    
    Parameters:
    
    pageIndex - the page index, starting from 0
    
    Returns:
    
    the content stream, decoded as ISO-8859-1, or null if the page does not exist or has no content
    
    Throws:
    
    java.io.IOException - if the document cannot be read or a stream cannot be decoded
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
  - deletePage
```
public int deletePage(int pageNumber)
               throws InvalidPasswordException,
                      java.io.IOException
```
    Deletes a page. Bookmarks that point to the page are removed, and resources only that page used are dropped when the document is written. Has no effect if the document has only one page or the page does not exist.
    To delete several pages, delete them from the last to the first, as the following pages are renumbered after each deletion.
    
    Parameters:
    
    pageNumber - the number of the page to delete, starting from 1
    
    Returns:
    
    the number of pages left
    
    Throws:
    
    java.io.IOException - if the document cannot be read or parsed
    
    InvalidPasswordException - if the document is encrypted and the password is missing or wrong
    
    InvokeException - if another document has been appended to this one; delete the pages before appending, or write and reload the combined document
  - computeScope
```
public static boolean[] computeScope(java.lang.String scope,
                                     int pageNum)
```
    Evaluates a page scope: tells for each page of a document whether the scope selects it.
    A scope is a comma-separated list of items: a page number ("3"), a range ("3-5"), a page and all pages after it ("2+"), and the filters "odd", "even", "last" (only the last page) and "skiplast" (all but the last page). Pages are numbered from 1. For example, "5+,even" selects the even pages from page 5 on, and "1+,skiplast" all pages except the last.
    
    Parameters:
    
    scope - the scope, or null or an empty string for all pages
    
    pageNum - the number of pages of the document
    
    Returns:
    
    one flag per page, true if the page is selected; index 0 is page 1

Class PdfDocumentBase

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

PdfDocumentBase

PdfDocumentBase

PdfDocumentBase

Method Detail

write

write

append

overlay

overlay

underlay

underlay

getNumberOfPages

getPermissions

getTitle

setTitle

getAuthor

setAuthor

getPdfFormatVersion

getMetadata

getCreationDate

dumpOutlines

getKeywords

setKeywords

getCreator

setCreator

getProducer

getSubject

setSubject

setModDate

getModDate

getPageSize

getPageBox

read

getPageContent

deletePage

computeScope