Updating versions of project dependencies: rkernelVersion->master.130
[idea/community.git] / platform / projectModel-api / src / com / intellij / openapi / roots / ModuleExtension.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
17 package com.intellij.openapi.roots;
18
19 import com.intellij.openapi.Disposable;
20 import com.intellij.openapi.extensions.ExtensionPointName;
21 import org.jdom.Element;
22 import org.jetbrains.annotations.ApiStatus;
23 import org.jetbrains.annotations.NotNull;
24
25 /**
26  * Extend this class to provide additional module-level properties which can be edited in Project Structure dialog. For ordinary module-level
27  * properties use {@link com.intellij.openapi.module.ModuleServiceManager module service} instead.
28  * <p/>
29  * If the inheritor implements {@link com.intellij.openapi.components.PersistentStateComponent} its state will be persisted in the module
30  * configuration file.
31  */
32 public abstract class ModuleExtension implements Disposable {
33   /**
34    * @deprecated don't enumerate extensions in the plugin, use {@link ModuleRootModel#getModuleExtension(Class)} instead
35    */
36   @Deprecated
37   public static final ExtensionPointName<ModuleExtension> EP_NAME = ExtensionPointName.create("com.intellij.moduleExtension");
38
39   /**
40    * <b>Note:</b> don't call this method directly from client code. Use approach below instead:
41    * <pre>
42    *   ModifiableRootModel modifiableModel = ModuleRootManager.getInstance(module).getModifiableModel();
43    *   CompilerModuleExtension extension = modifiableModel.getModuleExtension(CompilerModuleExtension.class);
44    *   try {
45    *     // ...
46    *   }
47    *   finally {
48    *     modifiableModel.commit();
49    *   }
50    * </pre>
51    * The point is that call to commit() on CompilerModuleExtension obtained like
52    * {@code 'CompilerModuleExtension.getInstance(module).getModifiableModel(true)'} doesn't dispose the model.
53    * <p/>
54    * Call to {@code ModifiableRootModel.commit()} not only commits linked extensions but disposes them as well.
55    * 
56    * @param writable  flag which identifies if resulting model is writable
57    * @return          extension model
58    */
59   @ApiStatus.OverrideOnly
60   @NotNull
61   public abstract ModuleExtension getModifiableModel(final boolean writable);
62
63   public abstract void commit();
64
65   public abstract boolean isChanged();
66
67   /**
68    * @deprecated Please implement PersistentStateComponent instead.
69    */
70   @Deprecated
71   public void readExternal(@NotNull Element element) {
72     throw new UnsupportedOperationException("Implement PersistentStateComponent");
73   }
74
75   /**
76    * @deprecated Please implement PersistentStateComponent instead.
77    */
78   @Deprecated
79   public void writeExternal(@NotNull Element element) {
80     throw new UnsupportedOperationException("Implement PersistentStateComponent");
81   }
82 }