unloaded modules: javadocs added
[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 public abstract class ModuleManager extends SimpleModificationTracker {
37   /**
38    * Returns the module manager instance for the current project.
39    *
40    * @param project the project for which the module manager is requested.
41    * @return the module manager instance.
42    */
43   public static ModuleManager getInstance(@NotNull Project project) {
44     return project.getComponent(ModuleManager.class);
45   }
46
47   /**
48    * Creates a module of the specified type at the specified path and adds it to the project
49    * to which the module manager is related.
50    *
51    * @param filePath     the path at which the module is created.
52    * @param moduleTypeId the ID of the module type to create.
53    * @return the module instance.
54    */
55   @NotNull
56   public abstract Module newModule(@NotNull @NonNls String filePath, final String moduleTypeId);
57
58   /**
59    * Loads a module from an .iml file with the specified path and adds it to the project.
60    *
61    * @param filePath the path to load the module from.
62    * @return the module instance.
63    * @throws InvalidDataException        if the data in the .iml file is semantically incorrect.
64    * @throws IOException                 if an I/O error occurred when loading the module file.
65    * @throws JDOMException               if the file contains invalid XML data.
66    * @throws ModuleWithNameAlreadyExists if a module with such a name already exists in the project.
67    */
68   @NotNull
69   public abstract Module loadModule(@NotNull String filePath) throws IOException, JDOMException, ModuleWithNameAlreadyExists;
70
71   /**
72    * Disposes of the specified module and removes it from the project.
73    *
74    * @param module the module to remove.
75    */
76   public abstract void disposeModule(@NotNull Module module);
77
78   /**
79    * Returns the list of all modules in the project.
80    *
81    * @return the array of modules.
82    */
83   @NotNull
84   public abstract Module[] getModules();
85
86   /**
87    * Returns the project module with the specified name.
88    *
89    * @param name the name of the module to find.
90    * @return the module instance, or null if no module with such name exists.
91    */
92   @Nullable
93   public abstract Module findModuleByName(@NonNls @NotNull String name);
94
95   /**
96    * Returns the list of modules sorted by dependency (the modules which do not depend
97    * on anything are in the beginning of the list, a module which depends on another module
98    * follows it in the list).
99    *
100    * @return the sorted array of modules.
101    */
102   @NotNull
103   public abstract Module[] getSortedModules();
104
105   /**
106    * Returns the module comparator which can be used for sorting modules by dependency
107    * (the modules which do not depend on anything are in the beginning of the list,
108    * a module which depends on another module follows it in the list).
109    *
110    * @return the module comparator instance.
111    */
112   @NotNull
113   public abstract Comparator<Module> moduleDependencyComparator();
114
115   /**
116    * Returns the list of modules which directly depend on the specified module.
117    *
118    * @param module the module for which the list of dependent modules is requested.
119    * @return list of <i>modules that depend on</i> given module.
120    * @see ModuleUtilCore#getAllDependentModules(Module)
121    */
122   @NotNull
123   public abstract List<Module> getModuleDependentModules(@NotNull Module module);
124
125   /**
126    * Checks if one of the specified modules directly depends on the other module.
127    *
128    * @param module   the module to check the dependency for.
129    * @param onModule the module on which <code>module</code> may depend.
130    * @return true if <code>module</code> directly depends on <code>onModule</code>, false otherwise.
131    */
132   public abstract boolean isModuleDependent(@NotNull Module module, @NotNull Module onModule);
133
134   /**
135    * Returns the graph of dependencies between modules in the project.
136    *
137    * @return the module dependency graph.
138    */
139   @NotNull
140   public abstract Graph<Module> moduleGraph();
141
142   /**
143    * Returns the graph of dependencies between modules in the project.
144    *
145    * @param includeTests whether test-only dependencies should be included
146    * @return the module dependency graph.
147    * @since 11.0
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 com.intellij.openapi.module.ModuleGrouper#getGroupPath()} instead.</strong> Exlicit 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   public abstract Collection<ModuleDescription> getAllModuleDescriptions();
181
182   @ApiStatus.Experimental
183   public abstract Collection<UnloadedModuleDescription> getUnloadedModuleDescriptions();
184
185   @ApiStatus.Experimental
186   @Nullable
187   public abstract UnloadedModuleDescription getUnloadedModuleDescription(@NotNull String moduleName);
188
189   /**
190    * Specify list of modules which will be unloaded from the project.
191    * @see UnloadedModuleDescription
192    */
193   @ApiStatus.Experimental
194   public abstract void setUnloadedModules(@NotNull List<String> unloadedModuleNames);
195 }