jPod PDF library

de.intarsys.pdf.cos
Class COSObject

java.lang.Object
  extended by de.intarsys.pdf.cos.COSDocumentElement
      extended by de.intarsys.pdf.cos.COSObject
All Implemented Interfaces:
ICOSExceptionHandler, de.intarsys.tools.component.ISaveStateSupport
Direct Known Subclasses:
COSCompositeObject, COSPrimitiveObject

public abstract class COSObject
extends COSDocumentElement
implements de.intarsys.tools.component.ISaveStateSupport

Abstract superclass for all COS level object types


Field Summary
static ICOSContainer CONSTANT_CONTAINER
          This is the container for template objects.
static ICOSContainer NULL_CONTAINER
          This is the default container for non - contained objects.
static Object SLOT_CONTAINER
           
 
Method Summary
abstract  void addObjectListener(ICOSObjectListener listener)
          Add a listener for object changes.
 COSArray asArray()
          this as a COSArray or null
 COSBoolean asBoolean()
           
 COSDictionary asDictionary()
           
 COSFixed asFixed()
           
 COSInteger asInteger()
           
 COSName asName()
           
 COSNull asNull()
           
 COSNumber asNumber()
           
 COSStream asStream()
           
 COSString asString()
           
abstract  Iterator<COSDocumentElement> basicIterator()
          An iterator over contained objects and references.
 COSObject beConstant()
          Declare this to be a constant.
 COSIndirectObject beIndirect()
          Make an indirect object out of a direct one.
 COSDocumentElement containable()
          The COSDocumentElement suitable for use in an ICOSContainer.
abstract  COSObject copyDeep()
          Make a deep copy of the receiver within the same document.
abstract  COSObject copyDeep(Map copied)
          Make a deep copy of the receiver within the same document.
 COSObject copyOptional()
          Make a copy of the receiver within the same document.
 COSObject copyShallow()
          Make a copy of the receiver.
 COSObject copySubGraph()
          Make a copy of the receiver within the same document.
 COSObject dereference()
          return the real object. this is needed for polymorphic handling of document elements. at application programming level only COSObject, never COSIndirectObject is seen.
 ICOSContainer getContainer()
          Answer the object that contains this.
 COSDocument getDoc()
          The document that contains this.
 COSIndirectObject getIndirectObject()
          return the indirect object for the receiver. application level programmers should not use this method. this is needed for creating a physical representation of the document (serializing)
 boolean getValueBoolean(boolean defaultValue)
          "Cast" the receiver to a Java boolean.
 byte[] getValueBytes(byte[] defaultValue)
          "Cast" the receiver to a Java byte[].This is a convenience method to ease programming with COSObject.
 float getValueFloat(float defaultValue)
          "Cast" the receiver to a Java float.This is a convenience method to ease programming with COSObject.
 int getValueInteger(int defaultValue)
          "Cast" the receiver to a Java int.This is a convenience method to ease programming with COSObject.
 String getValueString(String defaultValue)
          "Cast" the receiver to a Java String.This is a convenience method to ease programming with COSObject.
 void harden()
          "Harden" the reference to this object.
 boolean isDangling()
          true if this object is not contained in a document directly or indirectly.
 boolean isIndirect()
          Answer true if this object is an indirect one.
 boolean isNull()
          answer true if receiver is the null object
 boolean isNumber()
          answer true if receiver is a number
abstract  boolean isObjectListenerAvailable()
          true if an ICOSObjectListener is registered.
abstract  boolean isPrimitive()
          Answer true if this object is of a primitive type
 boolean isSwapped()
          Answer true if this elements content is swapped to a persistent store.
abstract  Iterator iterator()
          An iterator over contained objects.
 boolean mayBeSwapped()
          true if this object may be swapped from memory by the garbage collector.
abstract  void removeObjectListener(ICOSObjectListener listener)
          Remove a listener for object changes.
 void restoreState(Object saveState)
           
 void soften()
          "Soften" the reference to this object.
 String stringValue()
          A string representation for the receiver.
 String toString()
           
 
Methods inherited from class de.intarsys.pdf.cos.COSDocumentElement
accept, handleException, isReference
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface de.intarsys.tools.component.ISaveStateSupport
saveState
 

Field Detail

CONSTANT_CONTAINER

public static final ICOSContainer CONSTANT_CONTAINER
This is the container for template objects. Template objects can be created static in the application and are copied behind the scenes when integrated in a document.


NULL_CONTAINER

public static final ICOSContainer NULL_CONTAINER
This is the default container for non - contained objects.


SLOT_CONTAINER

public static final Object SLOT_CONTAINER
Method Detail

addObjectListener

public abstract void addObjectListener(ICOSObjectListener listener)
Add a listener for object changes.

Parameters:
listener - The listener to be informed about changes.

asArray

public COSArray asArray()
this as a COSArray or null

Returns:
this as a COSArray or null

asBoolean

public COSBoolean asBoolean()
Returns:
this as a COSBoolean or null

asDictionary

public COSDictionary asDictionary()
Returns:
this as a COSDictionary or null

asFixed

public COSFixed asFixed()
Returns:
this as a COSFixed or null

asInteger

public COSInteger asInteger()
Returns:
this as a COSInteger or null

asName

public COSName asName()
Returns:
this as a COSName or null

asNull

public COSNull asNull()
Returns:
this as a COSNull or null

asNumber

public COSNumber asNumber()
Returns:
this as a COSNumber or null

asStream

public COSStream asStream()
Returns:
this as a COSStream or null

asString

public COSString asString()
Returns:
this as a COSString or null

basicIterator

public abstract Iterator<COSDocumentElement> basicIterator()
An iterator over contained objects and references. The iterator is an empty iterator if this is not a container.

This iterator returns COSDocumentElements, leaving references alone.

Returns:
Iterator over contained objects and references.

beConstant

public COSObject beConstant()
Declare this to be a constant. This declaration ensures that when using this in a document context a copy will be made.

Returns:
The receiver.

beIndirect

public COSIndirectObject beIndirect()
Make an indirect object out of a direct one. An object can always be changed to an indirect one.

It is possible to morph existing objects into indirect ones, the objects in the hierarchy (container/document) are informed and will reflect the change.


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

copyDeep

public abstract COSObject copyDeep()
Make a deep copy of the receiver within the same document. The result is a "PDF semantic" deep copy, implementation artifacts as "attributes" and listeners are NOT copied.

The algorithm copies this along with all outgoing references (recursively).

Object identity is preserved.

Be careful when copying objects, as there are semantics that may NOT be recognized by this method.

Returns:
the object copied recursively

copyDeep

public abstract COSObject copyDeep(Map copied)
Make a deep copy of the receiver within the same document. The result is a "PDF semantic" deep copy, implementation artifacts as "attributes" and listeners are NOT copied.

The copied map is used to identify objects copied in earlier runs of this method to avoid duplicating resources used in different copy targets (for example the pages of a document). copied is modified while executing copyDeep and contains a mapping from indirect objects in the original document to copied objects.

The algorithm copies this along with all outgoing references (recursively).

Object identity is preserved.

Be careful when copying objects, as there are semantics that may NOT be recognized by this method.

Returns:
the object copied recursively
See Also:
copyDeep()

copyOptional

public final COSObject copyOptional()
Make a copy of the receiver within the same document. A copy is made only if we have an object that may not be inserted in multiple containers. This means all direct objects are (recursively) copied, all indirect objects return the receiver.

Be careful when copying objects, as there are semantics that may NOT be recognized by this method.

Returns:
The optional copy.

copyShallow

public COSObject copyShallow()
Make a copy of the receiver.

A copy is made of the receiver and after this recursively of all not indirect objects.

Be careful when copying objects, as there are semantics that may NOT be recognized by this method.

Returns:
The object copied

copySubGraph

public final COSObject copySubGraph()
Make a copy of the receiver within the same document.

The algorithm copies this along with all outgoing references (recursively) that themselve have a navigation path to this. The result is a new subgraph extending from the copy of this where no navigation path leads back to this.

Object identity is preserved.

Be careful when copying objects, as there are semantics that may NOT be recognized by this method.

Returns:
the object copied recursively

dereference

public COSObject dereference()
return the real object. this is needed for polymorphic handling of document elements. at application programming level only COSObject, never COSIndirectObject is seen.

Specified by:
dereference in class COSDocumentElement
Returns:
COSObject

getContainer

public ICOSContainer getContainer()
Answer the object that contains this. The container is never null.

Returns:
Answer the object that contains this.

getDoc

public COSDocument getDoc()
The document that contains this.

This may return null, as COSObject graphs may be created "offline" and add to the document as a whole.

The document is evaluated via the COSObject graph hierarchy that finally must be contained within a document.

Specified by:
getDoc in class COSDocumentElement
Returns:
The document that contains this.

getIndirectObject

public COSIndirectObject getIndirectObject()
return the indirect object for the receiver. application level programmers should not use this method. this is needed for creating a physical representation of the document (serializing)

Returns:
the indirect object for the receiver

getValueBoolean

public boolean getValueBoolean(boolean defaultValue)
"Cast" the receiver to a Java boolean. This is a convenience method to ease programming with COSObject.

Parameters:
defaultValue - The default value to return.
Returns:
The value of the receiver if not null and type compatible, the defaultValue otherwise.

getValueBytes

public byte[] getValueBytes(byte[] defaultValue)
"Cast" the receiver to a Java byte[].This is a convenience method to ease programming with COSObject.

Parameters:
defaultValue - The default value to return.
Returns:
The value of the receiver if not null and type compatible, the defaultValue otherwise.

getValueFloat

public float getValueFloat(float defaultValue)
"Cast" the receiver to a Java float.This is a convenience method to ease programming with COSObject.

Parameters:
defaultValue - The default value to return.
Returns:
The value of the receiver if not null and type compatible, the defaultValue otherwise.

getValueInteger

public int getValueInteger(int defaultValue)
"Cast" the receiver to a Java int.This is a convenience method to ease programming with COSObject.

Parameters:
defaultValue - The default value to return.
Returns:
The value of the receiver if not null and type compatible, the defaultValue otherwise.

getValueString

public String getValueString(String defaultValue)
"Cast" the receiver to a Java String.This is a convenience method to ease programming with COSObject.

Parameters:
defaultValue - The default value to return.
Returns:
The value of the receiver if not null and type compatible, the defaultValue otherwise.

harden

public void harden()
"Harden" the reference to this object. The indirect object at the root of the containment hierarchy will force a strong reference to its root COSObject.


isDangling

public boolean isDangling()
true if this object is not contained in a document directly or indirectly. This is especially true when an object is new (or reset to this state when an undo happend). Remember that an object can still be garbage, even if it is not dangling.

Returns:
true if this object is not contained in a document directly or indirectly.

isIndirect

public boolean isIndirect()
Answer true if this object is an indirect one.

Returns:
true if this object is an indirect one.

isNull

public boolean isNull()
answer true if receiver is the null object

Returns:
true if receiver is the null object

isNumber

public boolean isNumber()
answer true if receiver is a number

Returns:
answer true if receiver is a number

isObjectListenerAvailable

public abstract boolean isObjectListenerAvailable()
true if an ICOSObjectListener is registered. This is for test purposes.


isPrimitive

public abstract boolean isPrimitive()
Answer true if this object is of a primitive type

Returns:
Answer true if this object is of a primitive type

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.

iterator

public abstract Iterator iterator()
An iterator over contained objects. The iterator is an empty iterator if this is not a container.

This iterator returns only COSObject instances, references are dereferenced.

Returns:
Iterator over contained objects.

mayBeSwapped

public boolean mayBeSwapped()
true if this object may be swapped from memory by the garbage collector.

Returns:
true if this object may be swapped from memory by the garbage collector.

removeObjectListener

public abstract void removeObjectListener(ICOSObjectListener listener)
Remove a listener for object changes.

Parameters:
listener - The listener to be removed.

restoreState

public void restoreState(Object saveState)
Specified by:
restoreState in interface de.intarsys.tools.component.ISaveStateSupport

soften

public void soften()
"Soften" the reference to this object. The indirect object at the root of the containment hierarchy will release a strong reference to its root COSObject.


stringValue

public String stringValue()
A string representation for the receiver. This is a very "soft" definition. Do not rely on any specific format to be returned here.

Returns:
A string representation for the receiver.

toString

public String toString()
Overrides:
toString in class Object

jPod PDF library

Copyright © 2008 intarsys consulting GmbH. All Rights Reserved.