[project model api] annotate classes and interfaces from project model API as NonExte...
[idea/community.git] / platform / projectModel-api / src / com / intellij / openapi / module / ModifiableModuleModel.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.module;
3
4 import com.intellij.openapi.project.Project;
5 import org.jetbrains.annotations.ApiStatus;
6 import org.jetbrains.annotations.NotNull;
7 import org.jetbrains.annotations.Nullable;
8 import org.jetbrains.annotations.SystemIndependent;
9
10 import java.io.IOException;
11 import java.util.Map;
12
13 /**
14  * Represents the model for the list of modules in a project, or a temporary copy
15  * of that model displayed in the configuration UI.
16  *
17  * @see ModuleManager#getModifiableModel()
18  */
19 @ApiStatus.NonExtendable
20 public interface ModifiableModuleModel {
21   /**
22    * Returns the list of all modules in the project. Same as {@link ModuleManager#getModules()}.
23    *
24    * @return the array of modules.
25    */
26   @NotNull
27   Module[] getModules();
28
29   /**
30    * Creates a module of the specified type at the specified path and adds it to the project
31    * to which the module manager is related. {@link #commit()} must be called to
32    * bring the changes in effect.
33    *
34    * @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.
35    * @param moduleTypeId the ID of the module type to create.
36    * @return the module instance.
37    */
38   @NotNull
39   Module newModule(@NotNull String filePath, @NotNull String moduleTypeId);
40
41   /**
42    * Creates a module of the specified type at the specified path and adds it to the project
43    * to which the module manager is related. {@link #commit()} must be called to
44    * bring the changes in effect.
45    *
46    * @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.
47    * @param moduleTypeId ID of the module type to create.
48    * @param options      map of module options to be used when creating the module
49    * @return the module instance.
50    */
51   @NotNull
52   Module newModule(@NotNull String filePath, @NotNull String moduleTypeId, @Nullable Map<String, String> options);
53
54   /**
55    * Loads a module from an .iml file with the specified path and adds it to the project.
56    * {@link #commit()} must be called to bring the changes in effect.
57    *
58    * @param filePath the path to load the module from.
59    * @return the module instance.
60    * @throws IOException                 if an I/O error occurred when loading the module file.
61    * @throws ModuleWithNameAlreadyExists if a module with such a name already exists in the project.
62    */
63   @NotNull
64   Module loadModule(@NotNull @SystemIndependent String filePath) throws IOException, ModuleWithNameAlreadyExists;
65
66   /**
67    * Disposes of the specified module and removes it from the project. {@link #commit()}
68    * must be called to bring the changes in effect.
69    *
70    * @param module the module to remove.
71    */
72   void disposeModule(@NotNull Module module);
73
74   /**
75    * Returns the project module with the specified name.
76    *
77    * @param name the name of the module to find.
78    * @return the module instance, or null if no module with such name exists.
79    */
80   @Nullable
81   Module findModuleByName(@NotNull String name);
82
83   /**
84    * Disposes of all modules in the project.
85    */
86   void dispose();
87
88   /**
89    * Checks if there are any uncommitted changes to the model.
90    *
91    * @return true if there are uncommitted changes, false otherwise
92    */
93   boolean isChanged();
94
95   /**
96    * Commits changes made in this model to the actual project structure.
97    */
98   void commit();
99
100   /**
101    * Schedules the rename of a module to be performed when the model is committed.
102    *
103    * @param module  the module to rename.
104    * @param newName the new name to rename the module to.
105    * @throws ModuleWithNameAlreadyExists if a module with such a name already exists in the project.
106    */
107   void renameModule(@NotNull Module module, @NotNull String newName) throws ModuleWithNameAlreadyExists;
108
109   /**
110    * Returns the project module which has been renamed to the specified name.
111    *
112    * @param newName the name of the renamed module to find.
113    * @return the module instance, or null if no module has been renamed to such a name.
114    */
115   @Nullable
116   Module getModuleToBeRenamed(@NotNull String newName);
117
118   /**
119    * Returns the name to which the specified module has been renamed.
120    *
121    * @param module the module for which the new name is requested.
122    * @return the new name, or null if the module has not been renamed.
123    */
124   @Nullable
125   String getNewName(@NotNull Module module);
126
127   /**
128    * @return the new name of {@code module} if it has been renamed or its old name it hasn't.
129    */
130   @NotNull
131   String getActualName(@NotNull Module module);
132
133   @Nullable
134   String[] getModuleGroupPath(@NotNull Module module);
135
136   boolean hasModuleGroups();
137
138   void setModuleGroupPath(@NotNull Module module, @Nullable("null means remove") String[] groupPath);
139
140   @NotNull
141   Project getProject();
142 }