[project model api] annotate classes and interfaces from project model API as NonExte...
[idea/community.git] / platform / projectModel-api / src / com / intellij / openapi / project / ProjectManager.java
1 // Copyright 2000-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
2 package com.intellij.openapi.project;
3
4 import com.intellij.openapi.Disposable;
5 import com.intellij.openapi.application.ApplicationManager;
6 import com.intellij.util.messages.Topic;
7 import org.jdom.JDOMException;
8 import org.jetbrains.annotations.ApiStatus;
9 import org.jetbrains.annotations.NotNull;
10 import org.jetbrains.annotations.Nullable;
11 import org.jetbrains.annotations.TestOnly;
12
13 import java.io.File;
14 import java.io.IOException;
15 import java.nio.file.Path;
16
17 /**
18  * Provides project management.
19  */
20 @ApiStatus.NonExtendable
21 public abstract class ProjectManager {
22   public static final Topic<ProjectManagerListener> TOPIC = new Topic<>("Project open and close events", ProjectManagerListener.class);
23
24   /**
25    * @return {@code ProjectManager} instance
26    */
27   public static ProjectManager getInstance() {
28     return ApplicationManager.getApplication().getService(ProjectManager.class);
29   }
30
31   @Nullable
32   public static ProjectManager getInstanceIfCreated() {
33     return ApplicationManager.getApplication().getServiceIfCreated(ProjectManager.class);
34   }
35
36   /**
37    * @deprecated Use {@link #TOPIC} instead
38    */
39   @Deprecated
40   public abstract void addProjectManagerListener(@NotNull ProjectManagerListener listener);
41
42   public abstract void addProjectManagerListener(@NotNull VetoableProjectManagerListener listener);
43
44   /**
45    * @deprecated Use {@link #TOPIC} instead
46    */
47   @Deprecated
48   public abstract void addProjectManagerListener(@NotNull ProjectManagerListener listener, @NotNull Disposable parentDisposable);
49
50   /**
51    * @deprecated Use {@link #TOPIC} instead
52    */
53   @Deprecated
54   public abstract void removeProjectManagerListener(@NotNull ProjectManagerListener listener);
55
56   public abstract void removeProjectManagerListener(@NotNull VetoableProjectManagerListener listener);
57
58   /**
59    * Adds listener to the specified project.
60    *
61    * @param project  project to add listener to
62    * @param listener listener to add
63    */
64   public abstract void addProjectManagerListener(@NotNull Project project, @NotNull ProjectManagerListener listener);
65
66   /**
67    * Removes listener from the specified project.
68    *
69    * @param project  project to remove listener from
70    * @param listener listener to remove
71    */
72   public abstract void removeProjectManagerListener(@NotNull Project project, @NotNull ProjectManagerListener listener);
73
74   /**
75    * Returns the list of currently opened projects.
76    * {@link Project#isDisposed()} must be checked for each project before use (if the whole operation is not under read action).
77    */
78   @NotNull
79   public abstract Project[] getOpenProjects();
80
81   /**
82    * Returns the project which is used as a template for new projects. The template project
83    * is always available, even when no other project is open. This {@link Project} instance is not
84    * supposed to be used for anything except template settings storage.<p/>
85    *
86    * NB: default project can be lazy loaded
87    *
88    * @return the template project instance.
89    */
90   @NotNull
91   public abstract Project getDefaultProject();
92
93   /**
94    * Loads and opens a project with the specified path. If the project file is from an older IDEA
95    * version, prompts the user to convert it to the latest version. If the project file is from a
96    * newer version, shows a message box telling the user that the load failed.
97    *
98    * @param filePath the .ipr file path
99    * @return the opened project file, or null if the project failed to load because of version mismatch
100    *         or because the project is already open.
101    * @throws IOException          if the project file was not found or failed to read
102    * @throws JDOMException        if the project file contained invalid XML
103    */
104   @Nullable
105   public abstract Project loadAndOpenProject(@NotNull String filePath) throws IOException, JDOMException;
106
107   @Nullable
108   @ApiStatus.Experimental
109   @TestOnly
110   public Project loadAndOpenProject(@NotNull File file) throws IOException, JDOMException {
111     return loadAndOpenProject(file.toPath());
112   }
113
114   @Nullable
115   @ApiStatus.Experimental
116   public abstract Project loadAndOpenProject(@NotNull Path file) throws IOException, JDOMException;
117
118   /**
119    * Closes the specified project, but does not dispose it.
120    *
121    * @param project the project to close.
122    * @return true if the project was closed successfully, false if the closing was disallowed by the close listeners.
123    */
124   public abstract boolean closeProject(@NotNull Project project);
125
126   /**
127    * Asynchronously reloads the specified project.
128    *
129    * @param project the project to reload.
130    */
131   @SuppressWarnings("unused")
132   public abstract void reloadProject(@NotNull Project project);
133
134   /**
135    * Create new project in given location.
136    *
137    * @param name project name
138    * @param path project location
139    *
140    * @return newly crated project
141    */
142   @Nullable
143   public abstract Project createProject(@Nullable String name, @NotNull String path);
144 }