001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2005-2006, GeoTools Project Managment Committee (PMC)
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation;
009: * version 2.1 of the License.
010: *
011: * This library is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * Lesser General Public License for more details.
015: */
016: package org.geotools.event;
017:
018: import java.util.Collections;
019: import java.util.List;
020:
021: /**
022: * Indicates which style constructs have been changed.
023: *
024: * <p>
025: * Acts as a series of breadcrumbs stored up by a StyleEvent to communicate
026: * changes.
027: * </p>
028: *
029: * <p>
030: * This delta is constructed a fashion following the outline of the style
031: * document, allowing you to skip over entire branches of changes if you are
032: * not interested.
033: * </p>
034: * <h2>Example Use</h2>
035: * <p>
036: * The following examples will make use of the following
037: * allegorical data structure
038: * <pre><code>
039: * Root
040: * +--Parent
041: * +-- Child
042: * +-- List
043: * [0]--Element
044: * </code></pre>
045: * These roles are allegorical in nature any may be played
046: * in real life by arrays, beans, collections, etc..
047: * (as example StyleLayerDescriptor is a "Root").
048: * </p>
049: * <p>
050: * Example 0: An <b>Child</b> is changed.
051: * <pre><code>
052: * Event.POST_CHANGE
053: * +---Delta1 "" -1 NO_CHANGE(Root,null,)
054: * +---Delta2 "Parent" -1 NO_CHANGE (Parent, null )
055: * +---Delta3 "Child" -1 CHANGED (Child, oldChild )
056: * </code></pre>
057: * Location of <i>change</i> is indicated by delta, including
058: * name of "Child". The oldChild is provided incase you need to
059: * un-listen or something. Parent is not considered to have
060: * changed itself (it is still has the same structure).
061: * </p>
062: * <p>
063: * Example 1: An <b>Element</b> is changed:
064: * <pre><code>
065: * Event.POST_CHANGE
066: * +---Delta1 "" -1 NO_CHANGE(Root,null,)
067: * +---Delta2 "Parent" -1 NO_CHANGE (Parent, null )
068: * +---Delta3 "List" 0 CHANGED (Element, null )
069: * </code></pre>
070: * Location of <i>change</i> is indicated by delta, including position
071: * in list. Children in lists are children too, delta intentionally
072: * similar to the last.
073: * </p>
074: * <p>
075: * Example 2: A new <b>Element2</b> is added:
076: * <pre><code>
077: * Event.POST_CHANGE
078: * +---Delta1 "" -1 NO_CHANGE(Root,null,)
079: * +---Delta2 "Parent" -1 CHANGED (Parent, null )
080: * +---Delta3 "List" 1 ADDED (Element2, null )
081: * </code></pre>
082: * </p>
083: * Adding Element2 results in a change to Parent (it is structured
084: * diffrently). Position of the change in the "List" is indicated.
085: * <p>
086: * Example 3: Swap <b>Element</b> and Element2
087: * <pre><code>
088: * Event.POST_CHANGE
089: * +---Delta1 "" -1 NO_CHANGE(Root,null,)
090: * +---Delta2 "Parent" -1 CHANGED (Parent, null )
091: * +---Delta3 "List" 1 NO_CHANGE (Element, null )
092: * +---Delta4 "List" 0 NO_CHANGE (Element2, null )
093: * </code></pre>
094: * Moving things around does not change them, but it is a change to the
095: * Parent.
096: * </p>
097: * <p>
098: * Example 5: Remove <b>Element2</b>
099: * <pre><code>
100: * Event.POST_CHANGE
101: * +---Delta1 "" -1 NO_CHANGE(Root,null,)
102: * +---Delta2 "Parent" -1 CHANGED (Parent, null )
103: * +---Delta3 "List" -1 REMOVED ( null, Element2 )
104: * +---Delta4 "List" 0 NO_CHANGE (Element, null )
105: * </code></pre>
106: * Removing also is a considered a change to Parent, note
107: * this is a POST_CHANGE event so Element2 is an oldValue.
108: * The NO_CHANGE for Element is similar to Example4, it still
109: * indicates a change of position.
110: * </p>
111: * <p>
112: * Example 6: Go Fish
113: * <pre><code>
114: * Event.POST_CHANGE
115: * +---Delta1 "" -1 CHANGED(Root,null,)
116: * </code></pre>
117: * Something changed somewhere, similar to "touch".
118: * </p>
119: * <p>
120: * Example 7: Shutting Down
121: * <pre><code>
122: * Event.PRE_CLOSE
123: * +---Delta1 "" -1 NO_CHANGE(Root,null,)
124: * </code></pre>
125: * That was easy then...
126: * </p>
127: * <p>
128: * You should be aware that the event system may "collapse"
129: * events that duplicate information, especially when
130: * considering batch changes resulting from the application
131: * of a visitor or transformation.
132: * </p>
133: * @author Jody Garnett, Refractions Research
134: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/api/src/main/java/org/geotools/event/GTDelta.java $
135: */
136: public interface GTDelta {
137: /** List indicating no children are present */
138: public static final List NO_CHILDREN = Collections.EMPTY_LIST;
139:
140: /** Index position is not to be considered relevent */
141: public static final int NO_INDEX = -1;
142:
143: /**
144: * Returns the kind of this delta.
145: *
146: * <p>
147: * Normally, one of <code>ADDED</code>, <code>REMOVED</code> or
148: * <code>CHANGED</code>.
149: * </p>
150: *
151: * @return the kind of this resource delta
152: *
153: * @see Kind.ADDED
154: * @see Kind.REMOVED
155: * @see Kind.CHANGED
156: */
157: public Kind getKind();
158:
159: /**
160: * Affected construct, getKind & getChildern
161: * indicate specific details of the change.
162: *
163: * @return Affected construct
164: */
165: public Object getValue();
166:
167: /**
168: * Construct being replaced with a changed, getValue is the replacing value.
169: *
170: * @return Affected construct
171: */
172: public Object getOldValue();
173:
174: /**
175: * Position in a "list" where the change occured, or NO_INDEX.
176: *
177: * @return Position in "list" or NO_INDEX.
178: */
179: public int getPosition();
180:
181: /**
182: * Name of property being affected.
183: * <p>
184: * <ul>
185: * <li>propertyName: "bean" property name when intergrating third party
186: * Java Beans into a more complex tree structure.
187: * <li>List and Arrays: the name of the list, and may be
188: * combined with getPosition to indicate location, NO_INDEX would indicate
189: * the entire "list" has been modified.
190: * </ul>
191: * </p>
192: * @return name of affected Child, or <code>null</code> for root
193: */
194: public String getName();
195:
196: /**
197: * Finds and returns deltas for specificly changed constructs.
198: * <p>
199: * This code may be considered more accessable then the use of
200: * GTDeltaVisitor.
201: * </p>
202: *
203: * @return List of StyleDelta
204: */
205: public List getChildren();
206:
207: /**
208: * Accepts the given visitor.
209: *
210: * @param visitor
211: */
212: public void accept(GTDeltaVisitor visitor);
213:
214: /**
215: * Kind of Delta, used to indicate change.
216: *
217: * @since 2.2.M3
218: */
219: public class Kind {
220: /**
221: * Indicates no change.
222: * <p>
223: * GTDelta defined values:
224: * <ul>
225: * <li>getValue(): unchanged value
226: * <li>getOldValue(): null
227: * <li>getPosition(): index in list, or NO_INDEX
228: * </ul>
229: * May be considered a touch if it occurs as the last delta,
230: * usually just indicates that a child has undergone a change.
231: * </p>
232: * @see #getKind()
233: */
234: public static final Kind NO_CHANGE = new Kind();
235:
236: /**
237: * The construct has been added (usually to a list)
238: * <p>
239: * GTDelta defined values:
240: * <ul>
241: * <li>getValue(): added value
242: * <li>getOldValue(): null
243: * <li>getPosition(): index in list, or NO_INDEX
244: * </ul>
245: * </p>
246: * @see #getKind()
247: */
248: public static final Kind ADDED = new Kind();
249:
250: /**
251: * The construct has been removed (usually from a list)
252: * <p>
253: * GTDelta defined values:
254: * <ul>
255: * <li>getValue(): value being removed
256: * <li>getOldValue(): null
257: * <li>getPosition(): index in list, or NO_INDEX
258: * </ul>
259: * </p>
260: * <p>
261: * Since REMOVED deltas are sent before the delete is performed
262: * getValue is still valid.
263: * </p>
264: *
265: * @see #getKind()
266: */
267: public static final Kind REMOVED = new Kind();
268:
269: /**
270: * The construct has been changed.
271: * <p>
272: * GTDelta defined values:
273: * <ul>
274: * <li>getValue(): current value
275: * <li>getOldValue(): previous value (being replaced)
276: * <li>getPosition(): index in list, or NO_INDEX
277: * </ul>
278: * </p>
279: * @see #getKind()
280: */
281: public static final Kind CHANGED = new Kind();
282: }
283: }
|