ProjectSetCapability


1   /*******************************************************************************
2    * Copyright (c) 2000, 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   *     Dan Rubel - project set serializer API
11   *******************************************************************************/
12  package org.eclipse.team.core;
13  
14  import java.io.File  ;
15  import java.net.URI  ;
16  import java.util.*;
17  
18  import org.eclipse.core.resources.IProject;
19  import org.eclipse.core.runtime.IProgressMonitor;
20  import org.eclipse.team.internal.core.Messages;
21  
22  /**
23   * An object for serializing and deserializing
24   * references to projects.  Given a project, it can produce a
25   * UTF-8 encoded String which can be stored in a file.
26   * Given this String, it can load a project into the workspace.
27   * It also provides a mechanism
28   * by which repository providers can be notified when a project set is created and exported.
29   * 
30   * @see RepositoryProviderType
31   * 
32   * @since 2.1
33   */
34  public abstract class ProjectSetCapability {
35      
36      /**
37       * Ensure that the provider type is backwards compatible by
38       * passing the project set serializer to the type if a serializer
39       * is registered. This is required for repository providers
40       * who implemented a project set capability in 2.1 (before the
41       * capability contained the serialization API) and have not
42       * released a 3.0 plugin yet. This method is
43       * called before project set export and import and can be used by
44       * other clients who work with project sets.
45       * 
46       * @param type the provider type instance
47       * @param capability the capability that was obtained from the provider type
48       * 
49       * @since 3.0
50       */
51      public static void ensureBackwardsCompatible(RepositoryProviderType type, ProjectSetCapability capability) {
52          if (capability != null) {
53              IProjectSetSerializer oldSerializer = Team.getProjectSetSerializer(type.getID());
54              if (oldSerializer != null) {
55                  capability.setSerializer(oldSerializer);
56              }
57          }
58      }
59      
60      /**
61       * The old serialization interface
62       */
63      private IProjectSetSerializer serializer;
64      
65      /**
66       * Notify the provider that a project set has been created at path. Only
67       * providers identified as having projects in the project set will be
68       * notified. The project set may or may not be created in a workspace
69       * project (thus may not be a resource).
70       * 
71       * @param file the project set file that was created
72       * @param context a UI context object. This object will either be a 
73       *                 com.ibm.swt.widgets.Shell or it will be null.
74       * @param monitor a progress monitor
75       * 
76       * @deprecated should use or override 
77       * projectSetCreated(File, ProjectSetSerializationContext, IProgressMonitor)
78       * instead
79       */
80      public void projectSetCreated(File   file, Object   context, IProgressMonitor monitor) {
81          //default is to do nothing
82      }
83      
84      /**
85       * Notify the provider that a project set has been created at path. Only
86       * providers identified as having projects in the project set will be
87       * notified. The project set may or may not be created in a workspace
88       * project (thus may not be a resource).
89       * 
90       * @param file the project set file that was created
91       * @param context
92       *      the context in which the references are created
93       *      (not <code>null</code>)
94       * @param monitor a progress monitor
95       * 
96       * @since 3.0
97       */
98      public void projectSetCreated(File   file, ProjectSetSerializationContext context, IProgressMonitor monitor) {
99          // Invoke old method by default
100         projectSetCreated(file, context.getShell(), monitor);
101     }
102     
103     /**
104      * For every project in providerProjects, return an opaque
105      * UTF-8 encoded String to act as a reference to that project.
106      * The format of the String is specific to the provider.
107      * The format of the String must be such that
108      * {@link #addToWorkspace(String[], ProjectSetSerializationContext, IProgressMonitor)}
109      * will be able to consume it and load the corresponding project.
110      * <p>
111      * This default implementation simply throws an exception
112      * indicating that no references can be created unless there 
113      * is an IProjectSetSerializer registered for the repository
114      * provider type in which case the operation is delegated to the 
115      * serializer.
116      * Subclasses are expected to override.
117      * 
118      * @since 3.0
119      * 
120      * @param providerProjects
121      *      an array of projects for which references are needed
122      *      (not <code>null</code> and contains no <code>null</code>s)
123      * @param context
124      *      the context in which the references are created
125      *      (not <code>null</code>)
126      * @param monitor
127      *      a progress monitor or <code>null</code> if none
128      * @return 
129      *      an array containing exactly the same number of elements 
130      *      as the providerProjects argument 
131      *      where each element is a serialized reference string 
132      *      uniquely identifying the corresponding the project in the providerProjects array
133      *      (not <code>null</code> and contains no <code>null</code>s)
134      * @throws TeamException
135      *      thrown if there is a reference string cannot be created for a project
136      */
137     public String  [] asReference(
138         IProject[] providerProjects,
139         ProjectSetSerializationContext context,
140         IProgressMonitor monitor)
141         throws TeamException {
142         
143         if (serializer != null) {
144             return serializer.asReference(providerProjects, context.getShell(), monitor);
145         }
146         throw new TeamException(Messages.ProjectSetCapability_0); 
147     }
148 
149     /**
150      * For every String in referenceStrings, load the corresponding project into the workspace.
151      * The opaque strings in referenceStrings are guaranteed to have been previously
152      * produced by {@link #asReference(IProject[], ProjectSetSerializationContext, IProgressMonitor)}.
153      * The confirmOverwrite method is called with an array of projects
154      * for which projects of the same name already exists in the workspace.
155      * <p>
156      * Callers from within a UI context should wrapper a call to this method
157      * inside a WorkspaceModifyOperation so that events generated as a result
158      * of this operation are deferred until the outermost operation
159      * has successfully completed.
160      * <p>
161      * This default implementation simply throws an exception
162      * indicating that no projects can be loaded unless there 
163      * is an IProjectSetSerializer registered for the repository
164      * provider type in which case the operation is delegated to the 
165      * serializer.
166      * Subclasses are expected to override.
167      * 
168      * @since 3.0
169      * 
170      * @param referenceStrings
171      *      an array of reference strings uniquely identifying the projects
172      *      (not <code>null</code> and contains no <code>null</code>s)
173      * @param context
174      *      the context in which the projects are loaded
175      *      (not <code>null</code>)
176      * @param monitor
177      *      a progress monitor or <code>null</code> if none
178      * @return IProject[]
179      *      an array of projects that were loaded
180      *      excluding those projects already existing and not overwritten
181      *      (not <code>null</code>, contains no <code>null</code>s)
182      * @throws TeamException
183      *      thrown if there is a problem loading a project into the workspace.
184      *      If an exception is thrown, then the workspace is left in an unspecified state
185      *      where some of the referenced projects may be loaded or partially loaded, and others may not.
186      */
187     public IProject[] addToWorkspace(
188         String  [] referenceStrings,
189         ProjectSetSerializationContext context,
190         IProgressMonitor monitor)
191         throws TeamException {
192         
193         if (serializer != null) {
194             return serializer.addToWorkspace(referenceStrings, context.getFilename(), context.getShell(), monitor);
195         }
196         throw new TeamException(Messages.ProjectSetCapability_1); 
197     }
198     
199     ////////////////////////////////////////////////////////////////////////////
200     //
201     // Internal utility methods for subclasses
202     //
203     ////////////////////////////////////////////////////////////////////////////
204 
205     /**
206      * Determine if any of the projects already exist
207      * and confirm which of those projects are to be overwritten.
208      * 
209      * @since 3.0
210      * 
211      * @param context
212      *      the context in which the projects are loaded
213      *      (not <code>null</code>)
214      * @param projects 
215      *      an array of proposed projects to be loaded
216      *      (not <code>null</code>, contains no <code>null</code>s)
217      * @return 
218      *      an array of confirmed projects to be loaded
219      *      or <code>null</code> if the operation is to be canceled.
220      * @throws TeamException
221      */
222     protected IProject[] confirmOverwrite(
223         ProjectSetSerializationContext context,
224         IProject[] projects)
225         throws TeamException {
226         
227         // Build a collection of existing projects
228         
229         final Collection existingProjects = new ArrayList();
230         for (int i = 0; i < projects.length; i++) {
231             IProject eachProj = projects[i];
232             if (eachProj.exists()) {
233                 existingProjects.add(eachProj);
234             } else if (new File  (eachProj.getParent().getLocation().toFile(), eachProj.getName()).exists()) {
235                 existingProjects.add(eachProj);
236             }
237         }
238         if (existingProjects.size() == 0)
239             return projects;
240         
241         // Confirm the overwrite
242         
243         IProject[] confirmed =
244             context.confirmOverwrite(
245                 (IProject[]) existingProjects.toArray(
246                     new IProject[existingProjects.size()]));
247         if (confirmed == null)
248             return null;
249         if (existingProjects.size() == confirmed.length)
250             return projects;
251         
252         // Return the amended list of projects to be loaded
253         
254         Collection result = new ArrayList(projects.length);
255         result.addAll(Arrays.asList(projects));
256         result.removeAll(existingProjects);
257         for (int i = 0; i < confirmed.length; i++) {
258             IProject eachProj = confirmed[i];
259             if (existingProjects.contains(eachProj))
260                 result.add(eachProj);
261         }
262         return (IProject[]) result.toArray(new IProject[result.size()]);
263     }
264     
265     /*
266      * Set the serializer to the one registered. The serializer
267      * will be used if subclasses do not override asReference
268      * and addToWorkspace
269      */
270     void setSerializer(IProjectSetSerializer serializer) {
271         this.serializer = serializer;
272     }
273     
274     /**
275      * Return the URI for the given reference string or <code>null</code>
276      * if this capability does not support file system schemes as defined by
277      * the <code>org.eclipse.core.filesystem.filesystems</code> extension 
278      * point.
279      * @see #getProject(String)
280      * @param referenceString a reference string obtained from 
281      * {@link #asReference(IProject[], ProjectSetSerializationContext, IProgressMonitor)}
282      * @return the URI for the given reference string or <code>null</code>
283      * @since 3.2
284      */
285     public URI   getURI(String   referenceString) {
286         return null;
287     }
288     
289     /**
290      * Return the name of the project that is the target of the given
291      * reference string or <code>null</code> if this capability does not
292      * support parsing of reference strings.
293      * @see #getURI(String)
294      * @param referenceString  reference string obtained from 
295      * {@link #asReference(IProject[], ProjectSetSerializationContext, IProgressMonitor)}
296      * @return  the name of the project that is the target of the given
297      * reference string or <code>null</code>
298      * @since 3.2
299      */
300     public String   getProject(String   referenceString) {
301         return null;
302     }
303     
304     /**
305      * Convert the given URI and projectName to a reference string that can be
306      * passed to the {@link #addToWorkspace(String[], ProjectSetSerializationContext, IProgressMonitor)}
307      * method. The scheme of the provided URI must match the scheme of the
308      * repository provider type from which this capability was obtained.
309      * @param uri the uri that identifies the location of the project in the repository.
310      * @param projectName the name of the project.
311      * @return the reference string representing a project that can be loaded into the workspace
312      * or <code>null</code> if the URI and name cannot be translated into a reference string
313      * @since 3.2
314      */
315     public String   asReference(URI   uri, String   projectName) {
316         return null;
317     }
318 }
319
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags