/*******************************************************************************
* Copyright (c) 2000, 2007 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.ui.internal.commands;
import org.eclipse.core.commands.IStateListener;
import org.eclipse.core.commands.State;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IConfigurationElement;
import org.eclipse.core.runtime.IStatus;
import org.eclipse.core.runtime.Status;
import org.eclipse.jface.commands.PersistentState;
import org.eclipse.jface.preference.IPreferenceStore;
import org.eclipse.ui.internal.WorkbenchPlugin;
/**
* <p>
* A proxy for handler state that has been defined in XML. This delays the class
* loading until the state is really asked for information. Asking a proxy for
* anything (except disposing, and adding and removing listeners) will cause the
* proxy to instantiate the proxied handler.
* </p>
* <p>
* Loading the proxied state will automatically cause it to load its value from
* the preference store. Disposing of the state will cause it to persist its
* value.
* </p>
* <p>
* This class is not intended for use outside of the
* <code>org.eclipse.ui.workbench</code> plug-in.
* </p>
*
* @since 3.2
*/
public final class CommandStateProxy extends PersistentState {
/**
* The configuration element from which the state can be created. This value
* will exist until the element is converted into a real class -- at which
* point this value will be set to <code>null</code>.
*/
private IConfigurationElement configurationElement;
/**
* The key in the preference store to locate the persisted state.
*/
private String preferenceKey;
/**
* The preference store containing the persisted state, if any.
*/
private IPreferenceStore preferenceStore;
/**
* The real state. This value is <code>null</code> until the proxy is
* forced to load the real state. At this point, the configuration element
* is converted, nulled out, and this state gains a reference.
*/
private State state = null;
/**
* The name of the configuration element attribute which contains the
* information necessary to instantiate the real state.
*/
private final String stateAttributeName;
/**
* Constructs a new instance of <code>HandlerState</code> with all the
* information it needs to create the real state later.
*
* @param configurationElement
* The configuration element from which the real class can be
* loaded at run-time; must not be <code>null</code>.
* @param stateAttributeName
* The name of the attribute or element containing the state
* executable extension; must not be <code>null</code>.
* @param preferenceStore
* The preference store to which any persistent data should be
* written, and from which it should be loaded; may be
* <code>null</code>.
* @param preferenceKey
* The key at which the persistent data is located within the
* preference store.
*/
public CommandStateProxy(final IConfigurationElement configurationElement,
final String stateAttributeName,
final IPreferenceStore preferenceStore, final String preferenceKey) {
if (configurationElement == null) {
throw new NullPointerException(
"The configuration element backing a state proxy cannot be null"); //$NON-NLS-1$
}
if (stateAttributeName == null) {
throw new NullPointerException(
"The attribute containing the state class must be known"); //$NON-NLS-1$
}
this.configurationElement = configurationElement;
this.stateAttributeName = stateAttributeName;
this.preferenceKey = preferenceKey;
this.preferenceStore = preferenceStore;
}
public final void addListener(final IStateListener listener) {
if (state == null) {
addListenerObject(listener);
} else {
state.addListener(listener);
}
}
public final void dispose() {
if (state != null) {
state.dispose();
if (state instanceof PersistentState) {
final PersistentState persistableState = (PersistentState) state;
if (persistableState.shouldPersist() && preferenceStore != null
&& preferenceKey != null) {
persistableState.save(preferenceStore, preferenceKey);
}
}
}
}
public final Object getValue() {
if (loadState()) {
return state.getValue();
}
return null;
}
public final void load(final IPreferenceStore store,
final String preferenceKey) {
if (loadState() && state instanceof PersistentState) {
final PersistentState persistableState = (PersistentState) state;
if (persistableState.shouldPersist() && preferenceStore != null
&& preferenceKey != null) {
persistableState.load(preferenceStore, preferenceKey);
}
}
}
/**
* Loads the state, if possible. If the state is loaded, then the member
* variables are updated accordingly and the state is told to load its value
* from the preference store.
*
* @return <code>true</code> if the state is now non-null;
* <code>false</code> otherwise.
*/
private final boolean loadState() {
return loadState(false);
}
/**
* Loads the state, if possible. If the state is loaded, then the member
* variables are updated accordingly and the state is told to load its value
* from the preference store.
*
* @param readPersistence
* Whether the persistent state for this object should be read.
* @return <code>true</code> if the state is now non-null;
* <code>false</code> otherwise.
*/
private final boolean loadState(final boolean readPersistence) {
if (state == null) {
try {
state = (State) configurationElement
.createExecutableExtension(stateAttributeName);
state.setId(getId());
configurationElement = null;
// Try to load the persistent state, if possible.
if (readPersistence && state instanceof PersistentState) {
final PersistentState persistentState = (PersistentState) state;
persistentState.setShouldPersist(true);
}
load(preferenceStore, preferenceKey);
// Transfer the local listeners to the real state.
final Object[] listenerArray = getListeners();
for (int i = 0; i < listenerArray.length; i++) {
state.addListener((IStateListener) listenerArray[i]);
}
clearListeners();
return true;
} catch (final ClassCastException e) {
final String message = "The proxied state was the wrong class"; //$NON-NLS-1$
final IStatus status = new Status(IStatus.ERROR,
WorkbenchPlugin.PI_WORKBENCH, 0, message, e);
WorkbenchPlugin.log(message, status);
return false;
} catch (final CoreException e) {
final String message = "The proxied state for '" + configurationElement.getAttribute(stateAttributeName) //$NON-NLS-1$
+ "' could not be loaded"; //$NON-NLS-1$
IStatus status = new Status(IStatus.ERROR,
WorkbenchPlugin.PI_WORKBENCH, 0, message, e);
WorkbenchPlugin.log(message, status);
return false;
}
}
return true;
}
public final void removeListener(final IStateListener listener) {
if (state == null) {
removeListenerObject(listener);
} else {
state.removeListener(listener);
}
}
public final void save(final IPreferenceStore store,
final String preferenceKey) {
if (loadState() && state instanceof PersistentState) {
((PersistentState) state).save(store, preferenceKey);
}
}
public final void setId(final String id) {
super.setId(id);
if (state != null) {
state.setId(id);
}
}
public final void setShouldPersist(final boolean persisted) {
if (loadState(persisted) && state instanceof PersistentState) {
((PersistentState) state).setShouldPersist(persisted);
}
}
public final void setValue(final Object value) {
if (loadState()) {
state.setValue(value);
}
}
public final boolean shouldPersist() {
if (loadState() && state instanceof PersistentState) {
return ((PersistentState) state).shouldPersist();
}
return false;
}
public final String toString() {
if (state == null) {
return configurationElement.getAttribute(stateAttributeName);
}
return state.toString();
}
}
