ResourceMapping


1   /*******************************************************************************
2    * Copyright (c) 2004, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    * 
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.core.resources.mapping;
12  
13  import java.util.ArrayList  ;
14  import org.eclipse.core.internal.resources.mapping.ModelProviderManager;
15  import org.eclipse.core.resources.*;
16  import org.eclipse.core.runtime.*;
17  
18  /**
19   * A resource mapping supports the transformation of an application model 
20   * object into its underlying file system resources. It provides the
21   * bridge between a logical element and the physical resource(s) into which it
22   * is stored but does not provide more comprehensive model access or
23   * manipulations.
24   * <p>
25   * Mappings provide two means of model traversal. The {@link #accept} method
26   * can be used to visit the resources that constitute the model object. Alternatively,
27   * a set or traversals can be obtained by calling {@link #getTraversals}. A traversal
28   * contains a set of resources and a depth. This allows clients (such a repository providers)
29   * to do optimal traversals of the resources w.r.t. the operation that is being performed
30   * on the model object.
31   * </p>
32   * <p>
33   * This class may be subclassed by clients.
34   * </p>
35  
36   * @see IResource
37   * @see ResourceTraversal
38   * @since 3.2
39   */
40  public abstract class ResourceMapping extends PlatformObject {
41  
42      /**
43       * Accepts the given visitor for all existing resources in this mapping.
44       * The visitor's {@link IResourceVisitor#visit} method is called for each 
45       * accessible resource in this mapping. 
46       * 
47       * @param context the traversal context
48       * @param visitor the visitor
49       * @param monitor a progress monitor, or <code>null</code> if progress
50       *    reporting is not desired
51       * @exception CoreException if this method fails. Reasons include:
52       * <ul>
53       * <li> The visitor failed with this exception.</li>
54       * <li> The traversals for this mapping could not be obtained.</li>
55       * </ul>
56       */
57      public void accept(ResourceMappingContext context, IResourceVisitor visitor, IProgressMonitor monitor) throws CoreException {
58          ResourceTraversal[] traversals = getTraversals(context, monitor);
59          for (int i = 0; i < traversals.length; i++)
60              traversals[i].accept(visitor);
61      }
62  
63      /**
64       * Return whether this resource mapping contains all the resources
65       * of the given mapping.
66       * <p>
67       * This method always returns <code>false</code> when the given resource 
68       * mapping's model provider id does not match that the of the receiver.
69       * </p>
70       * 
71       * @param mapping the given resource mapping
72       * @return <code>true</code> if this mapping contains all the resources
73       * of the given mapping, and <code>false</code> otherwise.
74       */
75      public boolean contains(ResourceMapping mapping) {
76          return false;
77      }
78  
79      /**
80       * Override equals to compare the model objects of the
81       * mapping in order to determine equality.
82       * @param obj the object to compare
83       * @return <code>true</code> if the receiver is equal to the
84       * given object, and <code>false</code> otherwise.
85       */
86      public boolean equals(Object   obj) {
87          if (obj == this)
88              return true;
89          if (obj instanceof ResourceMapping) {
90              ResourceMapping other = (ResourceMapping) obj;
91              return other.getModelObject().equals(getModelObject());
92          }
93          return false;
94      }
95  
96      /**
97       * Returns all markers of the specified type on the resources in this mapping.
98       * If <code>includeSubtypes</code> is <code>false</code>, only markers 
99       * whose type exactly matches the given type are returned.  Returns an empty 
100      * array if there are no matching markers.
101      *
102      * @param type the type of marker to consider, or <code>null</code> to indicate all types
103      * @param includeSubtypes whether or not to consider sub-types of the given type
104      * @param monitor a progress monitor, or <code>null</code> if progress
105      *    reporting is not desired
106      * @return an array of markers
107      * @exception CoreException if this method fails.
108      */
109     public IMarker[] findMarkers(String   type, boolean includeSubtypes, IProgressMonitor monitor) throws CoreException {
110         final ResourceTraversal[] traversals = getTraversals(ResourceMappingContext.LOCAL_CONTEXT, monitor);
111         ArrayList   result = new ArrayList  ();
112         for (int i = 0; i < traversals.length; i++)
113             traversals[i].doFindMarkers(result, type, includeSubtypes);
114         return (IMarker[]) result.toArray(new IMarker[result.size()]);
115     }
116 
117     /**
118      * Returns the application model element associated with this
119      * resource mapping.
120      * 
121      * @return the application model element associated with this
122      * resource mapping.
123      */
124     public abstract Object   getModelObject();
125 
126     /**
127      * Return the model provider for the model object
128      * of this resource mapping. The model provider is obtained
129      * using the id returned from <code>getModelProviderId()</code>.
130      * @return the model provider
131      */
132     public final ModelProvider getModelProvider() {
133         try {
134             return ModelProviderManager.getDefault().getModelProvider(getModelProviderId());
135         } catch (CoreException e) {
136             throw new IllegalStateException  (e.getMessage());
137         }
138     }
139 
140     /**
141      * Returns the id of the model provider that generated this resource
142      * mapping.
143      * 
144      * @return the model provider id
145      */
146     public abstract String   getModelProviderId();
147 
148     /**
149      * Returns the projects that contain the resources that constitute this 
150      * application model.
151      * 
152      * @return the projects
153      */
154     public abstract IProject[] getProjects();
155 
156     /**
157      * Returns one or more traversals that can be used to access all the
158      * physical resources that constitute the logical resource. A traversal is
159      * simply a set of resources and the depth to which they are to be
160      * traversed. This method returns an array of traversals in order to provide
161      * flexibility in describing the traversals that constitute a model element.
162      * <p>
163      * Subclasses should, when possible, include
164      * all resources that are or may be members of the model element. 
165      * For instance, a model element should return the same list of
166      * resources regardless of the existence of the files on the file system.
167      * For example, if a logical resource called "form" maps to "/p1/form.xml"
168      * and "/p1/form.java" then whether form.xml or form.java existed, they
169      * should be returned by this method.
170      *</p><p>
171      * In some cases, it may not be possible for a model element to know all the
172      * resources that may constitute the element without accessing the state of
173      * the model element in another location (e.g. a repository). This method is
174      * provided with a context which, when provided, gives access to
175      * the members of corresponding remote containers and the contents of
176      * corresponding remote files. This gives the model element the opportunity
177      * to deduce what additional resources should be included in the traversal.
178      * </p>
179      * 
180      * @param context gives access to the state of
181      *            remote resources that correspond to local resources for the
182      *            purpose of determining traversals that adequately cover the
183      *            model element resources given the state of the model element
184      *            in another location. This parameter may be <code>null</code>, in
185      *            which case the implementor can assume that only the local
186      *            resources are of interest to the client.
187      * @param monitor a progress monitor, or <code>null</code> if progress
188      *    reporting is not desired
189      * @return a set of traversals that cover the resources that constitute the
190      *         model element
191      * @exception CoreException if the traversals could not be obtained.
192      */
193     public abstract ResourceTraversal[] getTraversals(ResourceMappingContext context, IProgressMonitor monitor) throws CoreException;
194     
195     /**
196      * Override hashCode to use the model object.
197      */
198     public int hashCode() {
199         return getModelObject().hashCode();
200     }
201 }
202
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags