de.intarsys.pdf.cos
Class COSDocument

java.lang.Object
  de.intarsys.pdf.cos.COSDocument

All Implemented Interfaces:

ICOSContainer, ICOSExceptionHandler, IAttributeSupport, ILocatorSupport

public class COSDocument
extends Object
implements ICOSContainer, ICOSExceptionHandler, IAttributeSupport, 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_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(ILocator locator) 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() If a document contains a permissions dictionary, it is "pushed" to this by the parser.
Object	getAttribute(Object key) get an attribute from the context
COSCatalog	getCatalog() Get the root object (the catalog) for the document.
COSDocument	getDoc() This method should not be used by the application programmer.
int	getIncrementalCount() The number of versions created for this document so far.
COSInfoDict	getInfoDict() Get the info dictionary containing metadata.
ILocator	getLocator() The ILocator for this document.
String	getName() The document name.
EnumWriteMode	getWriteModeHint() The write mode to be used when the document is written the next time.
void	handleException(COSRuntimeException ex) Handle ex, optionally rethrow.
boolean	isDirty() Answer true if the document has changes to be commited.
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	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) remove an attribute in the context
void	removeDocumentListener(ICOSDocumentListener listener) Remove an ICOSDocumentListener.
void	removeMonitor(ICOSMonitor monitor)
void	restore(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(ILocator locator) Save the document nto a new ILocator.
void	save(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) set the value of an attribute in the context
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.
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_DIRTY

public static final Object SLOT_DIRTY

SLOT_TRAILER

public static final Object SLOT_TRAILER

SLOT_LOCATOR

public static final Object SLOT_LOCATOR

Method Detail

createFromLocator

public static COSDocument createFromLocator(ILocator locator)
                                     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 -

addMonitor

public void addMonitor(ICOSMonitor listener)

addDocumentListener

public void addDocumentListener(ICOSDocumentListener listener)

Add an ICOSDocumentListener to be informed about the documents events.

Parameters:

listener - THe new 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()

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)

Description copied from interface: IAttributeSupport

get an attribute from the context

Specified by:

getAttribute in interface IAttributeSupport

Parameters:

key - the name of the attribute to get

Returns:

The value of the attribute to get

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.

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 ILocator getLocator()

The ILocator for this document. The ILocator designates the physical storage for the PDF data.

Specified by:

getLocator in interface 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.

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

isDirty

public boolean isDirty()

Answer true if the document has changes to be commited.

Returns:

Answer true if the document has changes to be commited.

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 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 od this 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)

Description copied from interface: IAttributeSupport

remove an attribute in the context

Specified by:

removeAttribute in interface IAttributeSupport

Parameters:

key - the name of the attribute to remove

Returns:

The previously associated object for key

removeMonitor

public void removeMonitor(ICOSMonitor monitor)

removeDocumentListener

public void removeDocumentListener(ICOSDocumentListener listener)

Remove an ICOSDocumentListener.

Parameters:

listener - The listener to be removed

restore

public void restore(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(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(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)

Description copied from interface: IAttributeSupport

set the value of an attribute in the context

Specified by:

setAttribute in interface IAttributeSupport

Parameters:

key - the name of the attribute to set

value - the new value the attribute

Returns:

The previously associated object for key

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.

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