001: /*******************************************************************************
002: * Copyright (c) 2003, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.commands;
011:
012: import java.util.Map;
013:
014: import org.eclipse.ui.internal.util.Util;
015:
016: /**
017: * An instance of this class describes changes to an instance of
018: * <code>IHandler</code>.
019: * <p>
020: * This class is not intended to be extended by clients.
021: * </p>
022: *
023: * @since 3.0
024: * @see IHandlerListener#handlerChanged(HandlerEvent)
025: * @deprecated Please use the "org.eclipse.core.commands" plug-in instead.
026: */
027: public final class HandlerEvent {
028:
029: /**
030: * Whether the attributes of the handler changed.
031: */
032: private final boolean attributeValuesByNameChanged;
033:
034: /**
035: * The handler that changed; this value is never <code>null</code>.
036: */
037: private final IHandler handler;
038:
039: /**
040: * This is the cached result of getPreviousAttributeValuesByName. It is
041: * computed the first time getPreviousAttributeValuesByName is called.
042: */
043: private Map previousAttributeValuesByName;
044:
045: /**
046: * The map of previous attributes, if they changed. If they did not change,
047: * then this value is <code>null</code>. The map's keys are the attribute
048: * names (strings), and its value are any object.
049: *
050: * This is the original map passed into the constructor. This object always
051: * returns a copy of this map, not the original. However the constructor of
052: * this object is called very frequently and the map is rarely requested,
053: * so we only copy the map the first time it is requested.
054: *
055: * @since 3.1
056: */
057: private final Map originalPreviousAttributeValuesByName;
058:
059: /**
060: * Creates a new instance of this class.
061: *
062: * @param handler
063: * the instance of the interface that changed.
064: * @param attributeValuesByNameChanged
065: * true, iff the attributeValuesByName property changed.
066: * @param previousAttributeValuesByName
067: * the map of previous attribute values by name. This map may be
068: * empty. If this map is not empty, it's collection of keys must
069: * only contain instances of <code>String</code>. This map
070: * must be <code>null</code> if attributeValuesByNameChanged is
071: * <code>false</code> and must not be null if
072: * attributeValuesByNameChanged is <code>true</code>.
073: */
074: public HandlerEvent(IHandler handler,
075: boolean attributeValuesByNameChanged,
076: Map previousAttributeValuesByName) {
077: if (handler == null) {
078: throw new NullPointerException();
079: }
080:
081: if (!attributeValuesByNameChanged
082: && previousAttributeValuesByName != null) {
083: throw new IllegalArgumentException();
084: }
085:
086: if (attributeValuesByNameChanged) {
087: this .originalPreviousAttributeValuesByName = previousAttributeValuesByName;
088: } else {
089: this .originalPreviousAttributeValuesByName = null;
090: }
091:
092: this .handler = handler;
093: this .attributeValuesByNameChanged = attributeValuesByNameChanged;
094: }
095:
096: /**
097: * Returns the instance of the interface that changed.
098: *
099: * @return the instance of the interface that changed. Guaranteed not to be
100: * <code>null</code>.
101: */
102: public IHandler getHandler() {
103: return handler;
104: }
105:
106: /**
107: * Returns the map of previous attribute values by name.
108: *
109: * @return the map of previous attribute values by name. This map may be
110: * empty. If this map is not empty, it's collection of keys is
111: * guaranteed to only contain instances of <code>String</code>.
112: * This map is guaranteed to be <code>null</code> if
113: * haveAttributeValuesByNameChanged() is <code>false</code> and is
114: * guaranteed to not be null if haveAttributeValuesByNameChanged()
115: * is <code>true</code>.
116: */
117: public Map getPreviousAttributeValuesByName() {
118: if (originalPreviousAttributeValuesByName == null) {
119: return null;
120: }
121:
122: if (previousAttributeValuesByName == null) {
123: previousAttributeValuesByName = Util.safeCopy(
124: originalPreviousAttributeValuesByName,
125: String.class, Object.class, false, true);
126: }
127:
128: return previousAttributeValuesByName;
129: }
130:
131: /**
132: * Returns whether or not the attributeValuesByName property changed.
133: *
134: * @return true, iff the attributeValuesByName property changed.
135: */
136: public boolean haveAttributeValuesByNameChanged() {
137: return attributeValuesByNameChanged;
138: }
139: }
|