api: annotate classes and interfaces from project model API as NonExtendable
[idea/community.git] / platform / projectModel-api / src / com / intellij / openapi / roots / OrderRootsEnumerator.java
1 /*
2  * Copyright 2000-2010 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 com.intellij.util.NotNullFunction;
20 import com.intellij.util.PathsList;
21 import org.jetbrains.annotations.ApiStatus;
22 import org.jetbrains.annotations.NotNull;
23
24 /**
25  * Interface for processing roots of OrderEntry's from {@link OrderEnumerator}.
26  *
27  * @see OrderEnumerator#classes()
28  * @see OrderEnumerator#sources()
29  *
30  * @author nik
31  */
32 @ApiStatus.NonExtendable
33 public interface OrderRootsEnumerator {
34   /**
35    * @return all roots processed by this enumerator
36    */
37   @NotNull
38   VirtualFile[] getRoots();
39
40   /**
41    * @return urls of all roots processed by this enumerator
42    */
43   @NotNull
44   String[] getUrls();
45
46   /**
47    * @return list of path to all roots processed by this enumerator
48    */
49   @NotNull
50   PathsList getPathsList();
51
52   /**
53    * Add all source roots processed by this enumerator to {@code list}
54    * @param list list
55    */
56   void collectPaths(@NotNull PathsList list);
57
58   /**
59    * If roots for this enumerator are already evaluated the cached result will be used. Otherwise roots will be evaluated and cached for
60    * subsequent calls. <p>
61    * Caching is not supported if {@link OrderEnumerator#satisfying}, {@link OrderEnumerator#using} or {@link #usingCustomRootProvider}
62    * option is used
63    * @return this instance
64    */
65   @NotNull
66   OrderRootsEnumerator usingCache();
67
68   /**
69    * This method makes sense only when dependencies of a module are processed (i.e. the enumerator instance is obtained by using {@link OrderEnumerator#orderEntries(com.intellij.openapi.module.Module)} or
70    * {@link ModuleRootModel#orderEntries()}). It instructs the enumerator to skip the output of the main module (if {@link com.intellij.openapi.roots.OrderEnumerator#productionOnly()}
71    * option is not specified then only the test output will be skipped)
72    *
73    * @return this instance
74    */
75   @NotNull
76   OrderRootsEnumerator withoutSelfModuleOutput();
77
78   /**
79    * Use {@code provider} to obtain roots of an library or jdk order entry instead of {@link OrderEntry#getFiles(OrderRootType)} method. Note that
80    * this option won't affect result of {@link #getUrls()} method
81    * @param provider function to evaluate roots for an order entry
82    * @return this instance
83    */
84   @NotNull
85   OrderRootsEnumerator usingCustomRootProvider(@NotNull NotNullFunction<? super OrderEntry, VirtualFile[]> provider);
86 }