api: annotate classes and interfaces from project model API as NonExtendable
[idea/community.git] / platform / projectModel-api / src / com / intellij / openapi / roots / ModifiableRootModel.java
1 /*
2  * Copyright 2000-2017 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.project.Project;
20 import com.intellij.openapi.projectRoots.Sdk;
21 import com.intellij.openapi.roots.libraries.Library;
22 import com.intellij.openapi.roots.libraries.LibraryTable;
23 import com.intellij.openapi.vfs.VirtualFile;
24 import org.jetbrains.annotations.ApiStatus;
25 import org.jetbrains.annotations.NonNls;
26 import org.jetbrains.annotations.NotNull;
27 import org.jetbrains.annotations.Nullable;
28
29 /**
30  * Model of roots that should be used by clients to modify module roots.
31  *
32  * @author dsl
33  * @see ModuleRootManager#getModifiableModel()
34  */
35 @ApiStatus.NonExtendable
36 public interface ModifiableRootModel extends ModuleRootModel {
37   @NotNull
38   Project getProject();
39
40   /**
41    * Adds the specified file or directory as a content root.
42    *
43    * @param root root of a content
44    * @return new content entry
45    */
46   @NotNull
47   ContentEntry addContentEntry(@NotNull VirtualFile root);
48
49   /**
50    * Adds the specified file or directory as a content root.
51    *
52    * @param url root of a content
53    * @return new content entry
54    */
55   @NotNull
56   ContentEntry addContentEntry(@NotNull String url);
57
58   /**
59    * Remove the specified content root.
60    *
61    * @param entry the content root to remove.
62    */
63   void removeContentEntry(@NotNull ContentEntry entry);
64
65   /**
66    * Appends an order entry to the classpath.
67    *
68    * @param orderEntry the order entry to add.
69    */
70   void addOrderEntry(@NotNull OrderEntry orderEntry);
71
72   /**
73    * Creates an entry for a given library and adds it to order
74    *
75    * @param library the library for which the entry is created.
76    * @return newly created order entry for the library
77    */
78   @NotNull
79   LibraryOrderEntry addLibraryEntry(@NotNull Library library);
80
81   /**
82    * Adds an entry for invalid library.
83    */
84   @NotNull
85   LibraryOrderEntry addInvalidLibrary(@NotNull @NonNls String name, @NotNull String level);
86
87   @NotNull
88   ModuleOrderEntry addModuleOrderEntry(@NotNull Module module);
89
90   @NotNull
91   ModuleOrderEntry addInvalidModuleEntry(@NotNull String name);
92
93   @Nullable
94   ModuleOrderEntry findModuleOrderEntry(@NotNull Module module);
95
96   @Nullable
97   LibraryOrderEntry findLibraryOrderEntry(@NotNull Library library);
98
99   /**
100    * Removes order entry from an order.
101    */
102   void removeOrderEntry(@NotNull OrderEntry orderEntry);
103
104   void rearrangeOrderEntries(@NotNull OrderEntry[] newOrder);
105
106   void clear();
107
108   /**
109    * Commits changes to a <code>{@link ModuleRootManager}</code>.
110    * Should be invoked in a write action. After <code>commit()<code>, the model
111    * becomes read-only.
112    *
113    * Use of ModuleRootModificationUtil.updateModel() is recommended.
114    */
115   void commit();
116
117   /**
118    * Must be invoked for uncommitted models that are no longer needed.
119    *
120    * Use of ModuleRootModificationUtil.updateModel() is recommended.
121    */
122   void dispose();
123
124   /**
125    * Returns library table with module libraries.<br>
126    * <b>Note:</b> returned library table does not support listeners. Also one shouldn't invoke 'commit()' or 'dispose()' methods on it,
127    * it is automatically committed or disposed along with this {@link ModifiableRootModel} instance.
128    *
129    * @return library table to be modified
130    */
131   @NotNull
132   LibraryTable getModuleLibraryTable();
133
134   /**
135    * Sets JDK for this module to a specific value
136    */
137   void setSdk(@Nullable Sdk jdk);
138
139   /**
140    * Sets JDK name and type for this module.
141    * To be used when JDK with this name and type does not exist (e.g. when importing module configuration).
142    *
143    * @param sdkName JDK name
144    * @param sdkType JDK type
145    */
146   void setInvalidSdk(@NotNull String sdkName, String sdkType);
147
148   /**
149    * Makes this module inheriting JDK from its project
150    */
151   void inheritSdk();
152
153   boolean isChanged();
154
155   boolean isWritable();
156
157   <T extends OrderEntry> void replaceEntryOfType(@NotNull Class<T> entryClass, T entry);
158
159   @Nullable
160   String getSdkName();
161
162   boolean isDisposed();
163 }