Known duplicates for macOS system shortcuts keymap
[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)}. Note that methods which change the state can be called
32  * only on instances of {@link ContentEntry} obtained from {@link ModifiableRootModel}. Calling these methods on instances obtained from
33  * {@code ModuleRootManager.getInstance(module).getContentEntries()} may lead to failed assertion at runtime.
34  *
35  * @author dsl
36  * @see ModuleRootModel#getContentEntries()
37  * @see ModifiableRootModel#addContentEntry(VirtualFile)
38  */
39 @ApiStatus.NonExtendable
40 public interface ContentEntry extends Synthetic {
41   /**
42    * Returns the root file or directory for the content root, if it is valid.
43    *
44    * @return the content root file or directory, or null if content entry is invalid.
45    */
46   @Nullable
47   VirtualFile getFile();
48
49   /**
50    * Returns the URL of content root.
51    * To validate returned roots, use
52    * <code>{@link com.intellij.openapi.vfs.VirtualFileManager#findFileByUrl(String)}</code>
53    *
54    * @return URL of content root, that should never be null.
55    */
56   @NotNull
57   String getUrl();
58
59   /**
60    * Returns the list of source roots under this content root.
61    *
62    * @return list of this {@code ContentEntry} {@link SourceFolder}s
63    */
64   SourceFolder @NotNull [] getSourceFolders();
65
66   /**
67    * @param rootType type of accepted source roots
68    * @return list of source roots of the specified type containing in this content root
69    */
70   @NotNull
71   List<SourceFolder> getSourceFolders(@NotNull JpsModuleSourceRootType<?> rootType);
72
73   /**
74    *
75    * @param rootTypes types of accepted source roots
76    * @return list of source roots of the specified types containing in this content root
77    */
78   @NotNull
79   List<SourceFolder> getSourceFolders(@NotNull Set<? extends JpsModuleSourceRootType<?>> rootTypes);
80
81   /**
82    * Returns the list of files and directories for valid source roots under this content root.
83    *
84    * @return list of all valid source roots.
85    */
86   VirtualFile @NotNull [] 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   ExcludeFolder @NotNull [] getExcludeFolders();
94
95   /**
96    * @return list of URLs for all excluded roots under this content root including synthetic excludes like the module output
97    */
98   @NotNull
99   List<String> getExcludeFolderUrls();
100
101   /**
102    * Returns the list of files and directories for valid excluded roots under this content root.
103    *
104    * @return list of all valid exclude roots including synthetic excludes like the module output
105    */
106   VirtualFile @NotNull [] getExcludeFolderFiles();
107
108   /**
109    * Adds a source or test source root under the content root. This method may be called only on an instance obtained from {@link ModifiableRootModel}.
110    *
111    * @param file         the file or directory to add as a source root.
112    * @param isTestSource true if the file or directory is added as a test source root.
113    * @return the object representing the added root.
114    */
115   @NotNull
116   SourceFolder addSourceFolder(@NotNull VirtualFile file, boolean isTestSource);
117
118   /**
119    * Adds a source or test source root with the specified package prefix under the content root. This method may be called only on an
120    * instance obtained from {@link ModifiableRootModel}.
121    *
122    * @param file          the file or directory to add as a source root.
123    * @param isTestSource  true if the file or directory is added as a test source root.
124    * @param packagePrefix the package prefix for the root to add, or an empty string if no
125    *                      package prefix is required.
126    * @return the object representing the added root.
127    */
128   @NotNull
129   SourceFolder addSourceFolder(@NotNull VirtualFile file, boolean isTestSource, @NotNull String packagePrefix);
130
131   /**
132    * Adds a source root of the given type with the given properties. This method may be called only on an instance obtained from
133    * {@link ModifiableRootModel}.
134    */
135   @NotNull <P extends JpsElement>
136   SourceFolder addSourceFolder(@NotNull VirtualFile file, @NotNull JpsModuleSourceRootType<P> type, @NotNull P properties);
137
138   /**
139    * Adds a source root of the given type with the default properties. This method may be called only on an instance obtained from
140    * {@link ModifiableRootModel}.
141    */
142   @NotNull <P extends JpsElement>
143   SourceFolder addSourceFolder(@NotNull VirtualFile file, @NotNull JpsModuleSourceRootType<P> type);
144
145   /**
146    * Adds a source or test source root under the content root. This method may be called only on an instance obtained from {@link ModifiableRootModel}.
147    *
148    * @param url          the file or directory url to add as a source root.
149    * @param isTestSource true if the file or directory is added as a test source root.
150    * @return the object representing the added root.
151    */
152   @NotNull
153   SourceFolder addSourceFolder(@NotNull String url, boolean isTestSource);
154
155   /**
156    * Adds a source root of the given type with the default properties. This method may be called only on an instance obtained from
157    * {@link ModifiableRootModel}.
158    */
159   @NotNull <P extends JpsElement>
160   SourceFolder addSourceFolder(@NotNull String url, @NotNull JpsModuleSourceRootType<P> type);
161
162   /**
163    * Adds a source root of the given type with given properties. This method may be called only on an instance obtained from
164    * {@link ModifiableRootModel}.
165    */
166   @NotNull <P extends JpsElement>
167   SourceFolder addSourceFolder(@NotNull String url, @NotNull JpsModuleSourceRootType<P> type, @NotNull P properties);
168
169   /**
170    * Removes a source or test source root from this content root. This method may be called only on an instance obtained from {@link ModifiableRootModel}.
171    *
172    * @param sourceFolder the source root to remove (must belong to this content root).
173    */
174   void removeSourceFolder(@NotNull SourceFolder sourceFolder);
175
176   /**
177    * Removes all source roots. This method may be called only on an instance obtained from {@link ModifiableRootModel}.
178    */
179   void clearSourceFolders();
180
181   /**
182    * Adds an exclude root under the content root. This method may be called only on an instance obtained from {@link ModifiableRootModel}.
183    *
184    * @param file the file or directory to add as an exclude root.
185    * @return the object representing the added root.
186    */
187   @NotNull
188   ExcludeFolder addExcludeFolder(@NotNull VirtualFile file);
189
190   /**
191    * Adds an exclude root under the content root. This method may be called only on an instance obtained from {@link ModifiableRootModel}.
192    *
193    * @param url the file or directory url to add as an exclude root.
194    * @return the object representing the added root.
195    */
196   @NotNull
197   ExcludeFolder addExcludeFolder(@NotNull String url);
198
199   /**
200    * Removes an exclude root from this content root. This method may be called only on an instance obtained from {@link ModifiableRootModel}.
201    *
202    * @param excludeFolder the exclude root to remove (must belong to this content root).
203    */
204   void removeExcludeFolder(@NotNull ExcludeFolder excludeFolder);
205
206   /**
207    * Removes an exclude root from this content root. This method may be called only on an instance obtained from {@link ModifiableRootModel}.
208    *
209    * @param url url of the exclude root
210    * @return {@code true} if the exclude root was removed
211    */
212   boolean removeExcludeFolder(@NotNull String url);
213
214   /**
215    * Removes all excluded folders. This method may be called only on an instance obtained from {@link ModifiableRootModel}.
216    */
217   void clearExcludeFolders();
218
219   /**
220    * Returns patterns for names of files which should be excluded from this content root. If name of a file under this content root matches
221    * 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
222    * contents will be excluded. '?' and '*' wildcards are supported.
223    */
224   @NotNull
225   List<String> getExcludePatterns();
226
227   /**
228    * Adds a pattern for names of files which should be excluded. This method may be called only on an instance obtained from {@link ModifiableRootModel}.
229    */
230   void addExcludePattern(@NotNull String pattern);
231
232   /**
233    * Removes a pattern for names of files which should be excluded. This method may be called only on an instance obtained from {@link ModifiableRootModel}.
234    */
235   void removeExcludePattern(@NotNull String pattern);
236
237   /**
238    * Sets patterns for names of files which should be excluded. This method may be called only on an instance obtained from {@link ModifiableRootModel}.
239    */
240   void setExcludePatterns(@NotNull List<String> patterns);
241
242   @NotNull
243   ModuleRootModel getRootModel();
244 }