ProjectConfigurationProvider


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  
20  package org.netbeans.spi.project;
21  
22  import java.beans.PropertyChangeListener  ;
23  import java.io.IOException  ;
24  import java.util.Collection  ;
25  
26  /**
27   * Provider of configurations for a project.
28   * Should be registered in a project's {@link org.netbeans.api.project.Project#getLookup lookup}.
29   * Besides the implementor, only the project UI infrastructure is expected to use this class.
30   * @param C the type of configuration created by this provider
31   *
32   * @author Adam Sotona, Jesse Glick
33   * @since org.netbeans.modules.projectapi/1 1.11
34   * @see <a HREF="http://projects.netbeans.org/nonav/buildsys/configurations.html">Project Configurations design document</a>
35   */
36  public interface ProjectConfigurationProvider<C extends ProjectConfiguration> {
37  
38      /**
39       * Property name for the active configuration.
40       * Use it when firing a change in the active configuration.
41       */
42      String   PROP_CONFIGURATION_ACTIVE = "activeConfiguration"; // NOI18N
43  
44      /**
45       * Property name of the set of configurations.
46       * Use it when firing a change in the set of configurations.
47       */
48      String   PROP_CONFIGURATIONS = "configurations"; // NOI18N
49  
50      /**
51       * Gets a list of configurations.
52       * Permitted to return different instances from one invocation to the next
53       * but it is advisable for the "same" instances to compare as equal.
54       * <p>Should be called within {@link org.netbeans.api.project.ProjectManager#mutex read access}.
55       * @return all available configurations for this project
56       */
57      Collection  <C> getConfigurations();
58  
59      /**
60       * Gets the currently active configuration.
61       * <p>Should be called within {@link org.netbeans.api.project.ProjectManager#mutex read access}.
62       * @return the active configuration for this project (should be a member of {@link #getConfigurations}, or null only if that is empty)
63       */
64      C getActiveConfiguration();
65  
66      /**
67       * Sets the active configuration.
68       * Should fire a change in {@link #PROP_CONFIGURATION_ACTIVE}.
69       * It should be true afterwards that <code>configuration.equals(getActiveConfiguration())</code>
70       * though it might not be true that <code>configuration == getActiveConfiguration()</code>.
71       * <p class="nonnormative">
72       * If possible, the choice of configuration should be persisted for the next IDE session.
73       * If applicable, the persisted choice should be kept in per-user settings, not shared or versioned.
74       * </p>
75       * <p>Should be called within {@link org.netbeans.api.project.ProjectManager#mutex write access}.
76       * @param configuration new active configuration
77       * @throws IllegalArgumentException if the requested configuration is not a member of {@link #getConfigurations}
78       * @throws IOException if storing the configuration change failed
79       */
80      void setActiveConfiguration(C configuration) throws IllegalArgumentException  , IOException  ;
81  
82      /**
83       * Checks if this project can provide a GUI customizer for its configurations.
84       * @return true if {@link #customize} may be called
85       */
86      boolean hasCustomizer();
87  
88      /**
89       * Customize this project's configurations.
90       * Only permitted if {@link #hasCustomizer} is true.
91       * May, for example, open the project properties dialog.
92       */
93      void customize();
94  
95      /**
96       * Indicates if a project action is affected by the choice of configuration.
97       * If so, a GUI for this action is permitted to show a list of configurations and
98       * let the user select a configuration to apply to one action invocation only.
99       * Such a GUI can avoid the need to first select an active configuration and
100      * then run the action as two steps.
101      * This is done by including a {@link ProjectConfiguration} in the context passed
102      * to {@link ActionProvider#invokeAction}.
103      * A project is free to return <code>false</code> even if the configuration
104      * <em>might</em> affect the behavior of the action, if it simply does not
105      * wish for such a GUI to be shown.
106      * <p class="nonnormative">
107      * The likely values of <code>command</code> are those actions
108      * normally shown in the IDE's tool bar with main project bindings:
109      * {@link ActionProvider#COMMAND_BUILD}, {@link ActionProvider#COMMAND_REBUILD},
110      * {@link ActionProvider#COMMAND_RUN}, and {@link ActionProvider#COMMAND_DEBUG}.
111      * </p>
112      * @param command one of {@link ActionProvider#getSupportedActions}
113      * @return true if the named command refers to an action affected by configurations
114      */
115     boolean configurationsAffectAction(String   command);
116 
117     /**
118      * Adds a listener to check for changes in {@link #PROP_CONFIGURATION_ACTIVE} or {@link #PROP_CONFIGURATIONS}.
119      * @param lst a listener to add
120      */
121     void addPropertyChangeListener(PropertyChangeListener   lst);
122 
123     /**
124      * Removes a listener.
125      * @param lst a listener to remove
126      */
127     void removePropertyChangeListener(PropertyChangeListener   lst);
128 
129 }
130
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags