org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/workingsets/IWorkingSetProjectConfiguration.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.IProject;
  17 import org.eclipse.core.resources.IResource;
  18 import org.eclipse.core.runtime.IProgressMonitor;
  19 import org.eclipse.core.runtime.IStatus;
  20
  21 import org.eclipse.cdt.core.settings.model.ICConfigurationDescription;
  22
  23 /**
  24  * <p>
  25  * The protocol for project configurations in a working set configuration. At a minimum, the project
  26  * configuration specifies which build configuration is {@linkplain #getSelectedConfigurationID() selected} to
  27  * be set as the project's active configuration. Implementations are free to add more configuration
  28  * information than the selected build configuration.
  29  * </p>
  30  * <p>
  31  * Note that project configurations are owned by working set configurations. Thus, different configurations of
  32  * the same (or different) working set may specify different settings for the same project.
  33  * </p>
  34  *
  35  * @author Christian W. Damus (cdamus)
  36  *
  37  * @since 6.0
  38  */
  39 public interface IWorkingSetProjectConfiguration extends IWorkingSetConfigurationElement {
  40         /**
  41          * Obtains the working set configuration element that owns me.
  42          *
  43          * @return my working set configuration
  44          */
  45         IWorkingSetConfiguration getWorkingSetConfiguration();
  46
  47         /**
  48          * Queries the name of the project that I configure.
  49          *
  50          * @return my project name
  51          */
  52         String getProjectName();
  53
  54         /**
  55          * Resolves my project name to the actual project resource in the workspace.
  56          *
  57          * @return my referenced project, or <code>null</code> if the project is not
  58          *         {@linkplain IResource#isAccessible() accessible} in the workspace
  59          */
  60         IProject resolveProject();
  61
  62         /**
  63          * Queries the ID of the build configuration that is currently selected for my project.
  64          *
  65          * @return my selected build configuration ID
  66          */
  67         String getSelectedConfigurationID();
  68
  69         /**
  70          * <p>
  71          * Resolves my selected configuration reference to the C model's description handle for it.
  72          * </p>
  73          * <p>
  74          * <b>Note</b> that, in the general case, it is possible for the configuration to resolve to a different
  75          * object from one call to the next, but always representing the same configuration. However, in the case
  76          * of a working-copy {@linkplain IWorkingSetProjectConfiguration.ISnapshot snapshot} of me, the result
  77          * will always be the same object.
  78          * </p>
  79          *
  80          * @return the C model representation of my selected build configuration
  81          *
  82          * @see #resolveConfigurations()
  83          */
  84         ICConfigurationDescription resolveSelectedConfiguration();
  85
  86         /**
  87          * <p>
  88          * Resolves the set of available configurations of my project.
  89          * </p>
  90          * <p>
  91          * <b>Note</b> that, in the general case, it is possible for these configurations to resolve to different
  92          * objects from one call to the next, but always representing the same configurations. However, in the
  93          * case of a working-copy {@linkplain IWorkingSetProjectConfiguration.ISnapshot snapshot} of me, the
  94          * results will always be the same objects.
  95          * </p>
  96          *
  97          * @return the C model representation of my selected available build configurations
  98          *
  99          * @see #resolveSelectedConfiguration()
 100          */
 101         Collection<ICConfigurationDescription> resolveConfigurations();
 102
 103         /**
 104          * Queries whether my project currently has my selected configuration active in the workspace.
 105          *
 106          * @return whether I am my project's active configuration
 107          *
 108          * @see #getSelectedConfigurationID()
 109          * @see #activate()
 110          */
 111         boolean isActive();
 112
 113         /**
 114          * Activates my selected configuration in the workspace, for my project.
 115          *
 116          * @see #getSelectedConfigurationID()
 117          * @see ISnapshot#setSelectedConfigurationID(String)
 118          * @see #isActive()
 119          */
 120         void activate();
 121
 122         /**
 123          * Builds my selected configuration in the workspace, for my project. If building the configuration
 124          * actually requires activating it, and it was not already active, then it would be a good idea to return
 125          * a warning status indicating that the active configuration had to be changed in order to effect the
 126          * build.
 127          *
 128          * @param monitor
 129          *            a progress monitor to report build progress
 130          * @return a status indicating any error or warning conditions in the invocation of the build
 131          */
 132         IStatus build(IProgressMonitor monitor);
 133
 134         /**
 135          * Creates a <i>snapshot</i> (also known as a "working copy") of myself, providing a mutable view suitable
 136          * for editing.
 137          *
 138          * @param workingSetConfig
 139          *            my parent working set configuration snapshot
 140          * @param workspace
 141          *            a workspace snapshot that captures the baseline state of the workspace and the working set
 142          *            configurations that are to be edited
 143          *
 144          * @return a working-copy snapshot of myself
 145          */
 146         ISnapshot createSnapshot(IWorkingSetConfiguration.ISnapshot workingSetConfig, WorkspaceSnapshot workspace);
 147
 148         //
 149         // Nested types
 150         //
 151
 152         /**
 153          * The snapshot ("working copy") view of a working set project configuration.
 154          *
 155          * @author Christian W. Damus (cdamus)
 156          *
 157          * @since 6.0
 158          */
 159         interface ISnapshot extends IWorkingSetProjectConfiguration, IWorkingSetConfigurationElement.ISnapshot {
 160                 IWorkingSetConfiguration.ISnapshot getWorkingSetConfiguration();
 161
 162                 /**
 163                  * Sets the ID of the build configuration that is currently selected for my project.
 164                  *
 165                  * @param id
 166                  *            my selected build configuration ID
 167                  */
 168                 void setSelectedConfigurationID(String id);
 169         }
 170 }