001: /*
002: * Copyright (c) 2007, intarsys consulting GmbH
003: *
004: * Redistribution and use in source and binary forms, with or without
005: * modification, are permitted provided that the following conditions are met:
006: *
007: * - Redistributions of source code must retain the above copyright notice,
008: * this list of conditions and the following disclaimer.
009: *
010: * - Redistributions in binary form must reproduce the above copyright notice,
011: * this list of conditions and the following disclaimer in the documentation
012: * and/or other materials provided with the distribution.
013: *
014: * - Neither the name of intarsys nor the names of its contributors may be used
015: * to endorse or promote products derived from this software without specific
016: * prior written permission.
017: *
018: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
019: * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
020: * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
021: * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
022: * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
023: * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
024: * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
025: * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
026: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
027: * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
028: * POSSIBILITY OF SUCH DAMAGE.
029: */
030: package de.intarsys.pdf.cos;
031:
032: import java.util.Map;
033: import java.util.Set;
034:
035: /**
036: * This is a cos level representation of the elements that may be contained in a
037: * cos container. An element may be either a {@link
038: * de.intarsys.pdf.cos.COSObject} or a
039: * {@link de.intarsys.pdf.cos.COSIndirectObject} to a
040: * {@link de.intarsys.pdf.cos.COSObject}. A
041: * {@link de.intarsys.pdf.cos.COSIndirectObject} is never seen by an application
042: * level programmer, this is an internal construct only.
043: *
044: */
045: abstract public class COSDocumentElement implements
046: ICOSExceptionHandler {
047: protected COSDocumentElement() {
048: //
049: }
050:
051: /**
052: * Answer <code>true</code> if this element is a reference (a
053: * {@link COSIndirectObject}.
054: *
055: * @return Answer <code>true</code> if this element is a reference.
056: */
057: public boolean isReference() {
058: return false;
059: }
060:
061: /**
062: * Answer <code>true</code> if this elements content is swapped to a
063: * persistent store.
064: *
065: * @return Answer <code>true</code> if this elements content is swapped to
066: * a persistent store.
067: */
068: public boolean isSwapped() {
069: return false;
070: }
071:
072: /**
073: * Return the real object. This is either the object itself or the object
074: * referenced by a reference object ({@link COSIndirectObject}).
075: *
076: * @return The real object.
077: */
078: abstract public COSObject dereference();
079:
080: /**
081: * Register the all indirect objects that can be reached from this with doc
082: *
083: * @param doc
084: * The container document
085: */
086: abstract protected void registerWith(COSDocument doc);
087:
088: /**
089: * see copyDeep()
090: *
091: * <p>
092: * This method keeps track of already copied objects to deal with cyclic
093: * references.
094: * </p>
095: *
096: * @see de.intarsys.pdf.cos.COSObject#copyDeep()
097: */
098: abstract protected COSObject copyDeep(Map copied);
099:
100: protected boolean equals(Object o, Set visited) {
101: return this .equals(o);
102: }
103:
104: /**
105: * Accept a visitor object. The receiver selects the correct implementation
106: * in the <code>visitor</code> by "double dispatching".
107: *
108: * @param visitor
109: * The object visiting the receiver.
110: *
111: * @return Object An object depending on the visitor semantics.
112: *
113: * @throws COSVisitorException
114: * An exception depending on the visitor semantics.
115: */
116: abstract public Object accept(ICOSObjectVisitor visitor)
117: throws COSVisitorException;
118:
119: /**
120: * The document where this is contained or null. A
121: * {@link COSDocumentElement} is at most contained in a single
122: * {@link COSDocument}.
123: *
124: * @return The document where this is contained.
125: */
126: abstract public COSDocument getDoc();
127:
128: /**
129: * Add a backward reference to the container when the receiver is added to a
130: * container object. The implementation depends on the type of containement
131: * for the object so far (direct/indirect), so we delegate to the old
132: * container.
133: *
134: * @param newContainer
135: * the new container embedding the object
136: * @return The new {@link ICOSContainer} associated with this.
137: */
138: abstract protected ICOSContainer addContainer(
139: ICOSContainer newContainer);
140:
141: /**
142: * Remove a backward reference to the container when the receiver is removed
143: * from a container object. The implementation depends on the type of
144: * containement for the object so far (direct/indirect), so we delegate to
145: * the old container.
146: *
147: * @param oldContainer
148: * the container that no longer embeds the receiver
149: * @return The new {@link ICOSContainer} associated with this.
150: */
151: abstract protected ICOSContainer removeContainer(
152: ICOSContainer oldContainer);
153:
154: /**
155: * The {@link COSDocumentElement} suitable for use in an
156: * {@link ICOSContainer}. This may be a {@link COSIndirectObject} or the
157: * {@link COSObject} itself if not indirect.
158: * <p>
159: * This method should not be used by the application programmer. This is
160: * called in the {@link COSObject} lifecycle to ensure internal consistency.
161: */
162: abstract public COSDocumentElement containable();
163:
164: abstract protected COSDocumentElement copyShallowNested();
165:
166: /*
167: * (non-Javadoc)
168: *
169: * @see de.intarsys.pdf.cos.ICOSExceptionHandler#error(de.intarsys.pdf.cos.COSRuntimeException)
170: */
171: public void handleException(COSRuntimeException ex)
172: throws COSRuntimeException {
173: COSDocument doc = getDoc();
174: if (doc != null) {
175: doc.handleException(ex);
176: } else {
177: throw ex;
178: }
179: }
180: }
|