Bug 106346 Move ResourceMapping back to API package
diff --git a/bundles/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/RemoteResourceMappingContext.java b/bundles/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/RemoteResourceMappingContext.java
new file mode 100644
index 0000000..84bfe81
--- /dev/null
+++ b/bundles/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/RemoteResourceMappingContext.java
@@ -0,0 +1,163 @@
+/*******************************************************************************
+ * Copyright (c) 2005 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.core.resources.mapping;
+
+import org.eclipse.core.resources.*;
+import org.eclipse.core.runtime.CoreException;
+import org.eclipse.core.runtime.IProgressMonitor;
+
+/**
+ * A remote mapping context provides a model element with a view of the remote state
+ * of local resources as they relate to a repository operation that is in
+ * progress. A repository provider can pass an instance of this interface to a
+ * model element when obtaining a set of traversals for a model element. This
+ * allows the model element to query the remote state of a resource in order to
+ * determine if there are resources that exist remotely but do not exist locally
+ * that should be included in the traversal. The traversals should also be as
+ * as possible to allow for optimization of remote operations.
+ * <p>
+ * This class may be subclassed by clients.
+ * </p>
+ *
+ * @see ResourceMapping
+ * @see ResourceMappingContext
+ * @since 3.1
+ */
+public abstract class RemoteResourceMappingContext extends ResourceMappingContext {
+
+ /**
+ * Refresh flag constant (bit mask value 0) indicating that no
+ * additional refresh behavior is required.
+ */
+ public static final int NONE = 0;
+
+ /**
+ * Refresh flag constant (bit mask value 1) indicating that
+ * the mapping will be making use of the contents of the files
+ * covered by the traversals being refreshed.
+ */
+ public static final int FILE_CONTENTS_REQUIRED = 1;
+
+ /**
+ * Return whether the contents of the corresponding remote differs from the
+ * content of the local file in the context of the current operation. By this
+ * we mean that this method will return <code>true</code> if the remote contents differ
+ * from the local contents and these remote contents would be fetched as part of the
+ * operation associated with the context.
+ * For instance, when updating the workspace to the latest remote state,
+ * this method would only return <code>true</code> if the remote contentd have changed
+ * since the last time the contents where updated. However, if replace the local contents,
+ * the methdo would return <code>true</code> if either the remote contents or the lcoal contents
+ * have changed.
+ * <p>
+ * This can be used by clients to determine if
+ * they need to fetch the remote contents in order to determine if the
+ * resources that constitute the model element are different in another
+ * location. If the lcoa file exists and the remote file does not, then
+ * the contents will be said to differ (i.e. <code>true</code> is returned).
+ * </p>
+ *
+ * @param file the local file
+ * @param monitor a progress monitor, or <code>null</code> if progress
+ * reporting is not desired
+ * @return whether the contents of the corresponding remote differs from the
+ * content of the local file
+ * @exception CoreException if the contents could not be compared. Reasons include:
+ * <ul>
+ * <li>The corresponding remote resource is not a container
+ * (status code will be IResourceStatus.RESOURCE_WRONG_TYPE).</li>
+ * </ul>
+ */
+ public abstract boolean contentDiffers(IFile file, IProgressMonitor monitor) throws CoreException;
+
+ /**
+ * Returns an instance of IStorage in order to allow the
+ * caller to access the contents of the remote that corresponds to the given
+ * local resource. If the remote file does not exist, <code>null</code> is
+ * returned. The provided local file handle need not exist locally. A
+ * exception is thrown if the corresponding remote resource is not a file.
+ * <p>
+ * This method may be long running as a server may need to be contacted to
+ * obtain the contents of the file.
+ * </p>
+ *
+ * @param file the local file
+ * @param monitor a progress monitor, or <code>null</code> if progress
+ * reporting is not desired
+ * @return a storage that provides access to the contents of the local
+ * resource's corresponding remote resource. If the remote file
+ * does not exist, <code>null</code> is returned
+ * @exception CoreException if the contents could not be fetched. Reasons include:
+ * <ul>
+ * <li>The corresponding remote resource is not a container
+ * (status code will be IResourceStatus.RESOURCE_WRONG_TYPE).</li>
+ * </ul>
+ */
+ public abstract IStorage fetchContents(IFile file, IProgressMonitor monitor) throws CoreException;
+
+ /**
+ * Returns the list of member resources whose corresponding remote resources
+ * are members of the corresponding remote resource of the given local
+ * container. The container need not exist locally and the result may
+ * include entries that do not exist locally and may not include all local
+ * children. An empty list is returned if the remote resource which
+ * corresponds to the container is empty. A <code>null</code> is
+ * returned if the remote does not exist. An exception is thrown if the
+ * corresponding remote is not capable of having members.
+ * <p>
+ * This method may be long running as a server may need to be contacted to
+ * obtain the members of the containers corresponding remote resource.
+ * </p>
+ *
+ * @param container the local container
+ * @param monitor a progress monitor, or <code>null</code> if progress
+ * reporting is not desired
+ * @return a list of member resources whose corresponding remote resources
+ * are members of the remote counterpart of the given container or
+ * <code>null</code> if the remote does not exist.
+ * @exception CoreException if the members could not be fetched. Reasons include:
+ * <ul>
+ * <li>The corresponding remote resource is not a container
+ * (status code will be IResourceStatus.RESOURCE_WRONG_TYPE).</li>
+ * </ul>
+ */
+ public abstract IResource[] fetchMembers(IContainer container, IProgressMonitor monitor) throws CoreException;
+
+ /**
+ * Refresh the known remote state for any resources covered by the given traversals.
+ * Clients who require the latest remote state should invoke this method before
+ * invoking any others of the class. Mappings can use this method as a hint to the
+ * context provider of which resources will be required for the mapping to generate
+ * the proper set of traversals.
+ * <p>
+ * Note that this is really only a hint to the context provider.
+ * It is up to implementors to decide, based on the provided traversals, how to efficiently
+ * perform the refresh. In the ideal case, calls to {@link #contentDiffers} and {@link #fetchMembers}
+ * would not need to contact the server after a call to a refresh with appropriate traversals. Also, ideally,
+ * if {@link #FILE_CONTENTS_REQUIRED} is on of the flags, then the contents for these files will be chached as efficiently
+ * as possible so that calls to {@link #fetchContents} will also not need to contact the server. This may
+ * not be possible for all context providers, so clients cannot assume that the above mentioed methods will not
+ * be long running. It is still advisably for clients to call {@link #refresh} with as much details
+ * as possible since, in the case where a provider is optimized performance will be much better.
+ * </p>
+ *
+ * @param traversals the resource traversals which indicate which resources are to be refreshed
+ * @param flags additional refresh behavior. For instance, if <code>FILE_CONTENTS_REQUIRED</code>
+ * is one of the flags, this indicates that the client will be accessing the contents of
+ * the files covered by the traversals. <code>NONE</code> shoudl be used when no additional
+ * behavior is required
+ * @param monitor a progress monitor, or <code>null</code> if progress
+ * reporting is not desired
+ * @exception CoreException if the members could not be fetched.
+ */
+ public abstract void refresh(ResourceTraversal[] traversals, int flags, IProgressMonitor monitor) throws CoreException;
+
+}
diff --git a/bundles/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/ResourceMapping.java b/bundles/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/ResourceMapping.java
new file mode 100644
index 0000000..78ef64c
--- /dev/null
+++ b/bundles/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/ResourceMapping.java
@@ -0,0 +1,118 @@
+/*******************************************************************************
+ * Copyright (c) 2004, 2005 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.core.resources.mapping;
+
+import org.eclipse.core.resources.*;
+import org.eclipse.core.runtime.*;
+
+/**
+ * A resource mapping supports the transformation of an application model
+ * object into its underlying file system resources. It provides the
+ * bridge between a logical element and the physical resource(s) into which it
+ * is stored but does not provide more comprehensive model access or
+ * manipulations.
+ * <p>
+ * Mappings provide two means of model traversal. The {@link #accept} method
+ * can be used to visit the resources that constitute the model object. Alternatively,
+ * a set or traversals can be obtained by calling {@link #getTraversals}. A traversal
+ * contains a set of resources and a depth. This allows clients (such a repository providers)
+ * to do optimal traversals of the resources w.r.t. the operation that is being performed
+ * on the model object.
+ * </p>
+ * <p>
+ * This class may be subclassed by clients.
+ * </p>
+
+ * @see IResource
+ * @see ResourceTraversal
+ * @since 3.1
+ */
+public abstract class ResourceMapping extends PlatformObject {
+
+ /**
+ * Returns the application model element associated with this
+ * resource mapping.
+ *
+ * @return the application model element associated with this
+ * resource mapping.
+ */
+ public abstract Object getModelObject();
+
+ /**
+ * Returns the projects that contain the resources that constitute this
+ * application model.
+ *
+ * @return the projects
+ */
+ public abstract IProject[] getProjects();
+
+ /**
+ * Returns one or more traversals that can be used to access all the
+ * physical resources that constitute the logical resource. A traversal is
+ * simply a set of resources and the depth to which they are to be
+ * traversed. This method returns an array of traversals in order to provide
+ * flexibility in describing the traversals that constitute a model element.
+ * <p>
+ * Subclasses should, when possible, include
+ * all resources that are or may be members of the model element.
+ * For instance, a model element should return the same list of
+ * resources regardless of the existance of the files on the file system.
+ * For example, if a logical resource called "form" maps to "/p1/form.xml"
+ * and "/p1/form.java" then whether form.xml or form.java existed, they
+ * should be returned by this method.
+ *</p><p>
+ * In some cases, it may not be possible for a model element to know all the
+ * resources that may constitute the element without accessing the state of
+ * the model element in another location (e.g. a repository). This method is
+ * provided with a context which, when provided, gives access to
+ * the members of correcponding remote containers and the contenst of
+ * corresponding remote files. This gives the model element the opportunity
+ * to deduce what additional resources should be included in the traversal.
+ * </p>
+ *
+ * @param context gives access to the state of
+ * remote resources that correspond to local resources for the
+ * purpose of determining traversals that adequately cover the
+ * model element resources given the state of the model element
+ * in another location. This parameter may be <code>null</code>, in
+ * which case the implementor can assume that only the local
+ * resources are of interest to the client.
+ * @param monitor a progress monitor, or <code>null</code> if progress
+ * reporting is not desired
+ * @return a set of traversals that cover the resources that constitute the
+ * model element
+ * @exception CoreException if the traversals could not be obtained.
+ */
+ public abstract ResourceTraversal[] getTraversals(ResourceMappingContext context, IProgressMonitor monitor) throws CoreException;
+
+ /**
+ * Accepts the given visitor for the resources in this mapping.
+ * The visitor's {@link IResourceVisitor#visit} method is called for each resource
+ * in this mapping.
+ *
+ * @param context the traversal context
+ * @param visitor the visitor
+ * @param monitor a progress monitor, or <code>null</code> if progress
+ * reporting is not desired
+ * @exception CoreException if this method fails. Reasons include:
+ * <ul>
+ * <li> This resource does not exist.</li>
+ * <li> The visitor failed with this exception.</li>
+ * </ul>
+ */
+ public void accept(ResourceMappingContext context, IResourceVisitor visitor, IProgressMonitor monitor) throws CoreException {
+ ResourceTraversal[] traversals = getTraversals(context, monitor);
+ for (int i = 0; i < traversals.length; i++) {
+ ResourceTraversal traversal = traversals[i];
+ traversal.accept(visitor);
+ }
+ }
+}
diff --git a/bundles/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/ResourceMappingContext.java b/bundles/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/ResourceMappingContext.java
new file mode 100644
index 0000000..96363be
--- /dev/null
+++ b/bundles/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/ResourceMappingContext.java
@@ -0,0 +1,46 @@
+/*******************************************************************************
+ * Copyright (c) 2004, 2005 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.core.resources.mapping;
+
+
+/**
+ * A resource mapping context is provided to a resource mapping when traversing
+ * the resources of the mapping. The type of context may determine what resources
+ * are included in the traversals of a mapping.
+ * <p>
+ * There are currently two resource mapping contexts: the local mapping context
+ * (represented by the singleton {@link #LOCAL_CONTEXT}),
+ * and {@link RemoteResourceMappingContext}. Implementors of {@link ResourceMapping}
+ * should not assume that these are the only valid contexts (in order to allow future
+ * extensibility). Therefore, if the provided context is not of one of the above mentioed types,
+ * the implementor can assume that the context is a local context.
+ * </p>
+ * <p>
+ * This class may be subclassed by clients; this class is not intended to be
+ * instantiated directly.
+ * </p>
+ *
+ * @see ResourceMapping
+ * @see RemoteResourceMappingContext
+ * @since 3.1
+ */
+public class ResourceMappingContext {
+
+ /**
+ * This resource mapping context is used to indicate that the operation
+ * that is requesting the traversals is performing a local operation.
+ * Because the operation is local, the resource mapping is free to be
+ * as precise as desired about what resources make up the mapping without
+ * concern for performing optimized remote operations.
+ */
+ public static final ResourceMappingContext LOCAL_CONTEXT = new ResourceMappingContext();
+
+}
diff --git a/bundles/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/ResourceTraversal.java b/bundles/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/ResourceTraversal.java
new file mode 100644
index 0000000..c5cf73d
--- /dev/null
+++ b/bundles/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/ResourceTraversal.java
@@ -0,0 +1,122 @@
+/*******************************************************************************
+ * Copyright (c) 2004, 2005 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.core.resources.mapping;
+
+import org.eclipse.core.resources.IResource;
+import org.eclipse.core.resources.IResourceVisitor;
+import org.eclipse.core.runtime.CoreException;
+
+/**
+ * A resource traversal is simply a set of resources and the depth to which
+ * each is to be traversed. A set of traversals is used to describe the
+ * resources that constitute a model element.
+ * <p>
+ * The flags of the traversal indicate which special resources should be
+ * included or excluded from the traversal. The flags used are the same as
+ * those passed to the <code>IResource#accept(IResourceVisitor, int, int)</code> method.
+ *
+ * <p>
+ * This class may be instantiated or subclassed by clients.
+ * </p>
+
+ * @see org.eclipse.core.resources.IResource
+ * @since 3.1
+ */
+public class ResourceTraversal {
+
+ private int depth;
+ private int flags;
+ private IResource[] resources;
+
+ /**
+ * Creates a new resource traversal.
+ * @param resources The resources in the traversal
+ * @param depth The traversal depth
+ *
+ * @deprecated Use {@link #ResourceTraversal(IResource[], int, int)} instead.
+ */
+ public ResourceTraversal(IResource[] resources, int depth) {
+ this(resources, depth, 0);
+ }
+
+ /**
+ * Creates a new resource traversal.
+ * @param resources The resources in the traversal
+ * @param depth The traversal depth
+ * @param flags the flags for this traversal. The traversal flags match those
+ * that are passed to the <code>IResource#accept</code> method.
+ */
+ public ResourceTraversal(IResource[] resources, int depth, int flags) {
+ this.resources = resources;
+ this.depth = depth;
+ this.flags = flags;
+ }
+
+ /**
+ * Visit the resources of this traversal.
+ *
+ * @param visitor a resource visitor
+ * @exception CoreException if this method fails. Reasons include:
+ * <ul>
+ * <li> A resource in this traversal does not exist.</li>
+ * <li> The visitor failed with this exception.</li>
+ * </ul>
+ */
+ public void accept(IResourceVisitor visitor) throws CoreException {
+ for (int i = 0; i < resources.length; i++) {
+ IResource resource = resources[i];
+ resource.accept(visitor, depth, flags);
+ }
+ }
+
+ /**
+ * Returns the depth to which the resources should be traversed.
+ *
+ * @return the depth to which the physical resources are to be traversed
+ * (one of IResource.DEPTH_ZERO, IResource.DEPTH_ONE or
+ * IResource.DEPTH_INFINITE)
+ */
+ public int getDepth() {
+ return depth;
+ }
+
+ /**
+ * Return the flags for this traversal.
+ * The flags of the traversal indicate which special resources should be
+ * included or excluded from the traversal. The flags used are the same as
+ * those passed to the <code>IResource#accept(IResourceVisitor, int, int)</code> method.
+ * Clients who traverse the resources manually (i.e. without calling <code>accept</code>)
+ * should respect the flags when determining which resources are included
+ * in the traversal.
+ *
+ * @return the flags for this traversal
+ */
+ public int getFlags() {
+ return flags;
+ }
+
+ /**
+ * Returns the file system resource(s) for this traversal. The returned
+ * resources must be contained within the same project and need not exist in
+ * the local file system. The traversal of the returned resources should be
+ * done considering the flag returned by getDepth. If a resource returned by
+ * a traversal is a file, it should always be visited. If a resource of a
+ * traversal is a folder then files contained in the folder can only be
+ * visited if the folder is IResource.DEPTH_ONE or IResource.DEPTH_INFINITE.
+ * Child folders should only be visited if the depth is
+ * IResource.DEPTH_INFINITE.
+ *
+ * @return The resources in this traversal
+ */
+ public IResource[] getResources() {
+ return resources;
+ }
+}
