KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > internal > resources > mapping > ResourceMapping


1 /*******************************************************************************
2  * Copyright (c) 2004, 2005 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.internal.resources.mapping;
12
13 import org.eclipse.core.resources.*;
14 import org.eclipse.core.runtime.*;
15
16 /**
17  * A resource mapping supports the transformation of an application model
18  * object into its underlying file system resources. It provides the
19  * bridge between a logical element and the physical resource(s) into which it
20  * is stored but does not provide more comprehensive model access or
21  * manipulations.
22  * <p>
23  * Mappings provide two means of model traversal. The {@link #accept} method
24  * can be used to visit the resources that constitute the model object. Alternatively,
25  * a set or traversals can be obtained by calling {@link #getTraversals}. A traversal
26  * contains a set of resources and a depth. This allows clients (such a repository providers)
27  * to do optimal traversals of the resources w.r.t. the operation that is being performed
28  * on the model object.
29  * </p>
30  * <p>
31  * This class may be subclassed by clients.
32  * </p>
33
34  * @see IResource
35  * @see ResourceTraversal
36  * @since 3.1
37  */
38 public abstract class ResourceMapping extends PlatformObject {
39
40     /**
41      * Returns the application model element associated with this
42      * resource mapping.
43      *
44      * @return the application model element associated with this
45      * resource mapping.
46      */
47     public abstract Object JavaDoc getModelObject();
48
49     /**
50      * Returns the projects that contain the resources that constitute this
51      * application model.
52      *
53      * @return the projects
54      */
55     public abstract IProject[] getProjects();
56
57     /**
58      * Returns one or more traversals that can be used to access all the
59      * physical resources that constitute the logical resource. A traversal is
60      * simply a set of resources and the depth to which they are to be
61      * traversed. This method returns an array of traversals in order to provide
62      * flexibility in describing the traversals that constitute a model element.
63      * <p>
64      * Subclasses should, when possible, include
65      * all resources that are or may be members of the model element.
66      * For instance, a model element should return the same list of
67      * resources regardless of the existance of the files on the file system.
68      * For example, if a logical resource called "form" maps to "/p1/form.xml"
69      * and "/p1/form.java" then whether form.xml or form.java existed, they
70      * should be returned by this method.
71      *</p><p>
72      * In some cases, it may not be possible for a model element to know all the
73      * resources that may constitute the element without accessing the state of
74      * the model element in another location (e.g. a repository). This method is
75      * provided with a context which, when provided, gives access to
76      * the members of correcponding remote containers and the contenst of
77      * corresponding remote files. This gives the model element the opportunity
78      * to deduce what additional resources should be included in the traversal.
79      * </p>
80      *
81      * @param context gives access to the state of
82      * remote resources that correspond to local resources for the
83      * purpose of determining traversals that adequately cover the
84      * model element resources given the state of the model element
85      * in another location. This parameter may be <code>null</code>, in
86      * which case the implementor can assume that only the local
87      * resources are of interest to the client.
88      * @param monitor a progress monitor, or <code>null</code> if progress
89      * reporting is not desired
90      * @return a set of traversals that cover the resources that constitute the
91      * model element
92      * @exception CoreException if the traversals could not be obtained.
93      */
94     public abstract ResourceTraversal[] getTraversals(ResourceMappingContext context, IProgressMonitor monitor) throws CoreException;
95
96     /**
97      * Accepts the given visitor for the resources in this mapping.
98      * The visitor's {@link IResourceVisitor#visit} method is called for each resource
99      * in this mapping.
100      *
101      * @param context the traversal context
102      * @param visitor the visitor
103      * @param monitor a progress monitor, or <code>null</code> if progress
104      * reporting is not desired
105      * @exception CoreException if this method fails. Reasons include:
106      * <ul>
107      * <li> This resource does not exist.</li>
108      * <li> The visitor failed with this exception.</li>
109      * </ul>
110      */
111     public void accept(ResourceMappingContext context, IResourceVisitor visitor, IProgressMonitor monitor) throws CoreException {
112         ResourceTraversal[] traversals = getTraversals(context, monitor);
113         for (int i = 0; i < traversals.length; i++) {
114             ResourceTraversal traversal = traversals[i];
115             traversal.accept(visitor);
116         }
117     }
118 }
119
Popular Tags