Foxit PDF SDK
com.foxit.sdk.pdf.objects.PDFNameTree Class Reference
Inheritance diagram for com.foxit.sdk.pdf.objects.PDFNameTree:
com.foxit.sdk.common.Base

Public Member Functions

 PDFNameTree (PDFDoc document, int type) throws com.foxit.sdk.PDFException
 Constructor, with parameters. More...
 
 PDFNameTree ()
 Constructor.
 
 PDFNameTree (PDFNameTree other)
 Constructor, with another PDF name tree object. More...
 
boolean add (String name, PDFObject pdf_object) throws com.foxit.sdk.PDFException
 Add a new key name with a PDF object as its value. More...
 
synchronized void delete ()
 Clean up related resources immediately. More...
 
int getCount () throws com.foxit.sdk.PDFException
 Get the count of elements in current name tree. More...
 
String getName (int index) throws com.foxit.sdk.PDFException
 Get a key name in the name tree, by index. More...
 
PDFObject getObj (String name) throws com.foxit.sdk.PDFException
 Get the value (as PDF object) of a specified key name. More...
 
int getType () throws com.foxit.sdk.PDFException
 Get the type of current name tree. More...
 
boolean hasName (String name) throws com.foxit.sdk.PDFException
 Check if the specified key name exists in current name tree. More...
 
boolean isEmpty ()
 Check whether current object is empty or not. More...
 
boolean removeAllObjs () throws com.foxit.sdk.PDFException
 Remove all key names from current name tree, along with theirs value (as PDF object). More...
 
boolean removeObj (String name) throws com.foxit.sdk.PDFException
 Remove a key name from current name tree, along with its value (as PDF object). More...
 
boolean rename (String old_name, String new_name) throws com.foxit.sdk.PDFException
 Rename an existing key name to a new key name. More...
 
boolean setObj (String name, PDFObject pdf_object) throws com.foxit.sdk.PDFException
 Set the value (as PDF object) of a specified key name. More...
 
- Public Member Functions inherited from com.foxit.sdk.common.Base
synchronized void delete ()
 Clean up related resources immediately. More...
 

Static Public Attributes

static final int e_Dests = 1
 "Dests" name tree.
 
static final int e_EmbeddedFiles = 3
 "EmbeddedFiles" name tree.
 
static final int e_JavaScript = 2
 "JavaScript" name tree.
 
static final int e_Pages = 4
 "Pages" name tree.
 
static final int e_Templates = 5
 "Templates" name tree.
 

Detailed Description

Name tree is a kind of common data structure in PDF. Name tree serves a similar purpose to PDF dictionary

  • associating keys and values - but by different means: in the name tree, a key name is treated as an alias of its value object. That means, the value object can be referred to by the key name instead of by reference object.
    Name tree has following characteristics:

    • key names in a name tree are ordered and each key name in the same name tree is unique;

    • values associated with the key names may be objects of any type, depending on the purpose of the name tree;

    • name tree can represent an arbitrarily large collection of key-value pairs, which can be looked up efficiently without requiring the entire data structure to be read from the PDF file.

    Class PDFNameTree is used to be associated with an existing name tree with specified type or create one. It offers functions to get key-value pairs in the name tree, and set/add/remove any key-value pair. Currently, class PDFNameTree can be associated with following name trees defined in PDF document:

    For convenient use about embedded files (known as attachments as well) in a PDF document, please refer to class com.foxit.sdk.pdf.Attachments .

See also
com.foxit.sdk.pdf.Attachments

Constructor & Destructor Documentation

◆ PDFNameTree() [1/2]

com.foxit.sdk.pdf.objects.PDFNameTree.PDFNameTree ( PDFDoc  document,
int  type 
) throws com.foxit.sdk.PDFException

Constructor, with parameters.

If there exists name tree with specified type in the PDF document, this function is just to construct a PDF name tree object to be associated with the name tree. If there is no such name tree in PDF document, the constructed PDF name tree object can be used to create such name tree in PDF document and add items to the name tree.

Parameters
[in]documentA valid PDF document object.
[in]typeThe type of the name tree. Please refer to values starting from com.foxit.sdk.pdf.objects.PDFNameTree.e_Dests and this should be one of these values.

◆ PDFNameTree() [2/2]

com.foxit.sdk.pdf.objects.PDFNameTree.PDFNameTree ( PDFNameTree  other)

Constructor, with another PDF name tree object.

Parameters
[in]otherAnother PDF name tree object.

Member Function Documentation

◆ add()

boolean com.foxit.sdk.pdf.objects.PDFNameTree.add ( String  name,
PDFObject  pdf_object 
) throws com.foxit.sdk.PDFException

Add a new key name with a PDF object as its value.

All PDF objects in the name tree are ordered by their names. When a new PDF object is added, Foxit PDF SDK will find a suitable place in the name tree to add it. After adding successfully, the indexes of some old keys may be changed.

Parameters
[in]nameString for a new key name. This should not be an empty string. This new name should not have existed in current name tree.
[in]pdf_objectA PDF object, to be set with the new name. The type of this PDF object should match current name tree; otherwise, the input PDF object is invalid. Please refer to comment of class PDFNameTree for more details.
User should not release this PDF object after this function succeeds.
Returns
true means success, while false means failure.

◆ delete()

synchronized void com.foxit.sdk.pdf.objects.PDFNameTree.delete ( )

Clean up related resources immediately.

Returns
None.
Note
Once this function is called, current object cannot be used anymore.

◆ getCount()

int com.foxit.sdk.pdf.objects.PDFNameTree.getCount ( ) throws com.foxit.sdk.PDFException

Get the count of elements in current name tree.

Returns
The element count.

◆ getName()

String com.foxit.sdk.pdf.objects.PDFNameTree.getName ( int  index) throws com.foxit.sdk.PDFException

Get a key name in the name tree, by index.

Parameters
[in]indexIndex of the key name to be retrieved. Valid range: from 0 to (count-1). count is returned by function PDFNameTree.getCount .
Returns
A string that represents the key name.

◆ getObj()

PDFObject com.foxit.sdk.pdf.objects.PDFNameTree.getObj ( String  name) throws com.foxit.sdk.PDFException

Get the value (as PDF object) of a specified key name.

Parameters
[in]nameString for a key name. It should not be an empty string.
Returns
A PDFObject object. The type of returned PDF object depends on the purpose of current name tree. Please refer to comment of class PDFNameTree for more details. If not found, this function will return null.

◆ getType()

int com.foxit.sdk.pdf.objects.PDFNameTree.getType ( ) throws com.foxit.sdk.PDFException

Get the type of current name tree.

Returns
Type of current name tree. Please refer to values starting from com.foxit.sdk.pdf.objects.PDFNameTree.e_Dests and this would be one of these values.

◆ hasName()

boolean com.foxit.sdk.pdf.objects.PDFNameTree.hasName ( String  name) throws com.foxit.sdk.PDFException

Check if the specified key name exists in current name tree.

Parameters
[in]nameA string that represents the key name to be checked. It should not be an empty string.
Returns
true means the specified name exists in current name tree, and false means the specified name does not exist in current name tree.

◆ isEmpty()

boolean com.foxit.sdk.pdf.objects.PDFNameTree.isEmpty ( )

Check whether current object is empty or not.

When the current object is empty, that means current object is useless.

Returns
true means current object is empty, while false means not.

◆ removeAllObjs()

boolean com.foxit.sdk.pdf.objects.PDFNameTree.removeAllObjs ( ) throws com.foxit.sdk.PDFException

Remove all key names from current name tree, along with theirs value (as PDF object).

Returns
true means success, while false means failure.

◆ removeObj()

boolean com.foxit.sdk.pdf.objects.PDFNameTree.removeObj ( String  name) throws com.foxit.sdk.PDFException

Remove a key name from current name tree, along with its value (as PDF object).

If the input name does not exist in current name tree, this function will return true directly.

Parameters
[in]nameString for a key name to be removed. This should not be an empty string.
Returns
true means success, while false means failure.

◆ rename()

boolean com.foxit.sdk.pdf.objects.PDFNameTree.rename ( String  old_name,
String  new_name 
) throws com.foxit.sdk.PDFException

Rename an existing key name to a new key name.

Parameters
[in]old_nameString for an old key name which is to be renamed. This should not be an empty string. This name should have existed in current name tree.
[in]new_nameString for a new key name. This should not be an empty string. This new name should not have existed in current name tree.
Returns
true means success, while false means failure.

◆ setObj()

boolean com.foxit.sdk.pdf.objects.PDFNameTree.setObj ( String  name,
PDFObject  pdf_object 
) throws com.foxit.sdk.PDFException

Set the value (as PDF object) of a specified key name.

Parameters
[in]nameString for a key name. It should not be an empty string. This name should have existed in current name tree.
[in]pdf_objectA PDF object to be set as the name's value. It should not be null. The type of this PDF object should match current name tree; otherwise, the input PDF object is invalid. Please refer to comment of class PDFNameTree for more details.
User should not release this PDF object after this function succeeds.
Returns
true means success, while false means failure.