Revert "prefer to use JDK utils in low-level classes, do not extend DynamicBundle...
[idea/community.git] / platform / projectModel-api / src / com / intellij / openapi / module / ModuleManager.java
1 // Copyright 2000-2020 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.module;
3
4 import com.intellij.openapi.project.Project;
5 import com.intellij.openapi.util.SimpleModificationTracker;
6 import com.intellij.util.graph.Graph;
7 import org.jdom.JDOMException;
8 import org.jetbrains.annotations.ApiStatus;
9 import org.jetbrains.annotations.NonNls;
10 import org.jetbrains.annotations.NotNull;
11 import org.jetbrains.annotations.Nullable;
12
13 import java.io.File;
14 import java.io.IOException;
15 import java.nio.file.Path;
16 import java.util.Collection;
17 import java.util.Comparator;
18 import java.util.List;
19
20 /**
21  * Provides services for working with the modules of a project.
22  */
23 @ApiStatus.NonExtendable
24 public abstract class ModuleManager extends SimpleModificationTracker {
25   /**
26    * Returns the module manager instance for the current project.
27    *
28    * @param project the project for which the module manager is requested.
29    * @return the module manager instance.
30    */
31   public static ModuleManager getInstance(@NotNull Project project) {
32     return project.getComponent(ModuleManager.class);
33   }
34
35   /**
36    * Creates a module of the specified type at the specified path and adds it to the project
37    * to which the module manager is related.
38    *
39    * @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.
40    * @param moduleTypeId the ID of the module type to create.
41    * @return the module instance.
42    */
43   public abstract @NotNull Module newModule(@NotNull @NonNls String filePath, @NotNull String moduleTypeId);
44
45   public @NotNull Module newModule(@NotNull Path file, @NotNull String moduleTypeId) {
46     return newModule(file.toString().replace(File.separatorChar, '/'), moduleTypeId);
47   }
48
49   /**
50    * Creates a non-persistent module of the specified type and adds it to the project
51    * to which the module manager is related. {@link #commit()} must be called to
52    * bring the changes in effect.
53    *
54    * In contrast with modules created by {@link #newModule(String, String)},
55    * non-persistent modules aren't stored on a filesystem and aren't being written
56    * in a project XML file. When IDE closes, all non-persistent modules vanishes out.
57    */
58   @ApiStatus.Experimental
59   @NotNull
60   public Module newNonPersistentModule(@NotNull String moduleName, @NotNull String id) {
61     throw new UnsupportedOperationException();
62   }
63
64   /**
65    * @deprecated Use {@link #loadModule(Path)}
66    */
67   @Deprecated
68   public abstract @NotNull Module loadModule(@NotNull String filePath) throws IOException, JDOMException, ModuleWithNameAlreadyExists;
69
70   /**
71    * Loads a module from an .iml file with the specified path and adds it to the project.
72    *
73    * @param file the path to load the module from.
74    * @return the module instance.
75    * @throws IOException                 if an I/O error occurred when loading the module file.
76    * @throws ModuleWithNameAlreadyExists if a module with such a name already exists in the project.
77    */
78   public abstract @NotNull Module loadModule(@NotNull Path file) throws IOException, ModuleWithNameAlreadyExists;
79
80   /**
81    * Disposes of the specified module and removes it from the project.
82    *
83    * @param module the module to remove.
84    */
85   public abstract void disposeModule(@NotNull Module module);
86
87   /**
88    * Returns the list of all modules in the project.
89    *
90    * @return the array of modules.
91    */
92   public abstract Module @NotNull [] getModules();
93
94   /**
95    * Returns the project module with the specified name.
96    *
97    * @param name the name of the module to find.
98    * @return the module instance, or null if no module with such name exists.
99    */
100   @Nullable
101   public abstract Module findModuleByName(@NonNls @NotNull String name);
102
103   /**
104    * Returns the list of modules sorted by dependency (the modules which do not depend
105    * on anything are in the beginning of the list, a module which depends on another module
106    * follows it in the list).
107    *
108    * @return the sorted array of modules.
109    */
110   public abstract Module @NotNull [] getSortedModules();
111
112   /**
113    * Returns the module comparator which can be used for sorting modules by dependency
114    * (the modules which do not depend on anything are in the beginning of the list,
115    * a module which depends on another module follows it in the list).
116    *
117    * @return the module comparator instance.
118    */
119   @NotNull
120   public abstract Comparator<Module> moduleDependencyComparator();
121
122   /**
123    * Returns the list of modules which directly depend on the specified module.
124    *
125    * @param module the module for which the list of dependent modules is requested.
126    * @return list of <i>modules that depend on</i> given module.
127    * @see ModuleUtilCore#getAllDependentModules(Module)
128    */
129   @NotNull
130   public abstract List<Module> getModuleDependentModules(@NotNull Module module);
131
132   /**
133    * Checks if one of the specified modules directly depends on the other module.
134    *
135    * @param module   the module to check the dependency for.
136    * @param onModule the module on which {@code module} may depend.
137    * @return true if {@code module} directly depends on {@code onModule}, false otherwise.
138    */
139   public abstract boolean isModuleDependent(@NotNull Module module, @NotNull Module onModule);
140
141   /**
142    * Returns the graph of dependencies between modules in the project.
143    *
144    * @return the module dependency graph.
145    */
146   @NotNull
147   public abstract Graph<Module> moduleGraph();
148
149   /**
150    * Returns the graph of dependencies between modules in the project.
151    *
152    * @param includeTests whether test-only dependencies should be included
153    * @return the module dependency graph.
154    */
155   @NotNull
156   public abstract Graph<Module> moduleGraph(boolean includeTests);
157
158   /**
159    * Returns the model for the list of modules in the project, which can be used to add,
160    * remove or modify modules.
161    *
162    * @return the modifiable model instance.
163    */
164   @NotNull
165   public abstract ModifiableModuleModel getModifiableModel();
166
167
168   /**
169    * Returns the path to the group to which the specified module belongs, as an array of group names starting from the project root.
170    * <p>
171    * <strong>Use {@link ModuleGrouper#getGroupPath(Module)} instead.</strong> Explicit module groups will be replaced
172    * by automatical module grouping accordingly to qualified names of modules, see https://youtrack.jetbrains.com/issue/IDEA-166061 for details.
173    * </p>
174    * @param module the module for which the path is requested.
175    * @return the path to the group for the module, or null if the module does not belong to any group.
176    */
177   public abstract String @Nullable [] getModuleGroupPath(@NotNull Module module);
178
179   public abstract boolean hasModuleGroups();
180
181   /**
182    * @return description of all modules in the project including unloaded
183    */
184   @ApiStatus.Experimental
185   @NotNull
186   public abstract Collection<ModuleDescription> getAllModuleDescriptions();
187
188   @ApiStatus.Experimental
189   @NotNull
190   public abstract Collection<UnloadedModuleDescription> getUnloadedModuleDescriptions();
191
192   @ApiStatus.Experimental
193   @Nullable
194   public abstract UnloadedModuleDescription getUnloadedModuleDescription(@NotNull String moduleName);
195
196   @NotNull
197   public abstract ModuleGrouper getModuleGrouper(@Nullable ModifiableModuleModel model);
198
199   /**
200    * Specify list of modules which will be unloaded from the project.
201    * @see UnloadedModuleDescription
202    */
203   @ApiStatus.Experimental
204   public abstract void setUnloadedModules(@NotNull List<String> unloadedModuleNames);
205
206   @ApiStatus.Experimental
207   public void removeUnloadedModules(@NotNull Collection<? extends UnloadedModuleDescription> unloadedModules) {
208   }
209 }