de.intarsys.pdf.cos
Class COSIndirectObject

java.lang.Object
  de.intarsys.pdf.cos.COSDocumentElement
      de.intarsys.pdf.cos.COSIndirectObject

All Implemented Interfaces:

ICOSContainer, ICOSExceptionHandler

public class COSIndirectObject
extends COSDocumentElement
implements ICOSContainer

An object representing an indirect object within a COSDocument.

The indirect object provides transparent lazy access to the serialized COSObject. Dereferencing this will deserialize the COSObject if not available. On the other hand, this implementation must support the handling of very large documents, so transparent garbage collection must be supported. This is implemented using a two stage reference: A hard reference via object is held to objects that should be hard wired in the memory. A soft reference is held via reference to objects that should be available to garbage collection. An object is "hard wired" when one of the following conditions is true:

• An explicit call to "harden" is made.
• The object or one of its descendants is changed.

You should not override equals or hash without really knowing what you do. Part of the implementation depends on indirect objects being real unique.

Method Summary

Object	accept(ICOSObjectVisitor visitor) Accept a visitor object.
ICOSContainer	associate(ICOSContainer newContainer, COSObject pObject) It is the responsibility of the current container to create the association with the new one.
COSDocumentElement	containable() The COSDocumentElement suitable for use in an ICOSContainer.
COSDocumentElement	containable(COSObject pObject) The stand-in to be used when object should be contained in a container.
static COSIndirectObject	create(COSObject object) Create an indirection for object.
static COSIndirectObject	create(STDocument stDoc, COSObjectKey key)
static COSIndirectObject	create(STDocument stDoc, int objectNumber, int generationNumber)
COSObject	dereference() Return the real object.
ICOSContainer	disassociate(ICOSContainer oldContainer, COSObject pObject) It is the responsibility of the current container to remove the association from the old one.
boolean	exists()
COSDocument	getDoc() The document where this is contained or null.
int	getGenerationNumber()
COSObjectKey	getKey() The key for this.
int	getObjectNumber()
void	harden(COSObject pObject) "Harden" the reference to object, keeping it from being garbage collected even if (temporarily) not accessed.
boolean	isDirty() true if the object graph referenced by this is changed.
boolean	isReference() Answer true if this element is a reference (a COSIndirectObject.
boolean	isSwapped() Answer true if this elements content is swapped to a persistent store.
int	referenceCount() The number of references to the contained object.
COSIndirectObject	referenceIndirect(COSObject pObject) Switch a contained object to an indirect one.
void	register(COSDocumentElement pObject) It is the responsibility of the active container to register object in its data structures.
void	registerWith(STDocument pSTDoc)
ICOSContainer	restoreStateContainer(ICOSContainer container) Restore the save state for the container.
ICOSContainer	saveStateContainer() Create a save state for the container when saving the COSObject state.
void	setDirty(boolean pDirty) Set the dirty state of the indirect object
void	setKey(COSObjectKey key) Assign a COSObjectKey to this.
void	setKey(int objectNumber, int generationNumber)
void	soften(COSObject pObject) "Soften" the reference to object, making it accessible for swapping out / garbage collection if the counter for hardening is zero.
STDocument	stGetDoc() The ST level document.
String	toString()
void	willChange(COSObject change) Propagate a change from a COSObject down in the hierarchy.

Methods inherited from class de.intarsys.pdf.cos.COSDocumentElement

handleException

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

create

public static COSIndirectObject create(COSObject object)

Create an indirection for object.

Parameters:

object - The object that should be indirect.

Returns:

The new indirect object.

create

public static COSIndirectObject create(STDocument stDoc,
                                       COSObjectKey key)

create

public static COSIndirectObject create(STDocument stDoc,
                                       int objectNumber,
                                       int generationNumber)

accept

public Object accept(ICOSObjectVisitor visitor)
              throws COSVisitorException

Description copied from class: COSDocumentElement

Accept a visitor object. The receiver selects the correct implementation in the visitor by "double dispatching".

Specified by:

accept in class COSDocumentElement

Parameters:

visitor - The object visiting the receiver.

Returns:

Object An object depending on the visitor semantics.

Throws:

COSVisitorException - An exception depending on the visitor semantics.

associate

public ICOSContainer associate(ICOSContainer newContainer,
                               COSObject pObject)

Description copied from interface: ICOSContainer

It is the responsibility of the current container to create the association with the new one. The table shows the available transitions | composite | indirect | | constant | n.a. | n.a. | (always copied before by "containable") null | ok | ok | composite | error | ok | indirect | ok | ok |

Specified by:

associate in interface ICOSContainer

Returns:

The resulting ICOSContainer for object

containable

public COSDocumentElement containable()

Description copied from class: COSDocumentElement

The COSDocumentElement suitable for use in an ICOSContainer. This may be a COSIndirectObject or the COSObject itself if not indirect.

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 class COSDocumentElement

containable

public COSDocumentElement containable(COSObject pObject)

Description copied from interface: ICOSContainer

The stand-in to be used when object should be contained in a container. This is either the object itself or the COSIndirectObject to it.

Specified by:

containable in interface ICOSContainer

Parameters:

pObject - THe object whose containable is requested.

Returns:

The stand-in to be used when object should be contained in a container.

dereference

public COSObject dereference()

Description copied from class: COSDocumentElement

Return the real object. This is either the object itself or the object referenced by a reference object (COSIndirectObject).

Specified by:

dereference in class COSDocumentElement

Returns:

The real object.

disassociate

public ICOSContainer disassociate(ICOSContainer oldContainer,
                                  COSObject pObject)

Description copied from interface: ICOSContainer

It is the responsibility of the current container to remove the association from the old one. The table shows the available transitions.

              | composite  | indirect   |
              |
    constant  | n.a.       | n.a.       |
    null      | n.a.       | n.a.       |
    composite | ok         | n.a.       |
    indirect  | ok         | n.a.       |
 

Specified by:

disassociate in interface ICOSContainer

Returns:

The resulting ICOSContainer for object

exists

public boolean exists()

getDoc

public COSDocument getDoc()

Description copied from class: COSDocumentElement

The document where this is contained or null. A COSDocumentElement is at most contained in a single COSDocument.

Specified by:

getDoc in interface ICOSContainer

Specified by:

getDoc in class COSDocumentElement

Returns:

The document where this is contained.

getGenerationNumber

public int getGenerationNumber()

getKey

public COSObjectKey getKey()

The key for this.

Returns:

The key for this.

getObjectNumber

public int getObjectNumber()

harden

public void harden(COSObject pObject)

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:

pObject - The object that should be kept in memory.

isDirty

public boolean isDirty()

true if the object graph referenced by this is changed.

Returns:

true if the object graph referenced by this is changed.

isReference

public boolean isReference()

Description copied from class: COSDocumentElement

Answer true if this element is a reference (a COSIndirectObject.

Overrides:

isReference in class COSDocumentElement

Returns:

Answer true if this element is a reference.

isSwapped

public boolean isSwapped()

Description copied from class: COSDocumentElement

Answer true if this elements content is swapped to a persistent store.

Overrides:

isSwapped in class COSDocumentElement

Returns:

Answer true if this elements content is swapped to a persistent store.

referenceCount

public int referenceCount()

Description copied from interface: ICOSContainer

The number of references to the contained object. This method returns -1 when the value can not be determined (as for indirect objects parsed from a file).

Specified by:

referenceCount in interface ICOSContainer

Returns:

The number of references to the contained object.

referenceIndirect

public COSIndirectObject referenceIndirect(COSObject pObject)

Description copied from interface: ICOSContainer

Switch a contained object to an indirect one. Update the reference.

Specified by:

referenceIndirect in interface ICOSContainer

Parameters:

pObject - The object to be indirect

register

public void register(COSDocumentElement pObject)

Description copied from interface: ICOSContainer

It is the responsibility of the active container to register object in its data structures.

Specified by:

register in interface ICOSContainer

Parameters:

pObject - The new object to be registered in the hierarchy.

registerWith

public void registerWith(STDocument pSTDoc)

Parameters:

pSTDoc -

restoreStateContainer

public ICOSContainer restoreStateContainer(ICOSContainer container)

Description copied from interface: ICOSContainer

Restore the save state for the container.

Specified by:

restoreStateContainer in interface ICOSContainer

Returns:

The "before" state of the receiver.

saveStateContainer

public ICOSContainer saveStateContainer()

Description copied from interface: ICOSContainer

Create a save state for the container when saving the COSObject state.

Specified by:

saveStateContainer in interface ICOSContainer

Returns:

The save state for the container.

setDirty

public void setDirty(boolean pDirty)

Set the dirty state of the indirect object

setKey

public void setKey(COSObjectKey key)

Assign a COSObjectKey to this.

Parameters:

key - The new key.

setKey

public void setKey(int objectNumber,
                   int generationNumber)

soften

public void soften(COSObject pObject)

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:

pObject - The object that should be kept in memory.

stGetDoc

public final STDocument stGetDoc()

The ST level document.

Returns:

The ST level document.

toString

public String toString()

Overrides:

toString in class Object

willChange

public void willChange(COSObject change)

Description copied from interface: ICOSContainer

Propagate a change from a COSObject down in the hierarchy.

Specified by:

willChange in interface ICOSContainer