jPod PDF library

de.intarsys.pdf.cos
Class COSDocument

java.lang.Object
  extended by de.intarsys.pdf.cos.COSDocument
All Implemented Interfaces:
ICOSContainer, ICOSExceptionHandler, de.intarsys.tools.attribute.IAttributeSupport, de.intarsys.tools.locator.ILocatorSupport

public class COSDocument
extends Object
implements ICOSContainer, ICOSExceptionHandler, de.intarsys.tools.attribute.IAttributeSupport, de.intarsys.tools.locator.ILocatorSupport

This is a COS level representation of a pdf document. A COS document is made up of a collection of COSObject instances. These objects are arranged according to the PDF file format specification.

See PDF File Format Specification [PDF].


Field Summary
static Object SLOT_ALL
          A dummy object indicating a unconstrained change
static Object SLOT_DIRTY
           
static Object SLOT_LOCATOR
           
static Object SLOT_TRAILER
           
 
Method Summary
 void add(COSDocumentElement element)
          This should not be used by the application programmer.
 void addDocumentListener(ICOSDocumentListener listener)
          Add an ICOSDocumentListener to be informed about the documents events.
 void addMonitor(ICOSMonitor listener)
           
 ICOSContainer associate(ICOSContainer newContainer, COSObject object)
          This method should not be used by the application programmer.
 void close()
          Close the document.
 COSDocumentElement containable(COSObject object)
          This method should not be used by the application programmer.
 COSDocument copyDeep()
          Make a deep copy of the receiver.
static COSDocument createFromLocator(de.intarsys.tools.locator.ILocator locator)
           
static COSDocument createFromLocator(de.intarsys.tools.locator.ILocator locator, Map options)
          Create a COSDocument based on a Locator.
static COSDocument createFromST(STDocument doc)
          Create a COSDocument based on a STDocument.
static COSDocument createNew()
          Create a new empty PDF COSDocument.
static COSDocument createNew(STDocType docType)
          Create a new empty COSDocument.
 ICOSContainer disassociate(ICOSContainer oldContainer, COSObject object)
          This method should not be used by the application programmer.
 IAccessPermissions getAccessPermissions()
          The currently active access permissions if supported by the ISecurityHandler.
 Object getAttribute(Object key)
           
 COSCatalog getCatalog()
          Get the root object (the catalog) for the document.
 COSDocument getDoc()
          This method should not be used by the application programmer.
 ICOSExceptionHandler getExceptionHandler()
           
 int getIncrementalCount()
          The number of versions created for this document so far.
 COSInfoDict getInfoDict()
          Get the info dictionary containing metadata.
 de.intarsys.tools.locator.ILocator getLocator()
          The ILocator for this document.
 String getName()
          The document name.
 COSTrailer getTrailer()
          The trailer for the document.
 EnumWriteMode getWriteModeHint()
          The write mode to be used when the document is written the next time.
 void handleException(COSRuntimeException ex)
          Handle ex, optionally rethrow.
 void harden(COSObject object)
          "Harden" the reference to object, keeping it from being garbage collected even if (temporarily) not accessed.
 boolean isDirty()
          Answer true if the document has changes to be committed.
 boolean isEncrypted()
          Answer true if the document is encrypted.
 boolean isNew()
          Answer true if the document is new, i.e. not yet written.
 boolean isReadOnly()
          Answer true if the document is read only.
 Iterator<COSObject> objects()
          An iterator on all COSObject instances of this that are managed as indirect objects in the storage layer.
 int referenceCount()
          This method should not be used by the application programmer.
 COSIndirectObject referenceIndirect(COSObject object)
          This method should not be used by the application programmer.
 void register(COSDocumentElement object)
          This method should not be used by the application programmer.
 Object removeAttribute(Object key)
           
 void removeDocumentListener(ICOSDocumentListener listener)
          Remove an ICOSDocumentListener.
 void removeMonitor(ICOSMonitor monitor)
           
 void restore(de.intarsys.tools.locator.ILocator locator)
          Restore this from a locator.
 ICOSContainer restoreStateContainer(ICOSContainer container)
          This method should not be used by the application programmer.
 void save()
          Save the document to its current ILocator.
 void save(de.intarsys.tools.locator.ILocator locator)
          Save the document nto a new ILocator.
 void save(de.intarsys.tools.locator.ILocator locator, Map options)
          Save the document to an optional new ILocator using the options to control specific serializing behavior such as "incremental writing".
 ICOSContainer saveStateContainer()
          This method should not be used by the application programmer.
 Object setAttribute(Object key, Object value)
           
 void setCatalog(COSCatalog catalog)
          Assign a new catalog (/Root entry in the trailer).
 void setExceptionHandler(ICOSExceptionHandler exceptionHandler)
           
 void setInfoDict(COSInfoDict infoDict)
          Set the info dictionary containing metadata.
 void setName(String name)
          Assign a new name to the document.
 void setWriteModeHint(EnumWriteMode writeMode)
          The write mode to be used when the document is written the next time.
 void soften(COSObject object)
          "Soften" the reference to object, making it accessible for swapping out / garbage collection if the counter for hardening is zero.
 STDocument stGetDoc()
          The storage layer document.
 void triggerChangedAll()
          This method should not be used by the application programmer.
 void willChange(COSObject change)
          This method should not be used by the application programmer.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SLOT_ALL

public static final Object SLOT_ALL
A dummy object indicating a unconstrained change


SLOT_DIRTY

public static final Object SLOT_DIRTY

SLOT_LOCATOR

public static final Object SLOT_LOCATOR

SLOT_TRAILER

public static final Object SLOT_TRAILER
Method Detail

createFromLocator

public static COSDocument createFromLocator(de.intarsys.tools.locator.ILocator locator)
                                     throws IOException,
                                            COSLoadException
Throws:
IOException
COSLoadException

createFromLocator

public static COSDocument createFromLocator(de.intarsys.tools.locator.ILocator locator,
                                            Map options)
                                     throws IOException,
                                            COSLoadException
Create a COSDocument based on a Locator.

Parameters:
locator - The ILocater referencing the documents data stream.
Returns:
A new COSDocument.
Throws:
COSLoadException
IOException

createFromST

public static COSDocument createFromST(STDocument doc)
                                throws COSLoadException
Create a COSDocument based on a STDocument.

Parameters:
doc - The storage layer document.
Returns:
A new COSDocument.
Throws:
COSLoadException

createNew

public static COSDocument createNew()
Create a new empty PDF COSDocument.

Returns:
A new empty PDF COSDocument

createNew

public static COSDocument createNew(STDocType docType)
Create a new empty COSDocument.

Returns:
A new empty COSDocument

add

public void add(COSDocumentElement element)
This should not be used by the application programmer. public for package visibility reasons.

Parameters:
element -

addDocumentListener

public void addDocumentListener(ICOSDocumentListener listener)
Add an ICOSDocumentListener to be informed about the documents events.

Parameters:
listener - THe new listener

addMonitor

public void addMonitor(ICOSMonitor listener)

associate

public ICOSContainer associate(ICOSContainer newContainer,
                               COSObject object)
This method should not be used by the application programmer. This is called in the COSObject lifecycle to ensure internal consistency.

Specified by:
associate in interface ICOSContainer
Returns:
The resulting ICOSContainer for object

close

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

Throws:
IOException

containable

public COSDocumentElement containable(COSObject object)
This method should not be used by the application programmer. This is called in the COSObject lifecycle to ensure internal consistency.

Specified by:
containable in interface ICOSContainer
Parameters:
object - THe object whose containable is requested.
Returns:
The stand-in to be used when object should be contained in a container.

copyDeep

public COSDocument copyDeep()
Make a deep copy of the receiver. The newly created document has the same content as this, but does not share any object. The structure of the ST level is built from scratch.

Returns:
A deep copy of this.

disassociate

public ICOSContainer disassociate(ICOSContainer oldContainer,
                                  COSObject object)
This method should not be used by the application programmer. This is called in the COSObject lifecycle to ensure internal consistency.

Specified by:
disassociate in interface ICOSContainer
Returns:
The resulting ICOSContainer for object

getAccessPermissions

public IAccessPermissions getAccessPermissions()
The currently active access permissions if supported by the ISecurityHandler.

Returns:
The currently active access permissions if supported by the ISecurityHandler.

getAttribute

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

getCatalog

public COSCatalog getCatalog()
Get the root object (the catalog) for the document.

Returns:
The root object (the catalog) for the document.

getDoc

public COSDocument getDoc()
This method should not be used by the application programmer. This is called in the COSObject lifecycle to ensure internal consistency.

Specified by:
getDoc in interface ICOSContainer
Returns:
The COSDocument instance where the ICOSContainer is contained.

getExceptionHandler

public ICOSExceptionHandler getExceptionHandler()

getIncrementalCount

public int getIncrementalCount()
The number of versions created for this document so far.

Returns:
The number of versions created for this document so far.

getInfoDict

public COSInfoDict getInfoDict()
Get the info dictionary containing metadata.

Returns:
The info dictionary containing metadata.

getLocator

public de.intarsys.tools.locator.ILocator getLocator()
The ILocator for this document. The ILocator designates the physical storage for the PDF data.

Specified by:
getLocator in interface de.intarsys.tools.locator.ILocatorSupport
Returns:
The ILocator for this document.

getName

public String getName()
The document name. This is derived from the associated ILocator.

Returns:
The document name.

getTrailer

public COSTrailer getTrailer()
The trailer for the document.

Returns:
The trailer for the 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.

handleException

public void handleException(COSRuntimeException ex)
                     throws COSRuntimeException
Description copied from interface: ICOSExceptionHandler
Handle ex, optionally rethrow.

Specified by:
handleException in interface ICOSExceptionHandler
Parameters:
ex - The exceptioin to be handeled.
Throws:
COSRuntimeException

harden

public void harden(COSObject object)
Description copied from interface: ICOSContainer
"Harden" the reference to object, keeping it from being garbage collected even if (temporarily) not accessed. Otherwise a container may decide to "swap" its descendants out of memory.

Hardening uses a counter to decide if a strong reference can be finally released.

Specified by:
harden in interface ICOSContainer
Parameters:
object - The object that should be kept in memory.

isDirty

public boolean isDirty()
Answer true if the document has changes to be committed.

Returns:
Answer true if the document has changes to be committed.

isEncrypted

public boolean isEncrypted()
Answer true if the document is encrypted.

Returns:
Answer true if the document is encrypted.

isNew

public boolean isNew()
Answer true if the document is new, i.e. not yet written.

Returns:
Answer true if the document is new, i.e. not yet written.

isReadOnly

public boolean isReadOnly()
Answer true if the document is read only. To save the document and its changes you have to define another ILocator when saving.

Returns:
Answer true if the document is read only.

objects

public Iterator<COSObject> objects()
An iterator on all COSObject instances of this that are managed as indirect objects in the storage layer.

ATTENTION: This iterator may (and on incremental documents most often will) return objects that are no longer used (referenced) in the document.

Returns:
An iterator on all COSObject instances of this document that are managed as indirect objects in the storage layer.

referenceCount

public int referenceCount()
This method should not be used by the application programmer. This is called in the COSObject lifecycle to ensure internal consistency.

Specified by:
referenceCount in interface ICOSContainer
Returns:
The number of references to the contained object.

referenceIndirect

public COSIndirectObject referenceIndirect(COSObject object)
This method should not be used by the application programmer. This is called in the COSObject lifecycle to ensure internal consistency.

Specified by:
referenceIndirect in interface ICOSContainer
Parameters:
object - The object to be indirect

register

public void register(COSDocumentElement object)
This method should not be used by the application programmer. This is called in the COSObject lifecycle to ensure internal consistency.

Specified by:
register in interface ICOSContainer
Parameters:
object - The new object to be registered in the hierarchy.

removeAttribute

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

removeDocumentListener

public void removeDocumentListener(ICOSDocumentListener listener)
Remove an ICOSDocumentListener.

Parameters:
listener - The listener to be removed

removeMonitor

public void removeMonitor(ICOSMonitor monitor)

restore

public void restore(de.intarsys.tools.locator.ILocator locator)
             throws IOException,
                    COSLoadException
Restore this from a locator. The ILocator must reference a data stream that was previously used to parse the document.

Parameters:
locator - The ILocator defining the new physical content.
Throws:
IOException
COSLoadException

restoreStateContainer

public ICOSContainer restoreStateContainer(ICOSContainer container)
This method should not be used by the application programmer. This is called in the COSObject lifecycle to ensure internal consistency.

Specified by:
restoreStateContainer in interface ICOSContainer
Returns:
The "before" state of the receiver.

save

public void save()
          throws IOException
Save the document to its current ILocator.

Throws:
IOException

save

public void save(de.intarsys.tools.locator.ILocator locator)
          throws IOException
Save the document nto a new ILocator.

Parameters:
locator - The ILocator defining the new data location.
Throws:
IOException

save

public void save(de.intarsys.tools.locator.ILocator locator,
                 Map options)
          throws IOException
Save the document to an optional new ILocator using the options to control specific serializing behavior such as "incremental writing".

Parameters:
locator -
options -
Throws:
IOException

saveStateContainer

public ICOSContainer saveStateContainer()
This method should not be used by the application programmer. This is called in the COSObject lifecycle to ensure internal consistency.

Specified by:
saveStateContainer in interface ICOSContainer
Returns:
The save state for the container.

setAttribute

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

setCatalog

public void setCatalog(COSCatalog catalog)
Assign a new catalog (/Root entry in the trailer). Use with care - this "swaps" the whole document.

Parameters:
catalog - The new catalog.

setExceptionHandler

public void setExceptionHandler(ICOSExceptionHandler exceptionHandler)

setInfoDict

public void setInfoDict(COSInfoDict infoDict)
Set the info dictionary containing metadata.

Parameters:
infoDict - The info dictionary containing metadata.

setName

public void setName(String name)
Assign a new name to the document.

Parameters:
name - The new name.

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.

soften

public void soften(COSObject object)
Description copied from interface: ICOSContainer
"Soften" the reference to object, making it accessible for swapping out / garbage collection if the counter for hardening is zero.

Specified by:
soften in interface ICOSContainer
Parameters:
object - The object that should be kept in memory.

stGetDoc

public STDocument stGetDoc()
The storage layer document.

Returns:
The storage layer document.

triggerChangedAll

public void triggerChangedAll()
This method should not be used by the application programmer. This is called in the COSObject lifecycle to ensure internal consistency.


willChange

public void willChange(COSObject change)
This method should not be used by the application programmer. This is called in the COSObject lifecycle to ensure internal consistency.

Specified by:
willChange in interface ICOSContainer

jPod PDF library

Copyright © 2008 intarsys consulting GmbH. All Rights Reserved.