de.intarsys.pdf.cos
Class COSDocument

java.lang.Object
  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