change assumptions about events after renaming root directory: now "roots changed...
[idea/community.git] / platform / projectModel-api / src / com / intellij / openapi / roots / OrderEntry.java
1 /*
2  * Copyright 2000-2012 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.vfs.VirtualFile;
20 import org.jetbrains.annotations.ApiStatus;
21 import org.jetbrains.annotations.Nls;
22 import org.jetbrains.annotations.NotNull;
23 import org.jetbrains.annotations.Nullable;
24
25 /**
26  * Represents an entry in the classpath of a module (as shown in the "Order/Export" page
27  * of the module configuration dialog).
28  *
29  * @author dsl
30  */
31 @ApiStatus.NonExtendable
32 public interface OrderEntry extends Synthetic, Comparable<OrderEntry> {
33   /**
34    * The empty array of order entries which can be reused to avoid unnecessary allocations.
35    */
36   OrderEntry[] EMPTY_ARRAY = new OrderEntry[0];
37
38   /**
39    * Returns list of root {@link VirtualFile}s of given type for this entry.
40    * Those files should be traversed in order they are returned in.
41    * Note that actual OrderEntry (as seen in UI) may also contain invalid roots.
42    * If you want to get list of all roots, use {@link #getUrls(OrderRootType)} method. <br>
43    *
44    * Note that list of roots is project dependent.
45    *
46    * @param type  required root type.
47    * @return list of virtual files.
48    * @see #getUrls(OrderRootType)
49    */
50   VirtualFile @NotNull [] getFiles(@NotNull OrderRootType type);
51
52   /**
53    * Returns list of roots of given type for this entry. To validate returned roots,
54    * use {@link com.intellij.openapi.vfs.VirtualFileManager#findFileByUrl(String)} <br>
55    *
56    * Note that list of roots is project-dependent.
57    *
58    * @param rootType the type of roots which should be returned.
59    * @return the list of roots of the specified type.
60    */
61   String @NotNull [] getUrls(@NotNull OrderRootType rootType);
62
63   /**
64    * Returns the user-visible name of this OrderEntry.
65    *
66    * @return name of this OrderEntry to be shown to user.
67    */
68   @NotNull
69   @Nls(capitalization = Nls.Capitalization.Title) String getPresentableName();
70
71   /**
72    * Checks whether this order entry is invalid for some reason. Note that entry being valid
73    * does not necessarily mean that all its roots are valid.
74    *
75    * @return true if entry is valid, false otherwise.
76    */
77   boolean isValid();
78
79   /**
80    * Returns the module to which the entry belongs.
81    *
82    * @return the module instance.
83    */
84   @NotNull
85   Module getOwnerModule();
86
87   /**
88    * Accepts the specified order entries visitor.
89    *
90    * @param policy       the visitor to accept.
91    * @param initialValue the default value to be returned by the visit process.
92    * @return the value returned by the visitor.
93    */
94   <R> R accept(@NotNull RootPolicy<R> policy, @Nullable R initialValue);
95 }