| /******************************************************************************* |
| * Copyright (c) 2008, 2011 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.wst.common.componentcore.internal.builder; |
| |
| import java.util.Set; |
| |
| import org.eclipse.core.resources.IProject; |
| import org.eclipse.core.resources.IResourceDeltaVisitor; |
| import org.eclipse.wst.common.componentcore.resources.IVirtualComponent; |
| |
| /** |
| * This graph provides a backward mapping of project component dependencies. It |
| * provides a project limited inverse of |
| * {@link IVirtualComponent#getReferences()}. |
| * |
| * <p>For example: |
| * <ul> |
| * <li>if the IVirtualComponent for project A has a dependency on the |
| * IVirtualComponent for project B, then calling |
| * {@link #getReferencingComponents(IProject)} on project B will return project |
| * A. </li> |
| * <li>if the IVirtualComponent for project A has a dependency on on the |
| * IVirtualComponent for a jar in project B, then calling |
| * {@link #getReferencingComponents(IProject)} for project B will return project |
| * A. This is true even if project B is not defined as an IVirtualComponent. |
| * </li> |
| * </ul> |
| * |
| * Any call to {@link #getReferencingComponents(IProject)} is always expected to |
| * be up to date. The only case where a client may need to force an update is if |
| * that client is also defining dynamic IVirtualComponent dependencies, i.e. the |
| * client is using the org.eclipse.wst.common.modulecore.componentimpl extension |
| * point. Only in this case should a client be calling any of |
| * {@link #preUpdate()}, {@link #postUpdate()}, or {@link #update(IProject)} |
| * |
| */ |
| public interface IDependencyGraph { |
| |
| /** |
| * Flag used by {@link #update(IProject, int)} to specify that something has been |
| * modified in a project which has changed the component dependencies. |
| */ |
| int MODIFIED = 0; |
| |
| /** |
| * Flag used by {@link #update(IProject, int)} to specify a project has been |
| * added or opened. This flag should be used as sparingly as possible |
| * because there are performance implications. |
| */ |
| int ADDED = 1; |
| |
| /** |
| * Flag used by {@link #update(IProject, int)} to specify a project has been |
| * removed or closed. |
| */ |
| int REMOVED = 2; |
| |
| /** |
| * The static instance of this graph. |
| */ |
| IDependencyGraph INSTANCE = DependencyGraphImpl.getInstance(); |
| |
| /** |
| * Returns the set of component projects referencing the specified target |
| * project. |
| * |
| * @param targetProject |
| * @return |
| */ |
| Set<IProject> getReferencingComponents(IProject targetProject); |
| |
| /** |
| * If <code>waitForAllUpdates</code> is <code>true</code> this method is |
| * equivalent to {@link #getReferencingComponents(IProject)}. Otherwise this |
| * method will return immediately without waiting for all updates to occur |
| * and potentially returning stale data. This a safer way to call |
| * getReferences to avoid deadlocks. If stale data is returned, then a |
| * subsequent on the same thread can be made, but there may be deadlock risk |
| * depending on what ISchedulingRule is currently held. A safer reaction |
| * to stale data would be to schedule another job to run in future to try again. |
| * |
| * @param targetProject |
| * @param waitForAllUpdates |
| * @return |
| */ |
| IDependencyGraphReferences getReferencingComponents(IProject targetProject, boolean waitForAllUpdates); |
| |
| /** |
| * Returns <code>true</code> if there are any pending updates. |
| * @return |
| */ |
| boolean isStale(); |
| |
| /** |
| * Returns a modification stamp. This modification stamp will be different |
| * if the project dependencies ever change. |
| */ |
| long getModStamp(); |
| |
| void addListener(IDependencyGraphListener listener); |
| |
| void removeListener(IDependencyGraphListener listener); |
| |
| /** |
| * WARNING: this should only be called by implementors of the |
| * org.eclipse.wst.common.modulecore.componentimpl extension point. |
| * |
| * <p>This method is part of the update API. |
| * |
| * @see {@link #update(IProject)} |
| */ |
| void preUpdate(); |
| |
| /** |
| * WARNING: this should only be called by implementors of the |
| * org.eclipse.wst.common.modulecore.componentimpl extension point. |
| * |
| * <p>This method is part of the update API. |
| * |
| * @see {@link #update(IProject)} |
| */ |
| void postUpdate(); |
| |
| /** |
| * @deprecated use {@link #update(IProject, int) using the #MODIFIED flag. |
| */ |
| void update(IProject sourceProject); |
| |
| /** |
| * WARNING: this should only be called by implementors of the |
| * org.eclipse.wst.common.modulecore.componentimpl extension point. |
| * |
| * <p>This method must be called when a resource change is detected which will |
| * affect how dependencies behave. For example, the core IVirtualComponent |
| * framework updates when changes are made to the |
| * .settings/org.eclipse.wst.common.component file changes, and also when |
| * IProjects are added or removed from the workspace. In the case for J2EE, |
| * this occurs when changes are made to the META-INF/MANIFEST.MF file. In |
| * general a call to update should only be made from a fast |
| * {@link IResourceDeltaVisitor}. |
| * |
| * <p>In order to improve efficiency and avoid unnecessary update processing, |
| * it is necessary to always proceed calls to update() with a call to |
| * preUpdate() and follow with a call to postUpdate() using a try finally |
| * block as follows: |
| * <pre> |
| * try { |
| * preUpdate(); |
| * // perform 0 or more update() calls here |
| * } finally { |
| * IDependencyGraph.INSTANCE.postUpdate(); |
| * } |
| * </pre> |
| * |
| * Valid updateType flags are {@link #MODIFIED}, {@link #ADDED}, and |
| * {@link #REMOVED} |
| * |
| */ |
| void update(IProject sourceProject, int updateType); |
| |
| } |