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