replaced <code></code> with more concise {@code}
[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.NotNull;
23
24 /**
25  * Extend this class to provide additional module-level properties which can be edited in Project Structure dialog. For ordinary module-level
26  * properties use {@link com.intellij.openapi.module.ModuleServiceManager module service} instead.
27  * <p/>
28  * If the inheritor implements {@link com.intellij.openapi.components.PersistentStateComponent} its state will be persisted in the module
29  * configuration file.
30  */
31 public abstract class ModuleExtension implements Disposable {
32   public static final ExtensionPointName<ModuleExtension> EP_NAME = ExtensionPointName.create("com.intellij.moduleExtension");
33
34   /**
35    * <b>Note:</b> don't call this method directly from client code. Use approach below instead:
36    * <pre>
37    *   ModifiableRootModel modifiableModel = ModuleRootManager.getInstance(module).getModifiableModel();
38    *   CompilerModuleExtension extension = modifiableModel.getModuleExtension(CompilerModuleExtension.class);
39    *   try {
40    *     // ...
41    *   }
42    *   finally {
43    *     modifiableModel.commit();
44    *   }
45    * </pre>
46    * The point is that call to commit() on CompilerModuleExtension obtained like
47    * {@code 'CompilerModuleExtension.getInstance(module).getModifiableModel(true)'} doesn't dispose the model.
48    * <p/>
49    * Call to {@code ModifiableRootModel.commit()} not only commits linked extensions but disposes them as well.
50    * 
51    * @param writable  flag which identifies if resulting model is writable
52    * @return          extension model
53    */
54   public abstract ModuleExtension getModifiableModel(final boolean writable);
55
56   public abstract void commit();
57
58   public abstract boolean isChanged();
59
60   /**
61    * Explicit comparator is used. To be deleted in 2018
62    */
63   @Deprecated
64   public int compareTo(@NotNull final ModuleExtension o) {
65     return getClass().getName().compareTo(o.getClass().getName());
66   }
67
68   /**
69    * @deprecated Please implement PersistentStateComponent instead.
70    */
71   @Deprecated
72   public void readExternal(@NotNull Element element) {
73     throw new UnsupportedOperationException("Implement PersistentStateComponent");
74   }
75
76   /**
77    * @deprecated Please implement PersistentStateComponent instead.
78    */
79   @Deprecated
80   public void writeExternal(@NotNull Element element) {
81     throw new UnsupportedOperationException("Implement PersistentStateComponent");
82   }
83 }