[project model api] annotate classes and interfaces from project model API as NonExte...
[idea/community.git] / platform / projectModel-api / src / com / intellij / openapi / module / ModuleManager.java
1 /*
2  * Copyright 2000-2017 JetBrains s.r.o.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package com.intellij.openapi.module;
17
18 import com.intellij.openapi.project.Project;
19 import com.intellij.openapi.util.InvalidDataException;
20 import com.intellij.openapi.util.SimpleModificationTracker;
21 import com.intellij.util.graph.Graph;
22 import org.jdom.JDOMException;
23 import org.jetbrains.annotations.ApiStatus;
24 import org.jetbrains.annotations.NonNls;
25 import org.jetbrains.annotations.NotNull;
26 import org.jetbrains.annotations.Nullable;
27
28 import java.io.IOException;
29 import java.util.Collection;
30 import java.util.Comparator;
31 import java.util.List;
32
33 /**
34  * Provides services for working with the modules of a project.
35  */
36 @ApiStatus.NonExtendable
37 public abstract class ModuleManager extends SimpleModificationTracker {
38   /**
39    * Returns the module manager instance for the current project.
40    *
41    * @param project the project for which the module manager is requested.
42    * @return the module manager instance.
43    */
44   public static ModuleManager getInstance(@NotNull Project project) {
45     return project.getComponent(ModuleManager.class);
46   }
47
48   /**
49    * Creates a module of the specified type at the specified path and adds it to the project
50    * to which the module manager is related.
51    *
52    * @param filePath     path to an *.iml file where module configuration will be saved; name of the module will be equal to the file name without extension.
53    * @param moduleTypeId the ID of the module type to create.
54    * @return the module instance.
55    */
56   @NotNull
57   public abstract Module newModule(@NotNull @NonNls String filePath, @NotNull String moduleTypeId);
58
59   /**
60    * Loads a module from an .iml file with the specified path and adds it to the project.
61    *
62    * @param filePath the path to load the module from.
63    * @return the module instance.
64    * @throws InvalidDataException        if the data in the .iml file is semantically incorrect.
65    * @throws IOException                 if an I/O error occurred when loading the module file.
66    * @throws JDOMException               if the file contains invalid XML data.
67    * @throws ModuleWithNameAlreadyExists if a module with such a name already exists in the project.
68    */
69   @NotNull
70   public abstract Module loadModule(@NotNull String filePath) throws IOException, JDOMException, ModuleWithNameAlreadyExists;
71
72   /**
73    * Disposes of the specified module and removes it from the project.
74    *
75    * @param module the module to remove.
76    */
77   public abstract void disposeModule(@NotNull Module module);
78
79   /**
80    * Returns the list of all modules in the project.
81    *
82    * @return the array of modules.
83    */
84   @NotNull
85   public abstract Module[] getModules();
86
87   /**
88    * Returns the project module with the specified name.
89    *
90    * @param name the name of the module to find.
91    * @return the module instance, or null if no module with such name exists.
92    */
93   @Nullable
94   public abstract Module findModuleByName(@NonNls @NotNull String name);
95
96   /**
97    * Returns the list of modules sorted by dependency (the modules which do not depend
98    * on anything are in the beginning of the list, a module which depends on another module
99    * follows it in the list).
100    *
101    * @return the sorted array of modules.
102    */
103   @NotNull
104   public abstract Module[] getSortedModules();
105
106   /**
107    * Returns the module comparator which can be used for sorting modules by dependency
108    * (the modules which do not depend on anything are in the beginning of the list,
109    * a module which depends on another module follows it in the list).
110    *
111    * @return the module comparator instance.
112    */
113   @NotNull
114   public abstract Comparator<Module> moduleDependencyComparator();
115
116   /**
117    * Returns the list of modules which directly depend on the specified module.
118    *
119    * @param module the module for which the list of dependent modules is requested.
120    * @return list of <i>modules that depend on</i> given module.
121    * @see ModuleUtilCore#getAllDependentModules(Module)
122    */
123   @NotNull
124   public abstract List<Module> getModuleDependentModules(@NotNull Module module);
125
126   /**
127    * Checks if one of the specified modules directly depends on the other module.
128    *
129    * @param module   the module to check the dependency for.
130    * @param onModule the module on which {@code module} may depend.
131    * @return true if {@code module} directly depends on {@code onModule}, false otherwise.
132    */
133   public abstract boolean isModuleDependent(@NotNull Module module, @NotNull Module onModule);
134
135   /**
136    * Returns the graph of dependencies between modules in the project.
137    *
138    * @return the module dependency graph.
139    */
140   @NotNull
141   public abstract Graph<Module> moduleGraph();
142
143   /**
144    * Returns the graph of dependencies between modules in the project.
145    *
146    * @param includeTests whether test-only dependencies should be included
147    * @return the module dependency graph.
148    */
149   @NotNull
150   public abstract Graph<Module> moduleGraph(boolean includeTests);
151
152   /**
153    * Returns the model for the list of modules in the project, which can be used to add,
154    * remove or modify modules.
155    *
156    * @return the modifiable model instance.
157    */
158   @NotNull
159   public abstract ModifiableModuleModel getModifiableModel();
160
161
162   /**
163    * Returns the path to the group to which the specified module belongs, as an array of group names starting from the project root.
164    * <p>
165    * <strong>Use {@link ModuleGrouper#getGroupPath(Module)} instead.</strong> Explicit module groups will be replaced
166    * by automatical module grouping accordingly to qualified names of modules, see https://youtrack.jetbrains.com/issue/IDEA-166061 for details.
167    * </p>
168    * @param module the module for which the path is requested.
169    * @return the path to the group for the module, or null if the module does not belong to any group.
170    */
171   @Nullable
172   public abstract String[] getModuleGroupPath(@NotNull Module module);
173
174   public abstract boolean hasModuleGroups();
175
176   /**
177    * @return description of all modules in the project including unloaded
178    */
179   @ApiStatus.Experimental
180   @NotNull
181   public abstract Collection<ModuleDescription> getAllModuleDescriptions();
182
183   @ApiStatus.Experimental
184   @NotNull
185   public abstract Collection<UnloadedModuleDescription> getUnloadedModuleDescriptions();
186
187   @ApiStatus.Experimental
188   @Nullable
189   public abstract UnloadedModuleDescription getUnloadedModuleDescription(@NotNull String moduleName);
190
191   @NotNull
192   public abstract ModuleGrouper getModuleGrouper(@Nullable ModifiableModuleModel model);
193
194   /**
195    * Specify list of modules which will be unloaded from the project.
196    * @see UnloadedModuleDescription
197    */
198   @ApiStatus.Experimental
199   public abstract void setUnloadedModules(@NotNull List<String> unloadedModuleNames);
200
201   @ApiStatus.Experimental
202   public void removeUnloadedModules(@NotNull Collection<? extends UnloadedModuleDescription> unloadedModules) {
203   }
204 }