View Javadoc

1   package org.apache.continuum.buildmanager;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  import org.apache.continuum.taskqueue.BuildProjectTask;
23  import org.apache.continuum.taskqueue.CheckOutTask;
24  import org.apache.continuum.taskqueue.PrepareBuildProjectsTask;
25  import org.apache.continuum.utils.build.BuildTrigger;
26  import org.apache.maven.continuum.model.project.BuildDefinition;
27  import org.apache.maven.continuum.model.project.BuildQueue;
28  import org.apache.maven.continuum.model.project.Project;
29  import org.apache.maven.continuum.model.scm.ScmResult;
30  
31  import java.io.File;
32  import java.util.List;
33  import java.util.Map;
34  
35  /**
36   * BuildsManager. All builds whether forced or triggered will go through (or have to be added through) a builds manager.
37   *
38   * @author <a href="mailto:oching@apache.org">Maria Odea Ching</a>
39   */
40  public interface BuildsManager
41  {
42      /**
43       * Build projects using their corresponding build definitions. This method adds the group of projects to the
44       * build queue of the overall queue with the least amount of tasks queued.
45       *
46       * @param projects
47       * @param projectsBuildDefinitionsMap
48       * @param buildTrigger
49       * @param scmResultMap                TODO
50       * @param projectGroupId
51       * @throws BuildManagerException
52       */
53      void buildProjects( List<Project> projects, Map<Integer, BuildDefinition> projectsBuildDefinitionsMap,
54                          BuildTrigger buildTrigger, Map<Integer, ScmResult> scmResultMap, int projectGroupId )
55          throws BuildManagerException;
56  
57      /**
58       * Build the project using the specified build definition. Adds the project to the build queue of the overall queue with the
59       * least among of tasks queued. The overall queue is chosen from the pool of queues attached to the schedule of the
60       * build definition.
61       *
62       * @param projectId
63       * @param buildDefinition
64       * @param projectName
65       * @param buildTrigger
66       * @param scmResult       TODO
67       * @param projectGroupId
68       * @throws BuildManagerException
69       */
70      void buildProject( int projectId, BuildDefinition buildDefinition, String projectName, BuildTrigger buildTrigger,
71                         ScmResult scmResult, int projectGroupId )
72          throws BuildManagerException;
73  
74      /**
75       * Adds the projects in the prepare-build-queue.
76       *
77       * @param projectsBuildDefinitionsMap
78       * @param buildTrigger
79       * @param projectGroupId              TODO
80       * @param scmRootAddress              TODO
81       * @param scmRootId
82       * @throws BuildManagerException
83       */
84      void prepareBuildProjects( Map<Integer, Integer> projectsBuildDefinitionsMap, BuildTrigger buildTrigger,
85                                 int projectGroupId, String projectGroupName, String scmRootAddress, int scmRootId )
86          throws BuildManagerException;
87  
88      /**
89       * Adds the project to the checkout queue of the overall build queue with the least amount of tasks queued.
90       * The overall queue is chosen from the pool of queues attached to the schedule of the build definition.
91       *
92       * @param projectId
93       * @param projectName
94       * @param workingDirectory
95       * @param scmRootUrl             TODO
96       * @param scmUsername
97       * @param scmPassword
98       * @param defaultBuildDefinition
99       * @param subProjects            TODO
100      * @throws BuildManagerException
101      */
102     void checkoutProject( int projectId, String projectName, File workingDirectory, String scmRootUrl,
103                           String scmUsername, String scmPassword, BuildDefinition defaultBuildDefinition,
104                           List<Project> subProjects )
105         throws BuildManagerException;
106 
107     /**
108      * Cancels the specified project's build.
109      *
110      * @param projectId
111      * @return
112      * @throws BuildManagerException
113      */
114     boolean cancelBuild( int projectId )
115         throws BuildManagerException;
116 
117     /**
118      * Cancels all the builds in all the overall queues.
119      *
120      * @return
121      * @throws BuildManagerException
122      */
123     boolean cancelAllBuilds()
124         throws BuildManagerException;
125 
126     /**
127      * Cancels the current build on the specified overall queue.
128      *
129      * @param buildQueueId
130      * @return
131      * @throws BuildManagerException
132      */
133     boolean cancelBuildInQueue( int buildQueueId )
134         throws BuildManagerException;
135 
136     /**
137      * @param projectId
138      * @return
139      * @throws BuildManagerException
140      */
141     boolean cancelCheckout( int projectId )
142         throws BuildManagerException;
143 
144     /**
145      * @return
146      * @throws BuildManagerException
147      */
148     boolean cancelAllCheckouts()
149         throws BuildManagerException;
150 
151     // public boolean cancelPrepareBuild(int projectId) throws BuildManagerException;
152 
153     /**
154      * Cancels all the prepare builds in all overall queues
155      */
156     boolean cancelAllPrepareBuilds()
157         throws BuildManagerException;
158 
159     /**
160      * Cancels the specified project group prepare build
161      *
162      * @param projectGroupId
163      * @param scmRootId
164      * @return
165      * @throws BuildManagerException
166      */
167     boolean cancelPrepareBuild( int projectGroupId, int scmRootId )
168         throws BuildManagerException;
169 
170     /**
171      * Cancels the specified project prepare build
172      *
173      * @param projectId
174      * @return
175      * @throws BuildManagerException
176      */
177     boolean cancelPrepareBuild( int projectId )
178         throws BuildManagerException;
179 
180     /**
181      * Removes the project from the build queue.
182      *
183      * @param projectId
184      * @throws BuildManagerException
185      */
186     void removeProjectFromBuildQueue( int projectId )
187         throws BuildManagerException;
188 
189     /**
190      * Removes the project built using the specified build definition from the build queue.
191      *
192      * @param projectId
193      * @param buildDefinitionId
194      * @param buildTrigger
195      * @param projectName
196      * @param projectGroupId
197      * @throws BuildManagerException
198      */
199     void removeProjectFromBuildQueue( int projectId, int buildDefinitionId, BuildTrigger buildTrigger,
200                                       String projectName, int projectGroupId )
201         throws BuildManagerException;
202 
203     // TODO: should we throw an exception when one of the projects cannot be removed?
204 
205     /**
206      * Removes the specified projects from their build queues.
207      *
208      * @param projectIds
209      */
210     void removeProjectsFromBuildQueue( int[] projectIds );
211 
212     /**
213      * Removes a set of projects using the specified hashcodes from the build queues.
214      *
215      * @param hascodes
216      * @throws BuildManagerException
217      */
218     void removeProjectsFromBuildQueueWithHashcodes( int[] hascodes )
219         throws BuildManagerException;
220 
221     /**
222      * Removes the project from the checkout queue.
223      *
224      * @param projectId
225      * @throws BuildManagerException
226      */
227     void removeProjectFromCheckoutQueue( int projectId )
228         throws BuildManagerException;
229 
230     /**
231      * Removes the specified projects from their checkout queues.
232      *
233      * @param projectIds
234      */
235     void removeProjectsFromCheckoutQueue( int[] projectIds );
236 
237     /**
238      * Removes a set of projects using the specified hashcodes from the checkout queues.
239      *
240      * @param hashcodes
241      * @throws BuildManagerException
242      */
243     void removeProjectsFromCheckoutQueueWithHashcodes( int[] hashcodes )
244         throws BuildManagerException;
245 
246     boolean removeProjectGroupFromPrepareBuildQueue( int projectGroupId, String scmRootAddress )
247         throws BuildManagerException;
248 
249     /*void removeProjectFromPrepareBuildQueue( int projectId ) throws BuildManagerException;
250 
251 void removeProjectsFromPrepareBuildQueue( int[] projectIds ) throws BuildManagerException;*/
252 
253     /**
254      * Add an overall build queue.
255      *
256      * @param buildQueue
257      * @throws BuildManagerException TODO
258      */
259     void addOverallBuildQueue( BuildQueue buildQueue )
260         throws BuildManagerException;
261 
262     /**
263      * Remove an overall build queue.
264      *
265      * @param overallBuildQueueId
266      * @throws BuildManagerException
267      */
268     void removeOverallBuildQueue( int overallBuildQueueId )
269         throws BuildManagerException;
270 
271     /**
272      * Checks whether the project build is queued.
273      *
274      * @param projectId
275      * @return
276      * @throws BuildManagerException
277      */
278     boolean isInAnyBuildQueue( int projectId )
279         throws BuildManagerException;
280 
281     /**
282      * Checks whether the project build using the specified build definition is queued.
283      *
284      * @param projectId
285      * @param buildDefinitionId
286      * @return
287      * @throws BuildManagerException
288      */
289     boolean isInAnyBuildQueue( int projectId, int buildDefinitionId )
290         throws BuildManagerException;
291 
292     /**
293      * Checks whether the project checkout is already queued.
294      *
295      * @param projectId
296      * @return
297      * @throws BuildManagerException
298      */
299     boolean isInAnyCheckoutQueue( int projectId )
300         throws BuildManagerException;
301 
302     /**
303      * Checks if at least one of the projects is currently being checked out.
304      *
305      * @param projectIds
306      * @return
307      * @throws BuildManagerException
308      */
309     boolean isAnyProjectCurrentlyBeingCheckedOut( int[] projectIds )
310         throws BuildManagerException;
311 
312     /**
313      * Checks whether the project is already in the prepare-build queue.
314      *
315      * @param projectId
316      * @return
317      * @throws BuildManagerException
318      */
319     boolean isInPrepareBuildQueue( int projectId )
320         throws BuildManagerException;
321 
322     /**
323      * Checks where the project group is already in the prepare-build queue
324      *
325      * @param projectGroupId
326      * @param scmRootId
327      * @return
328      * @throws BuildManagerException
329      */
330     boolean isInPrepareBuildQueue( int projectGroupId, int scmRootId )
331         throws BuildManagerException;
332 
333     /**
334      * Checks whether the project is currently being built.
335      *
336      * @param projectId
337      * @return
338      * @throws BuildManagerException
339      */
340     boolean isProjectInAnyCurrentBuild( int projectId )
341         throws BuildManagerException;
342 
343     /**
344      * Checks if at least one of the projects is currently preparing build
345      *
346      * @param projectIds
347      * @return
348      * @throws BuildManagerException
349      */
350     boolean isAnyProjectCurrentlyPreparingBuild( int[] projectIds )
351         throws BuildManagerException;
352 
353     // needed in QueuesAction
354 
355     /**
356      * Returns all the build tasks currently being executed.
357      *
358      * @return
359      * @throws BuildManagerException
360      */
361     Map<String, BuildProjectTask> getCurrentBuilds()
362         throws BuildManagerException;
363 
364     /**
365      * Returns all the checkout tasks currently being executed.
366      *
367      * @return
368      * @throws BuildManagerException
369      */
370     Map<String, CheckOutTask> getCurrentCheckouts()
371         throws BuildManagerException;
372 
373     /**
374      * Returns all the overall build queues together with a list of the build tasks in it's build queue.
375      *
376      * @return
377      * @throws BuildManagerException
378      */
379     Map<String, List<BuildProjectTask>> getProjectsInBuildQueues()
380         throws BuildManagerException;
381 
382     /**
383      * Returns all the overall build queues together with a list of checkout tasks in it's checkout queue.
384      *
385      * @return
386      * @throws BuildManagerException
387      */
388     Map<String, List<CheckOutTask>> getProjectsInCheckoutQueues()
389         throws BuildManagerException;
390 
391     /**
392      * Checks whether a build is in progress.
393      *
394      * @return
395      */
396     boolean isBuildInProgress();
397 
398     /**
399      * Checks if at least one of the projects is currently building.
400      *
401      * @param projectIds
402      * @return
403      * @throws BuildManagerException
404      */
405     boolean isAnyProjectCurrentlyBuilding( int[] projectIds )
406         throws BuildManagerException;
407 
408     /**
409      * Checks whether project is currently being checked out.
410      *
411      * @param projectId
412      * @return
413      * @throws BuildManagerException
414      */
415     boolean isProjectCurrentlyBeingCheckedOut( int projectId )
416         throws BuildManagerException;
417 
418     /**
419      * Checks whether project is currently preparing build
420      *
421      * @param projectId
422      * @return
423      * @throws BuildManagerException
424      */
425     boolean isProjectCurrentlyPreparingBuild( int projectId )
426         throws BuildManagerException;
427 
428     /**
429      * Checks whether project group is currently preparing build
430      *
431      * @param projectGroupId
432      * @param scmRootId
433      * @return
434      * @throws BuildManagerException
435      */
436     boolean isProjectGroupCurrentlyPreparingBuild( int projectGroupId, int scmRootId )
437         throws BuildManagerException;
438 
439     /**
440      * Return currently preparing build project.
441      *
442      * @return
443      * @throws BuildManagerException
444      */
445     Map<String, PrepareBuildProjectsTask> getCurrentProjectInPrepareBuild()
446         throws BuildManagerException;
447 
448     /**
449      * Return all projects in prepare build queue.
450      *
451      * @return
452      * @throws BuildManagerException
453      */
454     Map<String, List<PrepareBuildProjectsTask>> getProjectsInPrepareBuildQueue()
455         throws BuildManagerException;
456 
457     /**
458      * Remove a project from a prepare build queue.
459      *
460      * @param projectGroupId
461      * @param scmRootId
462      * @return
463      * @throws BuildManagerException
464      */
465     boolean removeProjectFromPrepareBuildQueue( int projectGroupId, int scmRootId )
466         throws BuildManagerException;
467 
468     /**
469      * Removes a set of projects using the specified hashcodes from the prepare build queues.
470      *
471      * @param hashcodes
472      * @throws BuildManagerException
473      */
474     void removeProjectsFromPrepareBuildQueueWithHashCodes( int[] hashCodes )
475         throws BuildManagerException;
476 }