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