api: annotate classes and interfaces from project model API as NonExtendable
[idea/community.git] / platform / projectModel-api / src / com / intellij / openapi / roots / ContentEntry.java
1 /*
2  * Copyright 2000-2009 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.vfs.VirtualFile;
19 import org.jetbrains.annotations.ApiStatus;
20 import org.jetbrains.annotations.NotNull;
21 import org.jetbrains.annotations.Nullable;
22 import org.jetbrains.jps.model.JpsElement;
23 import org.jetbrains.jps.model.module.JpsModuleSourceRootType;
24
25 import java.util.List;
26 import java.util.Set;
27
28 /**
29  * Represents a module's content root.
30  * You can get existing entries with {@link ModuleRootModel#getContentEntries()} or
31  * create a new one with {@link ModifiableRootModel#addContentEntry(VirtualFile)}.
32  *
33  * @author dsl
34  * @see ModuleRootModel#getContentEntries()
35  * @see ModifiableRootModel#addContentEntry(VirtualFile)
36  */
37 @ApiStatus.NonExtendable
38 public interface ContentEntry extends Synthetic {
39   /**
40    * Returns the root file or directory for the content root, if it is valid.
41    *
42    * @return the content root file or directory, or null if content entry is invalid.
43    */
44   @Nullable
45   VirtualFile getFile();
46
47   /**
48    * Returns the URL of content root.
49    * To validate returned roots, use
50    * <code>{@link com.intellij.openapi.vfs.VirtualFileManager#findFileByUrl(String)}</code>
51    *
52    * @return URL of content root, that should never be null.
53    */
54   @NotNull
55   String getUrl();
56
57   /**
58    * Returns the list of source roots under this content root.
59    *
60    * @return list of this {@code ContentEntry} {@link SourceFolder}s
61    */
62   @NotNull
63   SourceFolder[] getSourceFolders();
64
65   /**
66    * @param rootType type of accepted source roots
67    * @return list of source roots of the specified type containing in this content root
68    */
69   @NotNull
70   List<SourceFolder> getSourceFolders(@NotNull JpsModuleSourceRootType<?> rootType);
71
72   /**
73    *
74    * @param rootTypes types of accepted source roots
75    * @return list of source roots of the specified types containing in this content root
76    */
77   @NotNull
78   List<SourceFolder> getSourceFolders(@NotNull Set<? extends JpsModuleSourceRootType<?>> rootTypes);
79
80   /**
81    * Returns the list of files and directories for valid source roots under this content root.
82    *
83    * @return list of all valid source roots.
84    */
85   @NotNull
86   VirtualFile[] getSourceFolderFiles();
87
88   /**
89    * Returns the list of excluded roots configured under this content root. The result doesn't include synthetic excludes like the module output.
90    *
91    * @return list of this {@code ContentEntry} {@link ExcludeFolder}s
92    */
93   @NotNull
94   ExcludeFolder[] getExcludeFolders();
95
96   /**
97    * @return list of URLs for all excluded roots under this content root including synthetic excludes like the module output
98    */
99   @NotNull
100   List<String> getExcludeFolderUrls();
101
102   /**
103    * Returns the list of files and directories for valid excluded roots under this content root.
104    *
105    * @return list of all valid exclude roots including synthetic excludes like the module output
106    */
107   @NotNull
108   VirtualFile[] getExcludeFolderFiles();
109
110   /**
111    * Adds a source or test source root under the content root.
112    *
113    * @param file         the file or directory to add as a source root.
114    * @param isTestSource true if the file or directory is added as a test source root.
115    * @return the object representing the added root.
116    */
117   @NotNull
118   SourceFolder addSourceFolder(@NotNull VirtualFile file, boolean isTestSource);
119
120   /**
121    * Adds a source or test source root with the specified package prefix under the content root.
122    *
123    * @param file          the file or directory to add as a source root.
124    * @param isTestSource  true if the file or directory is added as a test source root.
125    * @param packagePrefix the package prefix for the root to add, or an empty string if no
126    *                      package prefix is required.
127    * @return the object representing the added root.
128    */
129   @NotNull
130   SourceFolder addSourceFolder(@NotNull VirtualFile file, boolean isTestSource, @NotNull String packagePrefix);
131
132   @NotNull
133   <P extends JpsElement>
134   SourceFolder addSourceFolder(@NotNull VirtualFile file, @NotNull JpsModuleSourceRootType<P> type, @NotNull P properties);
135
136   @NotNull
137   <P extends JpsElement>
138   SourceFolder addSourceFolder(@NotNull VirtualFile file, @NotNull JpsModuleSourceRootType<P> type);
139
140   /**
141    * Adds a source or test source root under the content root.
142    *
143    * @param  url the file or directory url to add as a source root.
144    * @param isTestSource true if the file or directory is added as a test source root.
145    * @return the object representing the added root.
146    */
147   @NotNull
148   SourceFolder addSourceFolder(@NotNull String url, boolean isTestSource);
149
150   @NotNull
151   <P extends JpsElement>
152   SourceFolder addSourceFolder(@NotNull String url, @NotNull JpsModuleSourceRootType<P> type);
153
154   @NotNull
155   <P extends JpsElement>
156   SourceFolder addSourceFolder(@NotNull String url, @NotNull JpsModuleSourceRootType<P> type, @NotNull  P properties);
157
158   /**
159    * Removes a source or test source root from this content root.
160    *
161    * @param sourceFolder the source root to remove (must belong to this content root).
162    */
163   void removeSourceFolder(@NotNull SourceFolder sourceFolder);
164
165   void clearSourceFolders();
166
167   /**
168    * Adds an exclude root under the content root.
169    *
170    * @param file the file or directory to add as an exclude root.
171    * @return the object representing the added root.
172    */
173   ExcludeFolder addExcludeFolder(@NotNull VirtualFile file);
174
175   /**
176    * Adds an exclude root under the content root.
177    *
178    * @param url the file or directory url to add as an exclude root.
179    * @return the object representing the added root.
180    */
181   ExcludeFolder addExcludeFolder(@NotNull String url);
182
183   /**
184    * Removes an exclude root from this content root.
185    *
186    * @param excludeFolder the exclude root to remove (must belong to this content root).
187    */
188   void removeExcludeFolder(@NotNull ExcludeFolder excludeFolder);
189
190   /**
191    * Removes an exclude root from this content root.
192    * @param url url of the exclude root
193    * @return {@code true} if the exclude root was removed
194    */
195   boolean removeExcludeFolder(@NotNull String url);
196
197   void clearExcludeFolders();
198
199   /**
200    * Returns patterns for names of files which should be excluded from this content root. If name of a file under this content root matches
201    * any of the patterns it'll be excluded from the module, if name of a directory matches any of the patterns the directory and all of its
202    * contents will be excluded. '?' and '*' wildcards are supported.
203    */
204   @NotNull
205   List<String> getExcludePatterns();
206
207   void addExcludePattern(@NotNull String pattern);
208   void removeExcludePattern(@NotNull String pattern);
209   void setExcludePatterns(@NotNull List<String> patterns);
210
211   @NotNull
212   ModuleRootModel getRootModel();
213 }