Revert "prefer to use JDK utils in low-level classes, do not extend DynamicBundle...
[idea/community.git] / platform / core-api / src / com / intellij / openapi / module / Module.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.Disposable;
5 import com.intellij.openapi.components.ComponentManager;
6 import com.intellij.openapi.extensions.AreaInstance;
7 import com.intellij.openapi.project.Project;
8 import com.intellij.openapi.util.NlsSafe;
9 import com.intellij.openapi.vfs.VirtualFile;
10 import com.intellij.psi.search.GlobalSearchScope;
11 import org.jetbrains.annotations.*;
12
13 import java.io.File;
14 import java.nio.file.Path;
15
16 /**
17  * Represents a module in an IDEA project.
18  *
19  * @see ModuleManager#getModules()
20  * @see ModuleComponent
21  */
22 @SuppressWarnings("DeprecatedIsStillUsed")
23 public interface Module extends ComponentManager, AreaInstance, Disposable {
24   /**
25    * The empty array of modules which cab be reused to avoid unnecessary allocations.
26    */
27   Module[] EMPTY_ARRAY = new Module[0];
28
29   @NonNls String ELEMENT_TYPE = "type";
30
31   /**
32    * Returns the {@code VirtualFile} for the module .iml file. Note that location if .iml file may not be related to location of the module
33    * files, it may be stored in a different directory, under .idea/modules or doesn't exist at all if the module configuration is imported
34    * from external project system (e.g. Gradle). So only internal subsystems which deal with serialization are supposed to use this method.
35    * If you need to find a directory (directories) where source files for the module are located, get its {@link com.intellij.openapi.roots.ModuleRootModel#getContentRoots() content roots}.
36    * If you need to get just some directory near to module files (e.g. to select by default in a file chooser), use {@link com.intellij.openapi.module.ModuleUtil#suggestBaseDirectory}.
37    */
38   @ApiStatus.Internal
39   @Nullable VirtualFile getModuleFile();
40
41   /**
42    * Returns path to the module .iml file. This method isn't supposed to be used from plugins, see {@link #getModuleFile()} details.
43    */
44   @ApiStatus.Internal
45   @SystemIndependent @NonNls 
46   default @NotNull String getModuleFilePath() {
47     return getModuleNioFile().toString().replace(File.separatorChar, '/');
48   }
49
50   /**
51    * Returns path to the module .iml file. This method isn't supposed to be used from plugins, see {@link #getModuleFile()} details.
52    */
53   @ApiStatus.Internal
54   @NotNull Path getModuleNioFile();
55
56   /**
57    * Returns the project to which this module belongs.
58    *
59    * @return the project instance.
60    */
61   @NotNull Project getProject();
62
63   /**
64    * Returns the name of this module.
65    *
66    * @return the module name.
67    */
68   @NotNull @NlsSafe String getName();
69
70   /**
71    * Checks if the module instance has been disposed and unloaded.
72    *
73    * @return true if the module has been disposed, false otherwise
74    */
75   @Override
76   boolean isDisposed();
77
78   boolean isLoaded();
79
80   /**
81    * @deprecated Please store options in your own {@link com.intellij.openapi.components.PersistentStateComponent}
82    */
83   @Deprecated
84   default void clearOption(@NotNull String key) {
85     setOption(key, null);
86   }
87
88   /**
89    * @deprecated Please store options in your own {@link com.intellij.openapi.components.PersistentStateComponent}
90    */
91   @Deprecated
92   void setOption(@NotNull String key, @Nullable String value);
93
94   /**
95    * @deprecated Please store options in your own {@link com.intellij.openapi.components.PersistentStateComponent}
96    */
97   @Deprecated
98   @NonNls
99   @Nullable
100   String getOptionValue(@NotNull String key);
101
102   /**
103    * @return module scope including source and tests, excluding libraries and dependencies.
104    */
105   @NotNull
106   GlobalSearchScope getModuleScope();
107
108   /**
109    * @param includeTests whether to include test source
110    * @return module scope including source and, optionally, tests, excluding libraries and dependencies.
111    */
112   @NotNull
113   GlobalSearchScope getModuleScope(boolean includeTests);
114
115   /**
116    * @return module scope including source, tests, and libraries, excluding dependencies.
117    */
118   @NotNull
119   GlobalSearchScope getModuleWithLibrariesScope();
120
121   /**
122    * @return module scope including source, tests, and dependencies, excluding libraries.
123    */
124   @NotNull
125   GlobalSearchScope getModuleWithDependenciesScope();
126
127   /**
128    * @return a scope that includes everything in module content roots, without any dependencies or libraries
129    */
130   @NotNull
131   GlobalSearchScope getModuleContentScope();
132
133   /**
134    * @return a scope that includes everything under the content roots of this module and its dependencies, with test source
135    */
136   @NotNull
137   GlobalSearchScope getModuleContentWithDependenciesScope();
138
139   /**
140    * @param includeTests whether test source and test dependencies should be included
141    * @return a scope including module source and dependencies with libraries
142    */
143   @NotNull
144   GlobalSearchScope getModuleWithDependenciesAndLibrariesScope(boolean includeTests);
145
146   /**
147    * @return a scope including everything under the content roots of this module and all modules that depend on it, directly or indirectly (via exported dependencies), excluding test source and resources
148    */
149   @NotNull
150   GlobalSearchScope getModuleWithDependentsScope();
151
152   /**
153    * @return same as {@link #getModuleWithDependentsScope()}, but with test source/resources included
154    */
155   @NotNull
156   GlobalSearchScope getModuleTestsWithDependentsScope();
157
158   /**
159    * @param includeTests whether test source and test dependencies should be included
160    * @return a scope including production (and optionally test) source of this module and all modules and libraries it depends upon, including runtime and transitive dependencies, even if they're not exported.
161    */
162   @NotNull
163   GlobalSearchScope getModuleRuntimeScope(boolean includeTests);
164
165   @Nullable @NonNls
166   default String getModuleTypeName() {
167     //noinspection deprecation
168     return getOptionValue(ELEMENT_TYPE);
169   }
170
171   default void setModuleType(@NotNull @NonNls String name) {
172     //noinspection deprecation
173     setOption(ELEMENT_TYPE, name);
174   }
175 }