PathMacros: more javadocs
[idea/community.git] / platform / projectModel-api / src / com / intellij / openapi / application / PathMacros.java
1 /*
2  * Copyright 2000-2014 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.application;
17
18 import com.intellij.openapi.components.ServiceManager;
19 import org.jetbrains.annotations.NotNull;
20
21 import java.util.Collection;
22 import java.util.Set;
23
24 /**
25  * Stores predefined and custom (user-defined) path variables. Path variables are used to convert paths from absolute to portable form and
26  * vice versa. It allows us to reuse project configuration files on different machines.
27  * <p>
28  * In order to make a path (or URL) portable the serialization subsystem replaces its prefix by name of a corresponding path variable.
29  * There are {@link #getSystemMacroNames() predefined path variables} and also it's possible to specify {@link #getUserMacroNames() custom path variables}.
30  * </p>
31  */
32 public abstract class PathMacros {
33   public static PathMacros getInstance() {
34     return ServiceManager.getService(PathMacros.class);
35   }
36
37   public abstract Set<String> getAllMacroNames();
38
39   public abstract String getValue(String name);
40
41   public abstract void setMacro(String name, String value);
42
43   /**
44    * Obsolete macros that are to be removed gently from the project files. They can be read, but not written again. Not persisted
45    */
46   public abstract void addLegacyMacro(@NotNull String name, @NotNull String value);
47
48   public abstract void removeMacro(String name);
49
50   public abstract Set<String> getUserMacroNames();
51
52   public abstract Set<String> getSystemMacroNames();
53
54   public abstract Collection<String> getIgnoredMacroNames();
55
56   public abstract void setIgnoredMacroNames(@NotNull final Collection<String> names);
57
58   public abstract void addIgnoredMacro(@NotNull final String name);
59
60   public abstract boolean isIgnoredMacroName(@NotNull final String macro);
61
62   public abstract void removeAllMacros();
63
64   public abstract Collection<String> getLegacyMacroNames();
65 }