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; + } +}