org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/workingsets/IWorkingSetConfiguration.java

   1 /*******************************************************************************
   2  * Copyright (c) 2009 QNX Software Systems 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  *     QNX Software Systems - initial API and implementation
  10  *******************************************************************************/
  11
  12 package org.eclipse.cdt.internal.ui.workingsets;
  13
  14 import java.util.Collection;
  15
  16 import org.eclipse.core.resources.IResource;
  17 import org.eclipse.core.runtime.IProgressMonitor;
  18 import org.eclipse.core.runtime.IStatus;
  19
  20 import org.eclipse.cdt.core.settings.model.ICConfigurationDescription;
  21
  22 /**
  23  * <p>
  24  * The protocol for working set configurations. A working set configuration specifies, at a minimum, a
  25  * {@linkplain ICConfigurationDescription build configuration} for each C/C++ project in the working set.
  26  * {@linkplain #activate() activating} the configuration applies these build configurations to the respective
  27  * projects as their active build configurations.
  28  * </p>
  29  * <p>
  30  * Implementations of this interface may choose to manage more configuration settings than are captured by the
  31  * active build configuration. They are, then, responsible for persistence, editing, and application of these
  32  * settings.
  33  * </p>
  34  * <p>
  35  * A working set configuration is considered to be {@linkplain #isActive() active} if all of the projects in
  36  * the working set are configured to build according to the configuration specified by the working set
  37  * configuration. It is an implementation detail (i.e., unspecified) what it means for a working set that has
  38  * recorded settings for projects that are not currently {@linkplain IResource#isAccessible() accessible} in
  39  * the workspace. However, for projects that are accessible and are included in the working set, but for which
  40  * the working set configuration has no settings, such projects are implicitly in the working set
  41  * configuration and it specifies their current configuration settings. Thus, in the extreme case, a
  42  * working-set configuration that includes none of the projects that currently are members of the working set,
  43  * is active.
  44  * </p>
  45  *
  46  * @noimplement This interface is not intended to be implemented by clients.
  47  * @noextend This interface is not intended to be extended by clients.
  48  *
  49  * @author Christian W. Damus (cdamus)
  50  *
  51  * @since 6.0
  52  */
  53 public interface IWorkingSetConfiguration extends IWorkingSetConfigurationElement {
  54         /**
  55          * Obtains the working set element that contains me.
  56          *
  57          * @return my working set
  58          */
  59         IWorkingSetProxy getWorkingSet();
  60
  61         /**
  62          * Queries my name.
  63          *
  64          * @return my name
  65          */
  66         String getName();
  67
  68         /**
  69          * Obtains the project configuration element for the specified project.
  70          *
  71          * @param projectName
  72          *            a project name
  73          *
  74          * @return that project's configuration element
  75          *
  76          * @throws IllegalArgumentException
  77          *             if the specified project is not a member of my working set
  78          *
  79          * @see #getProjectConfigurations()
  80          */
  81         IWorkingSetProjectConfiguration getProjectConfiguration(String projectName);
  82
  83         /**
  84          * Obtains the configuration elements for all of the projects in my working set. These include any
  85          * projects that were not in my working set when I was last updated, and does not include any projects
  86          * that were in my working set when I was last updated but that no longer are.
  87          *
  88          * @return my project configuration elements
  89          */
  90         Collection<IWorkingSetProjectConfiguration> getProjectConfigurations();
  91
  92         /**
  93          * Queries whether I am currently active in the workspace. I am active if and only if for every the
  94          * projects in my working set, its active configuration is the one that I specify for it. As a special
  95          * case, the configurations of an empty working set can never be active.
  96          *
  97          * @return whether I am currently active in the workspace
  98          *
  99          * @see #activate()
 100          */
 101         boolean isActive();
 102
 103         /**
 104          * Updates the workspace to set, for each project in my working set, the active configuration that I
 105          * specify for it. This method has no effect if I am already active.
 106          *
 107          * @see #isActive()
 108          */
 109         void activate();
 110
 111         /**
 112          * Builds my project configurations in the workspace.
 113          *
 114          * @param monitor
 115          *            for reporting progress of the working-set build
 116          * @return the aggregate status of the individual
 117          *         {@linkplain IWorkingSetProjectConfiguration#build(IProgressMonitor) project builds}
 118          */
 119         IStatus build(IProgressMonitor monitor);
 120
 121         /**
 122          * Creates a <i>snapshot</i> (also known as a "working copy") of myself, providing a mutable view suitable
 123          * for editing.
 124          *
 125          * @param workingSet
 126          *            my parent working set snapshot
 127          * @param workspace
 128          *            a workspace snapshot that captures the baseline state of the workspace and the working set
 129          *            configurations that are to be edited
 130          *
 131          * @return a working-copy snapshot of myself
 132          */
 133         ISnapshot createSnapshot(IWorkingSetProxy.ISnapshot workingSet, WorkspaceSnapshot workspace);
 134
 135         //
 136         // Nested types
 137         //
 138
 139         /**
 140          * The snapshot ("working copy") view of a working set configuration. It defines additional API for the
 141          * manipulation of working set configurations.
 142          *
 143          * @noimplement This interface is not intended to be implemented by clients.
 144          * @noextend This interface is not intended to be extended by clients.
 145          *
 146          * @author Christian W. Damus (cdamus)
 147          *
 148          * @since 6.0
 149          */
 150         interface ISnapshot extends IWorkingSetConfiguration, IWorkingSetConfigurationElement.ISnapshot {
 151                 IWorkingSetProxy.ISnapshot getWorkingSet();
 152
 153                 /**
 154                  * <p>
 155                  * Queries whether I am read-only. Read-only working set configurations are used for the special case
 156                  * of showing what is the active configuration of the projects in a working set when none of the named
 157                  * working set configurations is active. Thus, a working set that has no user-defined named
 158                  * configurations does, at least, have its read-only active configuration.
 159                  * </p>
 160                  * <p>
 161                  * A working set only ever has at most one read-only configuration, though it may have multiple active
 162                  * configurations if some of its configurations are equivalent.
 163                  * </p>
 164                  *
 165                  * @return whether I am the read-only active configuration of my working set
 166                  */
 167                 boolean isReadOnly();
 168
 169                 /**
 170                  * Sets my name, which must be unique amongst the configurations in my working set.
 171                  *
 172                  * @param name
 173                  *            my new, unique name
 174                  *
 175                  * @throws IllegalArgumentException
 176                  *             if the new name is <code>null</code> or empty, or if it is already used by another
 177                  *             configuration of the same working set
 178                  */
 179                 void setName(String name);
 180         }
 181 }