api: annotate classes and interfaces from project model API as NonExtendable
[idea/community.git] / platform / projectModel-api / src / com / intellij / openapi / roots / ModuleRootModel.java
1 /*
2  * Copyright 2000-2014 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.roots;
17
18 import com.intellij.openapi.module.Module;
19 import com.intellij.openapi.projectRoots.Sdk;
20 import com.intellij.openapi.vfs.VirtualFile;
21 import org.jetbrains.annotations.ApiStatus;
22 import org.jetbrains.annotations.NotNull;
23 import org.jetbrains.annotations.Nullable;
24 import org.jetbrains.jps.model.module.JpsModuleSourceRootType;
25
26 import java.util.List;
27 import java.util.Set;
28
29 /**
30  * Interface providing root information model for a given module.
31  * It's implemented by {@link ModuleRootManager}.
32  *
33  * @author dsl
34  */
35 @ApiStatus.NonExtendable
36 public interface ModuleRootModel {
37   /**
38    * Returns the module to which the model belongs.
39    *
40    * @return the module instance.
41    */
42   @NotNull
43   Module getModule();
44
45   /**
46    * Use this method to obtain all content entries of a module. Entries are given in
47    * lexicographical order of their paths.
48    *
49    * @return list of content entries for this module
50    * @see ContentEntry
51    */
52   @NotNull
53   ContentEntry[] getContentEntries();
54
55   /**
56    * Use this method to obtain order of roots of a module. Order of entries is important.
57    *
58    * @return list of order entries for this module
59    */
60   @NotNull
61   OrderEntry[] getOrderEntries();
62
63   /**
64    * Returns the SDK used by the module.
65    *
66    * @return either module-specific or inherited SDK
67    * @see #isSdkInherited()
68    */
69   @Nullable
70   Sdk getSdk();
71
72   /**
73    * Returns {@code true} if SDK for this module is inherited from a project.
74    *
75    * @return true if the SDK is inherited, false otherwise
76    * @see ProjectRootManager#getProjectSdk()
77    * @see ProjectRootManager#setProjectSdk(Sdk)
78    */
79   boolean isSdkInherited();
80
81   /**
82    * Returns an array of content roots from all content entries.
83    *
84    * @return the array of content roots.
85    * @see #getContentEntries()
86    */
87   @NotNull
88   VirtualFile[] getContentRoots();
89
90   /**
91    * Returns an array of content root urls from all content entries.
92    *
93    * @return the array of content root URLs.
94    * @see #getContentEntries()
95    */
96   @NotNull
97   String[] getContentRootUrls();
98
99   /**
100    * Returns an array of exclude roots from all content entries.
101    *
102    * @return the array of excluded roots.
103    * @see #getContentEntries()
104    */
105   @NotNull
106   VirtualFile[] getExcludeRoots();
107
108   /**
109    * Returns an array of exclude root urls from all content entries.
110    *
111    * @return the array of excluded root URLs.
112    * @see #getContentEntries()
113    */
114   @NotNull
115   String[] getExcludeRootUrls();
116
117   /**
118    * Returns an array of source roots from all content entries.
119    *
120    * @return the array of source roots.
121    * @see #getContentEntries()
122    * @see #getSourceRoots(boolean)
123    */
124   @NotNull
125   VirtualFile[] getSourceRoots();
126
127   /**
128    * Returns an array of source roots from all content entries.
129    *
130    * @param includingTests determines whether test source roots should be included in the result
131    * @return the array of source roots.
132    * @see #getContentEntries()
133    */
134   @NotNull
135   VirtualFile[] getSourceRoots(boolean includingTests);
136
137   /**
138    * Return a list of source roots of the specified type.
139    *
140    * @param rootType type of source roots
141    * @return list of source roots
142    */
143   @NotNull
144   List<VirtualFile> getSourceRoots(@NotNull JpsModuleSourceRootType<?> rootType);
145
146   /**
147    * Return a list of source roots which types belong to the specified set.
148    *
149    * @param rootTypes types of source roots
150    * @return list of source roots
151    */
152   @NotNull
153   List<VirtualFile> getSourceRoots(@NotNull Set<? extends JpsModuleSourceRootType<?>> rootTypes);
154
155   /**
156    * Returns an array of source root urls from all content entries.
157    *
158    * @return the array of source root URLs.
159    * @see #getContentEntries()
160    * @see #getSourceRootUrls(boolean)
161    */
162   @NotNull
163   String[] getSourceRootUrls();
164
165   /**
166    * Returns an array of source root urls from all content entries.
167    *
168    * @param includingTests determines whether test source root urls should be included in the result
169    * @return the array of source root URLs.
170    * @see #getContentEntries()
171    */
172   @NotNull
173   String[] getSourceRootUrls(boolean includingTests);
174
175   /**
176    * Passes all order entries in the module to the specified visitor.
177    *
178    * @param policy       the visitor to accept.
179    * @param initialValue the default value to be returned by the visit process.
180    * @return the value returned by the visitor.
181    * @see OrderEntry#accept(RootPolicy, Object)
182    */
183   <R> R processOrder(@NotNull RootPolicy<R> policy, R initialValue);
184
185   /**
186    * Returns {@link OrderEnumerator} instance which can be used to process order entries of the module (with or without dependencies) and
187    * collect classes or source roots.
188    *
189    * @return {@link OrderEnumerator} instance
190    */
191   @NotNull
192   OrderEnumerator orderEntries();
193
194   /**
195    * Returns list of module names <i>this module</i> depends on.
196    *
197    * @return the list of module names this module depends on.
198    */
199   @NotNull
200   String[] getDependencyModuleNames();
201
202   <T> T getModuleExtension(@NotNull Class<T> klass);
203
204   @NotNull
205   Module[] getModuleDependencies();
206
207   @NotNull
208   Module[] getModuleDependencies(boolean includeTests);
209 }