jPod PDF library

de.intarsys.pdf.cos
Class COSIndirectObject

java.lang.Object
  extended by de.intarsys.pdf.cos.COSDocumentElement
      extended by 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:

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

jPod PDF library

Copyright © 2008 intarsys consulting GmbH. All Rights Reserved.