KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > openide > src > MultiPropertyChangeEvent


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */
19
20 package org.openide.src;
21
22 import java.beans.PropertyChangeEvent JavaDoc;
23
24 import java.util.Collection JavaDoc;
25 import java.util.Collections JavaDoc;
26 import java.util.Iterator JavaDoc;
27
28 /**
29  * This class is much like the ordinary PropertyChange event, but refines the message
30  * so it carry diff between the old and the new contents. There are several operations
31  * that can be made on a multivalued property:<UL>
32  * <LI>add - new items were introduced into the property.
33  * <LI>remove - items were removed from the property.
34  * <LI>change - some items were atomically replaced by new ones.
35  * <LI>reorder - no items were removed or added, but only reordered within the multivalued
36  * property.
37  * </UL>
38  * <STRONG>ADD</STRONG> operation only introduces new items. For ordered multivalued properties,
39  * there's a index array with positions for each newly inserted element.<BR>
40  * <STRONG>REMOVE</STRONG> only mentiones elements that are being removed.<BR>
41  * <STRONG>CHANGE</STRONG> event specifies what items are being removed and what are replacing them.<BR>
42  * <STRONG>REORDER</STRONG> can specify:<UL>
43  * <LI>a permutation describing the reorder operation
44  * <LI>old and new state of the whole property
45  * <LI>old state and the permutation
46  * <LI>new state and the permutation
47  * </UL>
48  * <BR>
49  * Note: this event is not particularly useful for indexed properties with primitive
50  * values since the values does not have an identity and would need to be converted to
51  * wrapper Objects which is not cheap anyway.
52  * @author sdedic
53  * @version 0.1
54  * @since 24/11/2000
55  */
56 public class MultiPropertyChangeEvent extends PropertyChangeEvent JavaDoc {
57     /**
58      * Items are being added to the container.
59      */
60     public static final int TYPE_ADD = 1;
61     
62     /**
63      * Items are being removed from the container.
64      */
65     public static final int TYPE_REMOVE = 2;
66     
67     /** Items are being replaced.
68      */
69     public static final int TYPE_MODIFY = 3;
70     
71     /**
72      * Items are being reordered.
73      */
74     public static final int TYPE_REORDER = 4;
75     
76     /** Compound event, resulting from a generic change and comparisons
77      */
78     public static final int TYPE_COMPOUND = 5;
79
80     /** Items that are affected by the change. These are items being added or removed,
81      * items being replaced or partial changes for a compound event/
82      */
83     private Collection JavaDoc affected;
84     /** Collection of original items
85      */
86     
87     private Collection JavaDoc newItems;
88     /**
89      * Permutation for reorder changes.
90      */
91     private int[] indices;
92     /**
93      * Type of the event.
94      */
95     private int eventType;
96
97     public MultiPropertyChangeEvent(Object JavaDoc source, String JavaDoc propName,
98         Object JavaDoc oldVal, Object JavaDoc newVal) {
99         super(source, propName, oldVal, newVal);
100     }
101     
102     public void makeInsertion(Collection JavaDoc items, int[] indices) {
103         checkUninitialized();
104         this.affected = items;
105         this.indices = indices;
106         this.eventType = TYPE_ADD;
107     }
108     
109     public void makeRemoval(Collection JavaDoc items, int[] indices) {
110         checkUninitialized();
111         this.affected = items;
112         this.indices = indices;
113         this.eventType = TYPE_REMOVE;
114     }
115     
116     public void makeRemoval(Collection JavaDoc items) {
117         checkUninitialized();
118         this.affected = items;
119         this.eventType = TYPE_REMOVE;
120     }
121     
122     public void makeReorder(int[] permutation) {
123         checkUninitialized();
124         this.indices = permutation;
125         this.eventType = TYPE_REORDER;
126     }
127     
128     public void makeReplacement(Collection JavaDoc old, Collection JavaDoc n, int[] indices) {
129         checkUninitialized();
130         this.indices = indices;
131         this.affected = old;
132         this.newItems = n;
133         this.eventType = TYPE_MODIFY;
134     }
135     
136     public void makeCompound(Collection JavaDoc partialChanges, int[] offsets) {
137         checkUninitialized();
138         this.affected = partialChanges;
139         this.eventType = TYPE_COMPOUND;
140         this.indices = offsets;
141     }
142     
143     protected void checkUninitialized() {
144         if (this.eventType != 0) {
145             throw new IllegalStateException JavaDoc("Event object is already initialized."); // NOI18N
146 }
147     }
148     
149     /** Returns items affected by the operation. For add and remove operations, these
150      * are items added to or removed from the container, respectively. For change operation,
151      * the collection contains items that are being replaced in the container.
152      * @return collection of affected items. The collection is read-only.
153      */
154     public Collection JavaDoc getAffectedItems() {
155         return this.affected;
156     }
157     
158     public Collection JavaDoc getComponents() {
159         if (eventType != TYPE_COMPOUND)
160             throw new IllegalStateException JavaDoc("Not a compound event"); // NOI18N
161 return affected;
162     }
163     
164     /**
165      * Returns items that will replace {@link #getAffectedItems} in the container.
166      * @return r/o collection of new items that are being inserted in the container.
167      */
168     public Collection JavaDoc getReplacement() throws IllegalStateException JavaDoc {
169         if (eventType != TYPE_MODIFY)
170             throw new IllegalStateException JavaDoc("No replacement"); // NOI18N
171 return this.newItems;
172     }
173     
174     /**
175      * Returns the permutation that describes the REORDER operation.
176      * @return array of item's indexes in the new property's state. The array is indexed by positions in the old state.
177      * @throws IllegalStateException if the event is not REORDER type.
178      */
179     public int[] getPermutation() throws IllegalStateException JavaDoc {
180         if (eventType != TYPE_REORDER)
181             throw new IllegalStateException JavaDoc("Not reordered"); // NOI18N
182 return this.indices;
183     }
184
185     /** Returns array of relevant indices. For ADD operation, these are indexes which
186      * the elements are inserted at (0-based, one position beyond item count permitted).
187      * for REMOVE operation, indices are indexes to elements which are to be removed
188      * (indexes are computed prior to the removing any of the affected items).
189      * For MODIFY operation, this represents positions of elements which were replaced
190      * by another ones. Last, REORDER operation uses indices as a permutation that
191      * describes the reorder operation.
192      * @return array of (integer) indices
193      */
194     public int[] getIndices() {
195         return this.indices;
196     }
197     
198     public final int getEventType() {
199         return this.eventType;
200     }
201     
202     /**
203      * Returns iterator over partial operations collection in a compound change event.
204      * If the event is simple, the returned iterator will return the event itself.
205      */
206     public Iterator JavaDoc getIterator() {
207         if (getEventType() == TYPE_COMPOUND)
208             return getComponents().iterator();
209         else
210             return Collections.singleton(this).iterator();
211     }
212 }
213
Popular Tags