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: /**
033: * A low level interface for polymorphic access to an object containing a
034: * COSObject.
035: * <p>
036: * This is implemented for example by {@link COSArray}.
037: *
038: */
039: public interface ICOSContainer {
040: /**
041: * It is the responsibility of the current container to create the
042: * association with the new one.
043: *
044: * The table shows the available transitions
045: *
046: * <code>
047: * | composite | indirect |
048: * |
049: * constant | n.a. | n.a. | (always copied before by "containable")
050: * null | ok | ok |
051: * composite | error | ok |
052: * indirect | ok | ok |
053: * </code>
054: *
055: * @param newContainer
056: * @param object
057: * @return The resulting {@link ICOSContainer} for <code>object</code>
058: */
059: public ICOSContainer associate(ICOSContainer newContainer,
060: COSObject object);
061:
062: /**
063: * It is the responsibility of the current container to remove the
064: * association from the old one.
065: *
066: * The table shows the available transitions.
067: *
068: * <pre>
069: * | composite | indirect |
070: * |
071: * constant | n.a. | n.a. |
072: * null | n.a. | n.a. |
073: * composite | ok | n.a. |
074: * indirect | ok | n.a. |
075: * </pre>
076: *
077: * @param oldContainer
078: * @param object
079: * @return The resulting {@link ICOSContainer} for <code>object</code>
080: */
081: public ICOSContainer disassociate(ICOSContainer oldContainer,
082: COSObject object);
083:
084: /**
085: * The stand-in to be used when object should be contained in a container.
086: * This is either the object itself or the COSIndirectObject to it.
087: *
088: * @param object
089: * THe object whose containable is requested.
090: *
091: * @return The stand-in to be used when object should be contained in a
092: * container.
093: */
094: public COSDocumentElement containable(COSObject object);
095:
096: /**
097: * The COSDocument instance where the ICOSContainer is contained.
098: *
099: * @return The COSDocument instance where the ICOSContainer is contained.
100: */
101: public COSDocument getDoc();
102:
103: /**
104: * Propagate a change from a COSObject down in the hierarchy.
105: */
106: public void willChange(COSObject object);
107:
108: /**
109: * The number of references to the contained object. This method returns -1
110: * when the value can not be determined (as for indirect objects parsed from
111: * a file).
112: *
113: * @return The number of references to the contained object.
114: */
115: public int referenceCount();
116:
117: /**
118: * Switch a contained object to an indirect one. Update the reference.
119: *
120: * @param object
121: * The object to be indirect
122: */
123: public COSIndirectObject referenceIndirect(COSObject object);
124:
125: /**
126: * It is the responsibility of the active container to register object in
127: * its data structures.
128: *
129: * @param object
130: * The new object to be registered in the hierarchy.
131: */
132: public void register(COSDocumentElement object);
133:
134: /**
135: * Restore the save state for the container.
136: *
137: * @param container
138: * @return The "before" state of the receiver.
139: */
140: public ICOSContainer restoreStateContainer(ICOSContainer container);
141:
142: /**
143: * Create a save state for the container when saving the COSObject state.
144: *
145: * @return The save state for the container.
146: */
147: public ICOSContainer saveStateContainer();
148: }
|