001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.netbeans.spi.project;
043:
044: import java.beans.PropertyChangeListener;
045: import java.io.IOException;
046: import java.util.Collection;
047:
048: /**
049: * Provider of configurations for a project.
050: * Should be registered in a project's {@link org.netbeans.api.project.Project#getLookup lookup}.
051: * Besides the implementor, only the project UI infrastructure is expected to use this class.
052: * @param C the type of configuration created by this provider
053: *
054: * @author Adam Sotona, Jesse Glick
055: * @since org.netbeans.modules.projectapi/1 1.11
056: * @see <a href="http://projects.netbeans.org/nonav/buildsys/configurations.html">Project Configurations design document</a>
057: */
058: public interface ProjectConfigurationProvider<C extends ProjectConfiguration> {
059:
060: /**
061: * Property name for the active configuration.
062: * Use it when firing a change in the active configuration.
063: */
064: String PROP_CONFIGURATION_ACTIVE = "activeConfiguration"; // NOI18N
065:
066: /**
067: * Property name of the set of configurations.
068: * Use it when firing a change in the set of configurations.
069: */
070: String PROP_CONFIGURATIONS = "configurations"; // NOI18N
071:
072: /**
073: * Gets a list of configurations.
074: * Permitted to return different instances from one invocation to the next
075: * but it is advisable for the "same" instances to compare as equal.
076: * <p>Should be called within {@link org.netbeans.api.project.ProjectManager#mutex read access}.
077: * @return all available configurations for this project
078: */
079: Collection<C> getConfigurations();
080:
081: /**
082: * Gets the currently active configuration.
083: * <p>Should be called within {@link org.netbeans.api.project.ProjectManager#mutex read access}.
084: * @return the active configuration for this project (should be a member of {@link #getConfigurations}, or null only if that is empty)
085: */
086: C getActiveConfiguration();
087:
088: /**
089: * Sets the active configuration.
090: * Should fire a change in {@link #PROP_CONFIGURATION_ACTIVE}.
091: * It should be true afterwards that <code>configuration.equals(getActiveConfiguration())</code>
092: * though it might not be true that <code>configuration == getActiveConfiguration()</code>.
093: * <p class="nonnormative">
094: * If possible, the choice of configuration should be persisted for the next IDE session.
095: * If applicable, the persisted choice should be kept in per-user settings, not shared or versioned.
096: * </p>
097: * <p>Should be called within {@link org.netbeans.api.project.ProjectManager#mutex write access}.
098: * @param configuration new active configuration
099: * @throws IllegalArgumentException if the requested configuration is not a member of {@link #getConfigurations}
100: * @throws IOException if storing the configuration change failed
101: */
102: void setActiveConfiguration(C configuration)
103: throws IllegalArgumentException, IOException;
104:
105: /**
106: * Checks if this project can provide a GUI customizer for its configurations.
107: * @return true if {@link #customize} may be called
108: */
109: boolean hasCustomizer();
110:
111: /**
112: * Customize this project's configurations.
113: * Only permitted if {@link #hasCustomizer} is true.
114: * May, for example, open the project properties dialog.
115: */
116: void customize();
117:
118: /**
119: * Indicates if a project action is affected by the choice of configuration.
120: * If so, a GUI for this action is permitted to show a list of configurations and
121: * let the user select a configuration to apply to one action invocation only.
122: * Such a GUI can avoid the need to first select an active configuration and
123: * then run the action as two steps.
124: * This is done by including a {@link ProjectConfiguration} in the context passed
125: * to {@link ActionProvider#invokeAction}.
126: * A project is free to return <code>false</code> even if the configuration
127: * <em>might</em> affect the behavior of the action, if it simply does not
128: * wish for such a GUI to be shown.
129: * <p class="nonnormative">
130: * The likely values of <code>command</code> are those actions
131: * normally shown in the IDE's tool bar with main project bindings:
132: * {@link ActionProvider#COMMAND_BUILD}, {@link ActionProvider#COMMAND_REBUILD},
133: * {@link ActionProvider#COMMAND_RUN}, and {@link ActionProvider#COMMAND_DEBUG}.
134: * </p>
135: * @param command one of {@link ActionProvider#getSupportedActions}
136: * @return true if the named command refers to an action affected by configurations
137: */
138: boolean configurationsAffectAction(String command);
139:
140: /**
141: * Adds a listener to check for changes in {@link #PROP_CONFIGURATION_ACTIVE} or {@link #PROP_CONFIGURATIONS}.
142: * @param lst a listener to add
143: */
144: void addPropertyChangeListener(PropertyChangeListener lst);
145:
146: /**
147: * Removes a listener.
148: * @param lst a listener to remove
149: */
150: void removePropertyChangeListener(PropertyChangeListener lst);
151:
152: }
|