Package com.itextpdf.kernel.pdf
Class PdfCatalog
- java.lang.Object
-
- com.itextpdf.kernel.pdf.PdfObjectWrapper<PdfDictionary>
-
- com.itextpdf.kernel.pdf.PdfCatalog
-
public class PdfCatalog extends PdfObjectWrapper<PdfDictionary>
The root of a document’s object hierarchy.
-
-
Field Summary
Fields Modifier and Type Field Description private static org.slf4j.Logger
LOGGER
protected java.util.Map<PdfName,PdfNameTree>
nameTrees
Map of thePdfNameTree
.private boolean
ocgCopied
protected PdfOCProperties
ocProperties
The document’s optional content properties dictionary.private boolean
outlineMode
private PdfOutline
outlines
private static java.util.Set<PdfName>
PAGE_LAYOUTS
private static java.util.Set<PdfName>
PAGE_MODES
protected PdfNumTree
pageLabels
Defining the page labelling for the document.private java.util.Map<PdfObject,java.util.List<PdfOutline>>
pagesWithOutlines
private PdfPagesTree
pageTree
private static java.lang.String
ROOT_OUTLINE_TITLE
-
Constructor Summary
Constructors Modifier Constructor Description protected
PdfCatalog(PdfDictionary pdfObject)
CreatePdfCatalog
dictionary.protected
PdfCatalog(PdfDocument pdfDocument)
CreatePdfCatalog
toPdfDocument
.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addDeveloperExtension(PdfDeveloperExtension extension)
Adds an extensions dictionary containing developer prefix identification and version numbers for developer extensions that occur in this document.(package private) void
addNamedDestination(PdfString key, PdfObject value)
This methods adds new name to the Dests NameTree.(package private) void
addNameToNameTree(PdfString key, PdfObject value, PdfName treeType)
This methods adds a new name to the specified NameTree.private void
addOutlineToPage(PdfOutline outline, IPdfNameTreeAccess names)
private void
addOutlineToPage(PdfOutline outline, PdfDictionary item, IPdfNameTreeAccess names)
(package private) void
addRootOutline(PdfOutline outline)
This method sets the root outline element in the catalog.private void
checkIsoConformanceForAction(PdfAction action)
private void
checkIsoConformanceForDestination(PdfDestination destination)
(package private) void
constructOutlines(PdfDictionary outlineRoot, IPdfNameTreeAccess names)
Constructdictionary
iteratively.(package private) PdfDestination
copyDestination(PdfObject dest, java.util.Map<PdfPage,PdfPage> page2page, PdfDocument toDocument)
private PdfDestination
createDestinationFromPageNum(PdfObject dest, PdfDocument toDocument)
private static PdfDestination
createDestinationFromPageRef(PdfObject dest, java.util.Map<PdfPage,PdfPage> page2page, PdfDocument toDocument, PdfObject pageObject)
(package private) PdfDictionary
fillAndGetOcPropertiesDictionary()
void
flush()
PdfCatalog will be flushed in PdfDocument.close().PdfCollection
getCollection()
Gets collection dictionary that a conforming reader shall use to enhance the presentation of file attachments stored in the PDF document.PdfDocument
getDocument()
GetPdfDocument
with indirect reference associated with the object.PdfString
getLang()
Get natural language.PdfNameTree
getNameTree(PdfName treeType)
This method gets Names tree from the catalog.PdfOCProperties
getOCProperties(boolean createIfNotExists)
Use this method to get the Optional Content Properties Dictionary.(package private) PdfOutline
getOutlines(boolean updateOutlines)
This method returns a complete outline tree of the whole document.PdfNumTree
getPageLabelsTree(boolean createIfNotExists)
This method returns the NumberTree of Page LabelsPdfName
getPageLayout()
Get page layout of the document.PdfName
getPageMode()
Get page mode of the document.(package private) java.util.Map<PdfObject,java.util.List<PdfOutline>>
getPagesWithOutlines()
this method return map containing all pages of the document with associated outlines.(package private) PdfPagesTree
getPageTree()
PdfViewerPreferences
getViewerPreferences()
Get viewer preferences of the document.(package private) boolean
hasOutlines()
Indicates if the catalog has any outlinesprivate boolean
isEqualSameNameDestExist(java.util.Map<PdfPage,PdfPage> page2page, PdfDocument toDocument, PdfString srcDestName, PdfArray srcDestArray, PdfPage oldPage)
protected boolean
isOCPropertiesMayHaveChanged()
True indicates that getOCProperties() was called, may have been modified, and thus its dictionary needs to be reconstructed.(package private) boolean
isOutlineMode()
This flag determines if Outline tree of the document has been built via calling getOutlines method.protected boolean
isWrappedObjectMustBeIndirect()
Defines if the object behind this wrapper must be an indirect object in the resultant document.boolean
nameTreeContainsKey(PdfName treeType)
This method checks Names tree for specified tree type.PdfCatalog
put(PdfName key, PdfObject value)
Add key and value toPdfCatalog
dictionary.PdfCatalog
remove(PdfName key)
Remove key from catalog dictionary.void
removeDeveloperExtension(PdfDeveloperExtension extension)
Removes an extensions dictionary containing developer prefix identification and version numbers for developer extensions that do not occur in this document.(package private) void
removeOutlines(PdfPage page)
This method removes all outlines associated with a given pagePdfCatalog
setAdditionalAction(PdfName key, PdfAction action)
The actions that shall be taken in response to various trigger events affecting the document as a whole.PdfCatalog
setCollection(PdfCollection collection)
Sets collection dictionary that a conforming reader shall use to enhance the presentation of file attachments stored in the PDF document.void
setLang(PdfString lang)
An entry specifying the natural language, and optionally locale.(package private) void
setOcgCopied(boolean ocgCopied)
PdfCatalog
setOpenAction(PdfAction action)
A value specifying an action that shall be performed when the document is opened.PdfCatalog
setOpenAction(PdfDestination destination)
A value specifying a destination that shall be displayed when the document is opened.PdfCatalog
setPageLayout(PdfName pageLayout)
This method sets a page layout of the documentPdfCatalog
setPageMode(PdfName pageMode)
This method sets a page mode of the document.PdfCatalog
setViewerPreferences(PdfViewerPreferences preferences)
This method sets the document viewer preferences, specifying the way the document shall be displayed on the screen-
Methods inherited from class com.itextpdf.kernel.pdf.PdfObjectWrapper
ensureObjectIsAddedToDocument, ensureUnderlyingObjectHasIndirectReference, getPdfObject, isFlushed, makeIndirect, makeIndirect, markObjectAsIndirect, setForbidRelease, setModified, setPdfObject, unsetForbidRelease
-
-
-
-
Field Detail
-
LOGGER
private static final org.slf4j.Logger LOGGER
-
ROOT_OUTLINE_TITLE
private static final java.lang.String ROOT_OUTLINE_TITLE
- See Also:
- Constant Field Values
-
PAGE_MODES
private static final java.util.Set<PdfName> PAGE_MODES
-
PAGE_LAYOUTS
private static final java.util.Set<PdfName> PAGE_LAYOUTS
-
pageTree
private final PdfPagesTree pageTree
-
nameTrees
protected java.util.Map<PdfName,PdfNameTree> nameTrees
Map of thePdfNameTree
. Used for creationname tree
dictionary.
-
pageLabels
protected PdfNumTree pageLabels
Defining the page labelling for the document.
-
ocProperties
protected PdfOCProperties ocProperties
The document’s optional content properties dictionary.
-
outlines
private PdfOutline outlines
-
pagesWithOutlines
private final java.util.Map<PdfObject,java.util.List<PdfOutline>> pagesWithOutlines
-
outlineMode
private boolean outlineMode
-
ocgCopied
private boolean ocgCopied
-
-
Constructor Detail
-
PdfCatalog
protected PdfCatalog(PdfDictionary pdfObject)
CreatePdfCatalog
dictionary.- Parameters:
pdfObject
- the dictionary to be wrapped
-
PdfCatalog
protected PdfCatalog(PdfDocument pdfDocument)
CreatePdfCatalog
toPdfDocument
.- Parameters:
pdfDocument
- APdfDocument
object representing the document to which redaction applies
-
-
Method Detail
-
getOCProperties
public PdfOCProperties getOCProperties(boolean createIfNotExists)
Use this method to get the Optional Content Properties Dictionary. Note that if you call this method, then thePdfDictionary
with OCProperties will be generated fromPdfOCProperties
object right before closing thePdfDocument
, so if you want to make low-level changes in Pdf structures themselves (PdfArray
,PdfDictionary
, etc), then you should address directly those objects, e.g.:PdfCatalog pdfCatalog = pdfDoc.getCatalog(); PdfDictionary ocProps = pdfCatalog.getAsDictionary(PdfName.OCProperties); // manipulate with ocProps.
Also note that this method is implicitly called when creating a new PdfLayer instance, so you should either use hi-level logic of operating with layers, or manipulate low-level Pdf objects by yourself.- Parameters:
createIfNotExists
- true to create new /OCProperties entry in catalog if not exists, false to return null if /OCProperties entry in catalog is not present.- Returns:
- the Optional Content Properties Dictionary
-
getDocument
public PdfDocument getDocument()
GetPdfDocument
with indirect reference associated with the object.- Returns:
- the resultant dictionary
-
flush
public void flush()
PdfCatalog will be flushed in PdfDocument.close(). User mustn't flush PdfCatalog!- Overrides:
flush
in classPdfObjectWrapper<PdfDictionary>
-
isWrappedObjectMustBeIndirect
protected boolean isWrappedObjectMustBeIndirect()
Description copied from class:PdfObjectWrapper
Defines if the object behind this wrapper must be an indirect object in the resultant document.
If this method returns true it doesn't necessarily mean that object must be in the indirect state at any moment, but rather defines that when the object will be written to the document it will be transformed into indirect object if it's not indirect yet.
Return value of this method shouldn't depend on any logic, it should return always true or false.- Specified by:
isWrappedObjectMustBeIndirect
in classPdfObjectWrapper<PdfDictionary>
- Returns:
- true if in the resultant document the object behind the wrapper must be indirect, otherwise false.
-
setOpenAction
public PdfCatalog setOpenAction(PdfDestination destination)
A value specifying a destination that shall be displayed when the document is opened. See ISO 32000-1, Table 28 – Entries in the catalog dictionary.- Parameters:
destination
- instance ofPdfDestination
.- Returns:
- destination
-
setOpenAction
public PdfCatalog setOpenAction(PdfAction action)
A value specifying an action that shall be performed when the document is opened. See ISO 32000-1, Table 28 – Entries in the catalog dictionary.- Parameters:
action
- instance ofPdfAction
.- Returns:
- action
-
setAdditionalAction
public PdfCatalog setAdditionalAction(PdfName key, PdfAction action)
The actions that shall be taken in response to various trigger events affecting the document as a whole. See ISO 32000-1, Table 28 – Entries in the catalog dictionary.- Parameters:
key
- the key of which the associated value needs to be returnedaction
- instance ofPdfAction
.- Returns:
- additional action
-
getPageMode
public PdfName getPageMode()
Get page mode of the document.- Returns:
- current instance of
PdfCatalog
-
setPageMode
public PdfCatalog setPageMode(PdfName pageMode)
This method sets a page mode of the document.
Valid values are:PdfName.UseNone
,PdfName.UseOutlines
,PdfName.UseThumbs
,PdfName.FullScreen
,PdfName.UseOC
,PdfName.UseAttachments
.- Parameters:
pageMode
- page mode.- Returns:
- current instance of PdfCatalog
-
getPageLayout
public PdfName getPageLayout()
Get page layout of the document.- Returns:
- name object of page layout that shall be used when document is opened
-
setPageLayout
public PdfCatalog setPageLayout(PdfName pageLayout)
This method sets a page layout of the document- Parameters:
pageLayout
- page layout of the document- Returns:
PdfCatalog
instance with applied page layout
-
getViewerPreferences
public PdfViewerPreferences getViewerPreferences()
Get viewer preferences of the document.- Returns:
- dictionary of viewer preferences
-
setViewerPreferences
public PdfCatalog setViewerPreferences(PdfViewerPreferences preferences)
This method sets the document viewer preferences, specifying the way the document shall be displayed on the screen- Parameters:
preferences
- document'sviewer preferences
- Returns:
PdfCatalog
instance with applied viewer preferences
-
getNameTree
public PdfNameTree getNameTree(PdfName treeType)
This method gets Names tree from the catalog.- Parameters:
treeType
- type of the tree (Dests, AP, EmbeddedFiles etc).- Returns:
- returns
PdfNameTree
-
nameTreeContainsKey
public boolean nameTreeContainsKey(PdfName treeType)
This method checks Names tree for specified tree type.- Parameters:
treeType
- type of tree which existence should be checked- Returns:
- true if such tree exists, false otherwise
-
getPageLabelsTree
public PdfNumTree getPageLabelsTree(boolean createIfNotExists)
This method returns the NumberTree of Page Labels- Parameters:
createIfNotExists
- defines whether the NumberTree of Page Labels should be created if it didn't exist before- Returns:
- returns
PdfNumTree
-
getLang
public PdfString getLang()
Get natural language.- Returns:
- natural language
-
setLang
public void setLang(PdfString lang)
An entry specifying the natural language, and optionally locale. Use this to specify the Language attribute on a Tagged Pdf element. For the content usage dictionary, use PdfName.Language- Parameters:
lang
-language
to be set
-
addDeveloperExtension
public void addDeveloperExtension(PdfDeveloperExtension extension)
Adds an extensions dictionary containing developer prefix identification and version numbers for developer extensions that occur in this document. See ISO 32000-1, Table 28 – Entries in the catalog dictionary.- Parameters:
extension
- enables developers to identify their own extension relative to a base version of PDF
-
removeDeveloperExtension
public void removeDeveloperExtension(PdfDeveloperExtension extension)
Removes an extensions dictionary containing developer prefix identification and version numbers for developer extensions that do not occur in this document. See ISO 32000-1, Table 28 – Entries in the catalog dictionary.- Parameters:
extension
- developer extension to be removed from the document
-
getCollection
public PdfCollection getCollection()
Gets collection dictionary that a conforming reader shall use to enhance the presentation of file attachments stored in the PDF document.- Returns:
PdfCollection
wrapper of collection dictionary.
-
setCollection
public PdfCatalog setCollection(PdfCollection collection)
Sets collection dictionary that a conforming reader shall use to enhance the presentation of file attachments stored in the PDF document.- Parameters:
collection
-dictionary
- Returns:
PdfCatalog
instance with applied collection dictionary
-
put
public PdfCatalog put(PdfName key, PdfObject value)
Add key and value toPdfCatalog
dictionary.- Parameters:
key
- the dictionary key corresponding with the PDF objectvalue
- the value of key- Returns:
- the key and value
-
remove
public PdfCatalog remove(PdfName key)
Remove key from catalog dictionary.- Parameters:
key
- the dictionary key corresponding with the PDF object- Returns:
- the key
-
isOCPropertiesMayHaveChanged
protected boolean isOCPropertiesMayHaveChanged()
True indicates that getOCProperties() was called, may have been modified, and thus its dictionary needs to be reconstructed.- Returns:
- boolean indicating if the dictionary needs to be reconstructed
-
setOcgCopied
void setOcgCopied(boolean ocgCopied)
-
getPageTree
PdfPagesTree getPageTree()
-
getPagesWithOutlines
java.util.Map<PdfObject,java.util.List<PdfOutline>> getPagesWithOutlines()
this method return map containing all pages of the document with associated outlines.- Returns:
- map containing all pages of the document with associated outlines
-
addNamedDestination
void addNamedDestination(PdfString key, PdfObject value)
This methods adds new name to the Dests NameTree. It throws an exception, if the name already exists.- Parameters:
key
- Name of the destination.value
- An object destination refers to. Must be an array or a dictionary with key /D and array. See ISO 32000-1 12.3.2.3 for more info.
-
addNameToNameTree
void addNameToNameTree(PdfString key, PdfObject value, PdfName treeType)
This methods adds a new name to the specified NameTree. It throws an exception, if the name already exists.- Parameters:
key
- key in the name treevalue
- value in the name treetreeType
- type of the tree (Dests, AP, EmbeddedFiles etc).
-
getOutlines
PdfOutline getOutlines(boolean updateOutlines)
This method returns a complete outline tree of the whole document.- Parameters:
updateOutlines
- if the flag is true, the method read the whole document and creates outline tree. If false the method gets cached outline tree (if it was cached via calling getOutlines method before).- Returns:
- fully initialized
PdfOutline
object.
-
hasOutlines
boolean hasOutlines()
Indicates if the catalog has any outlines- Returns:
true
, if there are outlines andfalse
otherwise.
-
isOutlineMode
boolean isOutlineMode()
This flag determines if Outline tree of the document has been built via calling getOutlines method. If this flag is false all outline operations will be ignored- Returns:
- state of outline mode.
-
removeOutlines
void removeOutlines(PdfPage page)
This method removes all outlines associated with a given page- Parameters:
page
- the page to remove outlines
-
addRootOutline
void addRootOutline(PdfOutline outline)
This method sets the root outline element in the catalog.- Parameters:
outline
- the outline dictionary that shall be the root of the document’s outline hierarchy
-
constructOutlines
void constructOutlines(PdfDictionary outlineRoot, IPdfNameTreeAccess names)
Constructdictionary
iteratively. Invalid pdf documents will be processed depending onPdfReader.StrictnessLevel
, if it set to lenient, we will ignore and process invalid outline structure, otherwisePdfException
will be thrown.- Parameters:
outlineRoot
-dictionary
root.names
- map containing the PdfObjects stored in the tree.
-
copyDestination
PdfDestination copyDestination(PdfObject dest, java.util.Map<PdfPage,PdfPage> page2page, PdfDocument toDocument)
-
fillAndGetOcPropertiesDictionary
PdfDictionary fillAndGetOcPropertiesDictionary()
-
checkIsoConformanceForDestination
private void checkIsoConformanceForDestination(PdfDestination destination)
-
checkIsoConformanceForAction
private void checkIsoConformanceForAction(PdfAction action)
-
createDestinationFromPageNum
private PdfDestination createDestinationFromPageNum(PdfObject dest, PdfDocument toDocument)
-
createDestinationFromPageRef
private static PdfDestination createDestinationFromPageRef(PdfObject dest, java.util.Map<PdfPage,PdfPage> page2page, PdfDocument toDocument, PdfObject pageObject)
-
isEqualSameNameDestExist
private boolean isEqualSameNameDestExist(java.util.Map<PdfPage,PdfPage> page2page, PdfDocument toDocument, PdfString srcDestName, PdfArray srcDestArray, PdfPage oldPage)
-
addOutlineToPage
private void addOutlineToPage(PdfOutline outline, IPdfNameTreeAccess names)
-
addOutlineToPage
private void addOutlineToPage(PdfOutline outline, PdfDictionary item, IPdfNameTreeAccess names)
-
-