jPod PDF library

de.intarsys.pdf.st
Class STDocument

java.lang.Object
  extended by de.intarsys.pdf.st.STDocument
All Implemented Interfaces:
de.intarsys.tools.attribute.IAttributeSupport, de.intarsys.tools.event.INotificationSupport, de.intarsys.tools.locator.ILocatorSupport

public class STDocument
extends Object
implements de.intarsys.tools.event.INotificationSupport, de.intarsys.tools.attribute.IAttributeSupport, de.intarsys.tools.locator.ILocatorSupport

The most physical abstraction of a PDF document. This object handles the random access representation of the PDF file.

An STDocument manages the cross ref access to data stream positions from COS level objects. As such the ST and the COS package are highly interdependent.


Field Summary
static String ATTR_LOCATOR
           
static String ATTR_SYSTEM_SECURITY_HANDLER
           
static String ATTR_XREF_SECTION
           
static STDocType DOCTYPE_FDF
          our current fdf version number *
static STDocType DOCTYPE_PDF
          our current pdf version number *
static String OPTION_WRITEMODEHINT
           
 
Method Summary
 void addChangedReference(COSIndirectObject object)
          Mark object as changed within this document.
 void addNotificationListener(de.intarsys.tools.event.EventType type, de.intarsys.tools.event.INotificationListener listener)
           
 void addObjectReference(COSIndirectObject newRef)
          Add another indirect object to the document.
 void close()
          Close the document.
 STDocument copyDeep()
          Return a deep copy of the document.
 COSDictionary cosGetTrailer()
          The documents trailer dictionary
static STDocument createFromLocator(de.intarsys.tools.locator.ILocator locator)
          Create a new document representing the data referenced by locator.
static STDocument createFromLocator(de.intarsys.tools.locator.ILocator locator, Map options)
          Create a new document representing the data referenced by locator using options to fine tune creation.
static STDocument createNew()
          create a new empty pdf document.
static STDocument createNew(STDocType docType)
          create a new empty document.
 STXRefSection createNewXRefSection()
           
 COSObjectKey createObjectKey()
          Create a new valid key for use in the document.
 void garbageCollect()
          Start a garbage collection for the receiver.
 Object getAccessLock()
           
 IAccessPermissions getAccessPermissions()
          If a document contains a permissions dictionary, it is "pushed" to this by the parser.
 Object getAttribute(Object key)
           
 Collection<COSIndirectObject> getChanges()
           
 COSDocument getDoc()
           
 STDocType getDocType()
           
 int getIncrementalCount()
           
 COSDictionary getLinearizedDict()
          The /Linearized dictionary of the document.
 de.intarsys.tools.locator.ILocator getLocator()
          THe locator for the document data.
 String getName()
          A name for the document.
 COSIndirectObject getObjectReference(COSObjectKey key)
          The indirect object with object number objNum and generation number genNum is looked up in the document.
 COSIndirectObject getObjectReference(int objectNumber, int generationNumber)
          The indirect object with object number objNum and generation number genNum is looked up in the document.
 COSDocumentParser getParser()
          The parser used for decoding the document data stream.
 de.intarsys.tools.randomaccess.IRandomAccess getRandomAccess()
          The random access object for the documents data.
 ISystemSecurityHandler getReadSecurityHandler()
          The documents security handler for decrypting.
 COSTrailer getTrailer()
           
 String getVersion()
          The version of the PDF spec for this document
 EnumWriteMode getWriteModeHint()
          The write mode to be used when the document is written the next time.
 ISystemSecurityHandler getWriteSecurityHandler()
          The documents security handler for encrypting.
 STXRefSection getXRefSection()
          The most recent STXrefSection of the document.
 void incrementalGarbageCollect()
           
 boolean isClosed()
           
 boolean isDirty()
          true if this has been changed.
 boolean isEncrypted()
           
 boolean isLinearized()
          true if this document is linearized.
 boolean isNew()
           
 boolean isReadOnly()
          true if this is read only.
 boolean isStreamed()
          true if this has only streamed xref sections.
 COSObject load(COSIndirectObject ref)
          Load a COSObject from the documents data.
 void loadAll()
           
 int loadedSize()
          The number of objects currently loaded.
 Iterator objects()
          An iterator on the indirect objects of the storage layer document.
 Object removeAttribute(Object key)
           
 void removeNotificationListener(de.intarsys.tools.event.EventType type, de.intarsys.tools.event.INotificationListener listener)
           
 void reparseFromLocator()
          Reparses the XREF sections without actually instantiating.
 void restore(de.intarsys.tools.locator.ILocator newLocator)
           
 void save()
           
 void save(de.intarsys.tools.locator.ILocator pLocator)
           
 void save(de.intarsys.tools.locator.ILocator pLocator, Map options)
           
 Object setAttribute(Object key, Object value)
           
 void setDirty(boolean dirty)
          Set the change flag of this.
 void setDoc(COSDocument doc)
           
 void setName(String name)
          Rename the document locally.
 void setSystemSecurityHandler(ISystemSecurityHandler handler)
          Set the ISystemSecurityHandler in order to change document's encryption.
 void setWriteModeHint(EnumWriteMode writeMode)
          The write mode to be used when the document is written the next time.
 void setXRefSection(STXRefSection pXRefSection)
          Attach the most recent x ref section to the document.
 void updateModificationDate()
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ATTR_LOCATOR

public static final String ATTR_LOCATOR
See Also:
Constant Field Values

ATTR_XREF_SECTION

public static final String ATTR_XREF_SECTION
See Also:
Constant Field Values

ATTR_SYSTEM_SECURITY_HANDLER

public static final String ATTR_SYSTEM_SECURITY_HANDLER
See Also:
Constant Field Values

DOCTYPE_FDF

public static final STDocType DOCTYPE_FDF
our current fdf version number *


DOCTYPE_PDF

public static final STDocType DOCTYPE_PDF
our current pdf version number *


OPTION_WRITEMODEHINT

public static final String OPTION_WRITEMODEHINT
See Also:
Constant Field Values
Method Detail

createFromLocator

public static STDocument createFromLocator(de.intarsys.tools.locator.ILocator locator)
                                    throws IOException,
                                           COSLoadException
Create a new document representing the data referenced by locator.

Parameters:
locator - The locator to the documents data
Returns:
A new document representing the data referenced by locator.
Throws:
IOException
COSLoadException

createFromLocator

public static STDocument createFromLocator(de.intarsys.tools.locator.ILocator locator,
                                           Map options)
                                    throws IOException,
                                           COSLoadException
Create a new document representing the data referenced by locator using options to fine tune creation.

All options given are copied to the STDocument attributes and accessible via the IAttributeSupport interface.

Parameters:
locator - The locator to the documents data
options - A collection of options
Returns:
A new document representing the data referenced by locator.
Throws:
IOException
COSLoadException

createNew

public static STDocument createNew()
create a new empty pdf document.

Returns:
A new empty pdf document

createNew

public static STDocument createNew(STDocType docType)
create a new empty document.

Returns:
A new empty document

addChangedReference

public void addChangedReference(COSIndirectObject object)
Mark object as changed within this document.

Parameters:
object - The object that is new or changed

addNotificationListener

public void addNotificationListener(de.intarsys.tools.event.EventType type,
                                    de.intarsys.tools.event.INotificationListener listener)
Specified by:
addNotificationListener in interface de.intarsys.tools.event.INotificationSupport

addObjectReference

public void addObjectReference(COSIndirectObject newRef)
Add another indirect object to the document.

Parameters:
newRef - The new indirect object.

close

public void close()
           throws IOException
Close the document. Accessing a documents content is undefined after close.

Throws:
IOException

copyDeep

public STDocument copyDeep()
Return a deep copy of the document. This will create a copy of the documents content. The new documents location (random access) is undefined. The objects will not preserve their key values.

Returns:
A deep copy of this.

cosGetTrailer

public COSDictionary cosGetTrailer()
The documents trailer dictionary

Returns:
The documents trailer dictionary

createNewXRefSection

public STXRefSection createNewXRefSection()

createObjectKey

public COSObjectKey createObjectKey()
Create a new valid key for use in the document.

Returns:
A new valid key for use in the document.

garbageCollect

public void garbageCollect()
Start a garbage collection for the receiver. In a garbage collection every indirect object currently unused (unreachable from the catalog) is removed.


getAccessLock

public Object getAccessLock()

getAccessPermissions

public IAccessPermissions getAccessPermissions()
If a document contains a permissions dictionary, it is "pushed" to this by the parser. Otherwise the document will have full permissions set.

Returns:
The document access permissions

getAttribute

public Object getAttribute(Object key)
Specified by:
getAttribute in interface de.intarsys.tools.attribute.IAttributeSupport

getChanges

public Collection<COSIndirectObject> getChanges()

getDoc

public COSDocument getDoc()

getDocType

public STDocType getDocType()

getIncrementalCount

public int getIncrementalCount()

getLinearizedDict

public COSDictionary getLinearizedDict()
The /Linearized dictionary of the document. The /Linearized dictionary is represented by the first entry in the (logically) first XRef section.

Note that this method may NOT return a dictionary even if the document contains a /Linearized dictionary as the first object. This is the case when the document was linearized and was written with an incremental change so that the linearization is obsolete.

Returns:
The valid /Linearized dictionary of the document.

getLocator

public de.intarsys.tools.locator.ILocator getLocator()
THe locator for the document data.

Specified by:
getLocator in interface de.intarsys.tools.locator.ILocatorSupport
Returns:
THe locator for the document data.

getName

public String getName()
A name for the document.

This is either a "local" name or the name of the locator reference if present.

Returns:
A name for the document

getObjectReference

public COSIndirectObject getObjectReference(COSObjectKey key)
The indirect object with object number objNum and generation number genNum is looked up in the document. If the indirect object is not yet available, it is created and registered.

Parameters:
key -
Returns:
The indirect object with object number objNum and generation number genNum

getObjectReference

public COSIndirectObject getObjectReference(int objectNumber,
                                            int generationNumber)
The indirect object with object number objNum and generation number genNum is looked up in the document. If the indirect object is not yet available, it is created and registered.

Parameters:
key -
Returns:
The indirect object with object number objNum and generation number genNum

getParser

public COSDocumentParser getParser()
The parser used for decoding the document data stream.

Returns:
The parser used for decoding the document data stream.

getRandomAccess

public de.intarsys.tools.randomaccess.IRandomAccess getRandomAccess()
The random access object for the documents data. Be aware that using the IRandomAccess after it is closed will throw an IOException.

Returns:
The random access object for the documents data.

getReadSecurityHandler

public ISystemSecurityHandler getReadSecurityHandler()
The documents security handler for decrypting.

Returns:
The documents security handler for decrypting.

getTrailer

public COSTrailer getTrailer()

getVersion

public String getVersion()
The version of the PDF spec for this document

Returns:
The version of the PDF spec for this document

getWriteModeHint

public EnumWriteMode getWriteModeHint()
The write mode to be used when the document is written the next time. If defined this overrides any hint that is used when saving the document. The write mode is reset after each "save".

Returns:
The write mode to be used when the document is written.

getWriteSecurityHandler

public ISystemSecurityHandler getWriteSecurityHandler()
The documents security handler for encrypting.

Returns:
The documents security handler for encrypting.

getXRefSection

public STXRefSection getXRefSection()
The most recent STXrefSection of the document.

Returns:
The most recent STXrefSection of the document.

incrementalGarbageCollect

public void incrementalGarbageCollect()

isClosed

public boolean isClosed()

isDirty

public boolean isDirty()
true if this has been changed.

Returns:
true if this has been changed.

isEncrypted

public boolean isEncrypted()
Returns:
if the document has an ISystemSecurityHandler

isLinearized

public boolean isLinearized()
true if this document is linearized.

When linearized reading is truly implemented, this check should be made using the document length instead for performance reasons.

Returns:
true if this document is linearized.

isNew

public boolean isNew()

isReadOnly

public boolean isReadOnly()
true if this is read only.

Returns:
true if this is read only.

isStreamed

public boolean isStreamed()
true if this has only streamed xref sections.

Returns:
true if this has only streamed xref sections.

load

public COSObject load(COSIndirectObject ref)
               throws IOException,
                      COSLoadException
Load a COSObject from the documents data.

Parameters:
ref - The object reference to be loaded.
Throws:
IOException
COSLoadException

loadAll

public void loadAll()
             throws IOException,
                    COSLoadException
Throws:
IOException
COSLoadException

loadedSize

public int loadedSize()
The number of objects currently loaded.

Returns:
The number of objects currently loaded.

objects

public Iterator objects()
An iterator on the indirect objects of the storage layer document. This includes garbage and purely technical objects like x ref streams.

Returns:
An iterator on the indirect objects of the storage layer document. This includes garbage and purely technical objects like x ref streams.

removeAttribute

public Object removeAttribute(Object key)
Specified by:
removeAttribute in interface de.intarsys.tools.attribute.IAttributeSupport

removeNotificationListener

public void removeNotificationListener(de.intarsys.tools.event.EventType type,
                                       de.intarsys.tools.event.INotificationListener listener)
Specified by:
removeNotificationListener in interface de.intarsys.tools.event.INotificationSupport

reparseFromLocator

public void reparseFromLocator()
                        throws IOException,
                               COSLoadException
Reparses the XREF sections without actually instantiating. Used for collecting errors on XREF level

Throws:
IOException
COSLoadException

restore

public void restore(de.intarsys.tools.locator.ILocator newLocator)
             throws IOException,
                    COSLoadException
Throws:
IOException
COSLoadException

save

public void save()
          throws IOException
Throws:
IOException

save

public void save(de.intarsys.tools.locator.ILocator pLocator)
          throws IOException
Throws:
IOException

save

public void save(de.intarsys.tools.locator.ILocator pLocator,
                 Map options)
          throws IOException
Throws:
IOException

setAttribute

public Object setAttribute(Object key,
                           Object value)
Specified by:
setAttribute in interface de.intarsys.tools.attribute.IAttributeSupport

setDirty

public void setDirty(boolean dirty)
Set the change flag of this.

Parameters:
dirty - true if this should be marked as changed

setDoc

public void setDoc(COSDocument doc)

setName

public void setName(String name)
Rename the document locally.

This has no effect if a locator is present.

Parameters:
name - The new local name of this

setSystemSecurityHandler

public void setSystemSecurityHandler(ISystemSecurityHandler handler)
                              throws COSSecurityException
Set the ISystemSecurityHandler in order to change document's encryption.

Parameters:
handler - the ISystemSecurityHandler to the documents data.
Throws:
COSSecurityException

setWriteModeHint

public void setWriteModeHint(EnumWriteMode writeMode)
The write mode to be used when the document is written the next time. If defined this overrides any hint that is used when saving the document. The write mode is reset after each "save".

Parameters:
writeMode - The write mode to be used when the document is written.

setXRefSection

public void setXRefSection(STXRefSection pXRefSection)
Attach the most recent x ref section to the document.

Parameters:
pXRefSection - The x ref section representing the most recent document changes.

updateModificationDate

public void updateModificationDate()

jPod PDF library

Copyright © 2008 intarsys consulting GmbH. All Rights Reserved.