OpenProjects


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.api.project.ui;
21  
22  import java.beans.PropertyChangeListener  ;
23  import org.netbeans.api.project.Project;
24  import org.netbeans.modules.project.uiapi.OpenProjectsTrampoline;
25  import org.netbeans.modules.project.uiapi.Utilities;
26  
27  /**
28   * List of projects open in the GUI.
29   * <p class="nonnormative">
30   * <strong>Warning:</strong> this API is intended only for a limited set of use
31   * cases where obtaining a list of all open projects is really the direct goal.
32   * For example, you may wish to display a chooser letting the user select a
33   * file from among the top-level source folders of any open project.
34   * For many cases, however, this API is not the correct approach, so use it as
35   * a last resort. Consider <a HREF="@JAVA/API@/org/netbeans/api/java/classpath/GlobalPathRegistry.html"><code>GlobalPathRegistry</code></a>,
36   * {@link org.netbeans.spi.project.ui.ProjectOpenedHook},
37   * and {@link org.netbeans.spi.project.ui.support.ProjectSensitiveActions}
38   * (or {@link org.netbeans.spi.project.ui.support.MainProjectSensitiveActions})
39   * first. Only certain operations should actually be aware of which projects
40   * are "open"; by default, all project functionality should be available whether
41   * it is open or not.
42   * </p>
43   * @author Jesse Glick, Petr Hrebejk
44   */
45  public final class OpenProjects {
46      
47      /**
48       * Property representing open projects.
49       * @see #getOpenProjects
50       */
51      public static final String   PROPERTY_OPEN_PROJECTS = "openProjects"; // NOI18N
52      
53      /**
54       * Property representing main project.
55       * @see #getMainProject
56       * @since org.netbeans.modules.projectuiapi/1 1.20
57       */
58      public static final String   PROPERTY_MAIN_PROJECT = "MainProject"; // NOI18N
59      
60      private static OpenProjects INSTANCE = new OpenProjects();
61      
62      private OpenProjectsTrampoline trampoline;
63      
64      private OpenProjects() {
65          this.trampoline = Utilities.getOpenProjectsTrampoline();
66      }
67  
68      /**
69       * Get the default singleton instance of this class.
70       * @return the default instance
71       */
72      public static OpenProjects getDefault() {                
73          return INSTANCE;
74      }
75      
76      /**
77       * Gets a list of currently open projects.
78       * @return list of projects currently opened in the IDE's GUI; order not specified
79       */
80      public Project[] getOpenProjects() {
81          return trampoline.getOpenProjectsAPI();
82      }
83  
84      /**
85       * Opens given projects.
86       * Acquires {@link org.netbeans.api.project.ProjectManager#mutex()} in the write mode.
87       * @param projects to be opened. In the case when some of the projects are already opened
88       * these projects are not opened again. If the projects contain duplicates, the duplicated
89       * projects are opened just once.
90       * @param openSubprojects if true also subprojects are opened.
91       * @since org.netbeans.modules.projectuiapi/0 1.2
92       * <p class="nonnormative">
93       * This method is designed for use by logical view's Libraries Node to open one or more of dependent
94       * projects. This method can be used also by other project GUI components which need to open certain
95       * project(s), eg. code generation wizards.<br>
96       * The method should not be used for opening newly created project, insted the
97       * {@link org.openide.WizardDescriptor.InstantiatingIterator#instantiate()} used for creation of new project
98       * should return the project directory.<br>
99       * The method should not be also used  to provide a GUI to open subprojects.
100      * The {@link org.netbeans.spi.project.ui.support.CommonProjectActions#openSubprojectsAction()} should be used
101      * instead.
102      * </p>
103      */
104     public void open (Project[] projects, boolean openSubprojects) {
105         trampoline.openAPI (projects,openSubprojects);
106     }
107 
108     /**
109      * Closes given projects.
110      * Acquires {@link org.netbeans.api.project.ProjectManager#mutex()} in the write mode.
111      * @param projects to be closed. The non opened project contained in the projects array are ignored.
112      * @since org.netbeans.modules.projectuiapi/0 1.2
113      */
114     public void close (Project[] projects) {
115         trampoline.closeAPI (projects);
116     }
117 
118     /**Retrieves the current main project set in the IDE.
119      *
120      * <div class="nonnormative">
121      * <p><strong>Warning:</strong> the set of usecases that require invoking this method is
122      * limited. {@link org.netbeans.spi.project.ui.support.MainProjectSensitiveActions} should
123      * be used in favour of this method if possible. In particular, this method should <em>not</em>
124      * be used to let the user choose if an action should be run on the main vs. the currently selected project.</p>
125      * <p>As a rule of thumb, any code outside of the project system infrastructure which behaves differently
126      * depending on the choice of main project should be reviewed critically. All functionality
127      * of a project ought to be available regardless of the "main project" flag, which is intended only
128      * as a convenient shortcut to permit certain actions (such as <b>Run</b>) to be invoked
129      * from a global context on a preselected project.</p>
130      * </div>
131      *
132      * @return the current main project or null if none
133      * @since 1.11
134      */
135     public Project getMainProject() {
136         return trampoline.getMainProject();
137     }
138     
139     /**Sets the main project.
140      *
141      * <div class="nonnormative">
142      * <p><strong>Warning:</strong> the set of usecases that require invoking this method is
143      * very limited and should be generally avoided if possible. In particular, this method
144      * should <em>not</em> be used to mark a project just created by the <b>New Project</b> wizard
145      * as the main project.</p>
146      * </div>
147      *
148      * @param project project to set as main project (must be open), or
149      *                <code>null</code> to set no project as main.
150      * @throws IllegalArgumentException if the project is not opened.
151      * @since 1.11
152      */
153     public void setMainProject(Project project) throws IllegalArgumentException   {
154         trampoline.setMainProject(project);
155     }
156     
157     /**
158      * Adds a listener to changes in the set of open projects.
159      * As this class is a singleton and is not subject to garbage collection,
160      * it is recommended to add only weak listeners, or remove regular listeners reliably.
161      * @param listener a listener to add
162      * @see #PROPERTY_OPEN_PROJECTS
163      */    
164     public void addPropertyChangeListener( PropertyChangeListener   listener ) {
165         trampoline.addPropertyChangeListenerAPI( listener );
166     }
167     
168     /**
169      * Removes a listener.
170      * @param listener a listener to remove
171      */
172     public void removePropertyChangeListener( PropertyChangeListener   listener ) {
173         trampoline.removePropertyChangeListenerAPI( listener );
174     }
175     
176 }
177
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags