001: /*******************************************************************************
002: * Copyright (c) 2006, 2007 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.navigator;
011:
012: import java.util.HashMap;
013: import java.util.LinkedHashSet;
014: import java.util.Map;
015: import java.util.Set;
016:
017: import org.eclipse.jface.viewers.AbstractTreeViewer;
018:
019: /**
020: *
021: * A pipelined viewer update should map requests to refresh or update elements
022: * in the viewer to their correct, modified structure. Clients use
023: * {@link PipelinedViewerUpdate} as the input and return type from intercept
024: * methods on {@link IPipelinedTreeContentProvider}.
025: *
026: * <p>
027: * Clients should use the viewer update to describe how the request from the
028: * upstream extension (see {@link IPipelinedTreeContentProvider} for more
029: * information on <i>upstream</i> extensions) should be reshaped when applied
030: * to the tree. A request from an upstream extension to refresh a given element
031: * could result in multiple refresh requests from downstream extensions.
032: * Therefore, the refresh targets are modeled as a set.
033: * </p>
034: * <p>
035: * Initially, this set will contain the original element that was passed to the
036: * refresh requests. Clients may squash the refresh by clearing the set, change
037: * the original target by removing the current element and adding a new target,
038: * or expand the refresh by adding more elements to the set.
039: * </p>
040: * <p>
041: * A pipelined extension may receive a {@link PipelinedViewerUpdate} as the
042: * result of a call to {@link AbstractTreeViewer#refresh()}-methods or
043: * {@link AbstractTreeViewer#update(Object, String[])}-methods. The
044: * <code>properties</code> field is only applicable for <code>update()</code>
045: * calls and the <code>updateLabels</code> field is only applicable for
046: * <code>refresh()</code> calls.
047: * </p>
048: *
049: * @since 3.2
050: *
051: */
052: public final class PipelinedViewerUpdate {
053:
054: private static final String[] NO_PROPERTIES = new String[0];
055:
056: private final Set refreshTargets = new LinkedHashSet();
057:
058: private boolean updateLabels = false;
059:
060: private Map properties;
061:
062: /**
063: * Properties allow optimization for <code>update</code> calls.
064: *
065: * @param aTarget
066: * The target which may have specific properties associated with
067: * it for an optimized refresh.
068: *
069: * @return Returns the properties for the given target. If no properties are
070: * specified, then an empty array is returned. <b>null</b> will
071: * never be returned.
072: */
073: public final String[] getProperties(Object aTarget) {
074: if (properties != null && properties.containsKey(aTarget)) {
075: String[] props = (String[]) properties.get(aTarget);
076: return props != null ? props : NO_PROPERTIES;
077: }
078: return NO_PROPERTIES;
079: }
080:
081: /**
082: *
083: * Properties allow optimization for <code>update</code> calls.
084: *
085: * @param aTarget
086: * The target of the properties.
087: * @param theProperties
088: * The properties to pass along to the <code>update</code>
089: * call.
090: * @see AbstractTreeViewer#update(Object, String[])
091: */
092: public final void setProperties(Object aTarget,
093: String[] theProperties) {
094: if (theProperties != null && theProperties.length > 0) {
095: if (properties == null) {
096: properties = new HashMap();
097: }
098: properties.put(aTarget, theProperties);
099:
100: } else {
101: properties.remove(aTarget);
102: }
103:
104: if (properties.size() == 0) {
105: properties = null;
106: }
107:
108: }
109:
110: /**
111: * @return Returns the current set of refresh targets. Clients may add or
112: * remove directly to or from this set.
113: */
114: public final Set getRefreshTargets() {
115: return refreshTargets;
116: }
117:
118: /**
119: * @return Returns the true if the labels should also be updated during the
120: * <code>refresh</code>.
121: */
122: public final boolean isUpdateLabels() {
123: return updateLabels;
124: }
125:
126: /**
127: * @param toUpdateLabels
128: * True indicates that calls to <code>refresh</code> should
129: * force the update of the labels in addition to refreshing the
130: * structure.
131: */
132: public final void setUpdateLabels(boolean toUpdateLabels) {
133: updateLabels = toUpdateLabels;
134: }
135:
136: }
|