KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > internal > commands > CommandStateProxy


1 /*******************************************************************************
2  * Copyright (c) 2000, 2007 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11
12 package org.eclipse.ui.internal.commands;
13
14 import org.eclipse.core.commands.IStateListener;
15 import org.eclipse.core.commands.State;
16 import org.eclipse.core.runtime.CoreException;
17 import org.eclipse.core.runtime.IConfigurationElement;
18 import org.eclipse.core.runtime.IStatus;
19 import org.eclipse.core.runtime.Status;
20 import org.eclipse.jface.commands.PersistentState;
21 import org.eclipse.jface.preference.IPreferenceStore;
22 import org.eclipse.ui.internal.WorkbenchPlugin;
23
24 /**
25  * <p>
26  * A proxy for handler state that has been defined in XML. This delays the class
27  * loading until the state is really asked for information. Asking a proxy for
28  * anything (except disposing, and adding and removing listeners) will cause the
29  * proxy to instantiate the proxied handler.
30  * </p>
31  * <p>
32  * Loading the proxied state will automatically cause it to load its value from
33  * the preference store. Disposing of the state will cause it to persist its
34  * value.
35  * </p>
36  * <p>
37  * This class is not intended for use outside of the
38  * <code>org.eclipse.ui.workbench</code> plug-in.
39  * </p>
40  *
41  * @since 3.2
42  */
43 public final class CommandStateProxy extends PersistentState {
44
45     /**
46      * The configuration element from which the state can be created. This value
47      * will exist until the element is converted into a real class -- at which
48      * point this value will be set to <code>null</code>.
49      */
50     private IConfigurationElement configurationElement;
51
52     /**
53      * The key in the preference store to locate the persisted state.
54      */
55     private String JavaDoc preferenceKey;
56
57     /**
58      * The preference store containing the persisted state, if any.
59      */
60     private IPreferenceStore preferenceStore;
61
62     /**
63      * The real state. This value is <code>null</code> until the proxy is
64      * forced to load the real state. At this point, the configuration element
65      * is converted, nulled out, and this state gains a reference.
66      */
67     private State state = null;
68
69     /**
70      * The name of the configuration element attribute which contains the
71      * information necessary to instantiate the real state.
72      */
73     private final String JavaDoc stateAttributeName;
74
75     /**
76      * Constructs a new instance of <code>HandlerState</code> with all the
77      * information it needs to create the real state later.
78      *
79      * @param configurationElement
80      * The configuration element from which the real class can be
81      * loaded at run-time; must not be <code>null</code>.
82      * @param stateAttributeName
83      * The name of the attribute or element containing the state
84      * executable extension; must not be <code>null</code>.
85      * @param preferenceStore
86      * The preference store to which any persistent data should be
87      * written, and from which it should be loaded; may be
88      * <code>null</code>.
89      * @param preferenceKey
90      * The key at which the persistent data is located within the
91      * preference store.
92      */
93     public CommandStateProxy(final IConfigurationElement configurationElement,
94             final String JavaDoc stateAttributeName,
95             final IPreferenceStore preferenceStore, final String JavaDoc preferenceKey) {
96
97         if (configurationElement == null) {
98             throw new NullPointerException JavaDoc(
99                     "The configuration element backing a state proxy cannot be null"); //$NON-NLS-1$
100 }
101
102         if (stateAttributeName == null) {
103             throw new NullPointerException JavaDoc(
104                     "The attribute containing the state class must be known"); //$NON-NLS-1$
105 }
106
107         this.configurationElement = configurationElement;
108         this.stateAttributeName = stateAttributeName;
109         this.preferenceKey = preferenceKey;
110         this.preferenceStore = preferenceStore;
111     }
112
113     public final void addListener(final IStateListener listener) {
114         if (state == null) {
115             addListenerObject(listener);
116         } else {
117             state.addListener(listener);
118         }
119     }
120
121     public final void dispose() {
122         if (state != null) {
123             state.dispose();
124             if (state instanceof PersistentState) {
125                 final PersistentState persistableState = (PersistentState) state;
126                 if (persistableState.shouldPersist() && preferenceStore != null
127                         && preferenceKey != null) {
128                     persistableState.save(preferenceStore, preferenceKey);
129                 }
130             }
131         }
132     }
133
134     public final Object JavaDoc getValue() {
135         if (loadState()) {
136             return state.getValue();
137         }
138
139         return null;
140     }
141
142     public final void load(final IPreferenceStore store,
143             final String JavaDoc preferenceKey) {
144         if (loadState() && state instanceof PersistentState) {
145             final PersistentState persistableState = (PersistentState) state;
146             if (persistableState.shouldPersist() && preferenceStore != null
147                     && preferenceKey != null) {
148                 persistableState.load(preferenceStore, preferenceKey);
149             }
150         }
151     }
152
153     /**
154      * Loads the state, if possible. If the state is loaded, then the member
155      * variables are updated accordingly and the state is told to load its value
156      * from the preference store.
157      *
158      * @return <code>true</code> if the state is now non-null;
159      * <code>false</code> otherwise.
160      */
161     private final boolean loadState() {
162         return loadState(false);
163     }
164
165     /**
166      * Loads the state, if possible. If the state is loaded, then the member
167      * variables are updated accordingly and the state is told to load its value
168      * from the preference store.
169      *
170      * @param readPersistence
171      * Whether the persistent state for this object should be read.
172      * @return <code>true</code> if the state is now non-null;
173      * <code>false</code> otherwise.
174      */
175     private final boolean loadState(final boolean readPersistence) {
176         if (state == null) {
177             try {
178                 state = (State) configurationElement
179                         .createExecutableExtension(stateAttributeName);
180                 state.setId(getId());
181                 configurationElement = null;
182
183                 // Try to load the persistent state, if possible.
184 if (readPersistence && state instanceof PersistentState) {
185                     final PersistentState persistentState = (PersistentState) state;
186                     persistentState.setShouldPersist(true);
187                 }
188                 load(preferenceStore, preferenceKey);
189
190                 // Transfer the local listeners to the real state.
191 final Object JavaDoc[] listenerArray = getListeners();
192                 for (int i = 0; i < listenerArray.length; i++) {
193                     state.addListener((IStateListener) listenerArray[i]);
194                 }
195                 clearListeners();
196
197                 return true;
198
199             } catch (final ClassCastException JavaDoc e) {
200                 final String JavaDoc message = "The proxied state was the wrong class"; //$NON-NLS-1$
201 final IStatus status = new Status(IStatus.ERROR,
202                         WorkbenchPlugin.PI_WORKBENCH, 0, message, e);
203                 WorkbenchPlugin.log(message, status);
204                 return false;
205
206             } catch (final CoreException e) {
207                 final String JavaDoc message = "The proxied state for '" + configurationElement.getAttribute(stateAttributeName) //$NON-NLS-1$
208 + "' could not be loaded"; //$NON-NLS-1$
209 IStatus status = new Status(IStatus.ERROR,
210                         WorkbenchPlugin.PI_WORKBENCH, 0, message, e);
211                 WorkbenchPlugin.log(message, status);
212                 return false;
213             }
214         }
215
216         return true;
217     }
218
219     public final void removeListener(final IStateListener listener) {
220         if (state == null) {
221             removeListenerObject(listener);
222         } else {
223             state.removeListener(listener);
224         }
225     }
226
227     public final void save(final IPreferenceStore store,
228             final String JavaDoc preferenceKey) {
229         if (loadState() && state instanceof PersistentState) {
230             ((PersistentState) state).save(store, preferenceKey);
231         }
232     }
233
234     public final void setId(final String JavaDoc id) {
235         super.setId(id);
236         if (state != null) {
237             state.setId(id);
238         }
239     }
240
241     public final void setShouldPersist(final boolean persisted) {
242         if (loadState(persisted) && state instanceof PersistentState) {
243             ((PersistentState) state).setShouldPersist(persisted);
244         }
245     }
246
247     public final void setValue(final Object JavaDoc value) {
248         if (loadState()) {
249             state.setValue(value);
250         }
251     }
252
253     public final boolean shouldPersist() {
254         if (loadState() && state instanceof PersistentState) {
255             return ((PersistentState) state).shouldPersist();
256         }
257
258         return false;
259     }
260
261     public final String JavaDoc toString() {
262         if (state == null) {
263             return configurationElement.getAttribute(stateAttributeName);
264         }
265
266         return state.toString();
267     }
268 }
269
Popular Tags