fix "IDEA-221944 Deadlock on opening second project" and support preloading for proje...
[idea/community.git] / platform / projectModel-impl / src / com / intellij / openapi / components / PathMacroSubstitutor.java
1 // Copyright 2000-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
2 package com.intellij.openapi.components;
3
4 import org.jdom.Element;
5 import org.jetbrains.annotations.Contract;
6 import org.jetbrains.annotations.NotNull;
7 import org.jetbrains.annotations.Nullable;
8
9 /**
10  * Provides methods to convert paths from absolute to portable form and vice versa.
11  *
12  * @see com.intellij.openapi.application.PathMacros
13  */
14 public interface PathMacroSubstitutor {
15   /**
16    * Convert path to absolute by replacing all names of path variables by its values
17    */
18   @Contract("null -> null; !null -> !null")
19   String expandPath(@Nullable String text);
20
21   @Contract("null -> null; !null -> !null")
22   default String collapsePath(@Nullable String text) {
23     return collapsePath(text, false);
24   }
25
26   /**
27    * Convert paths inside {@code text} to portable form by replacing all values of path variables by their names.
28    * @param recursively if {@code true} all occurrences of paths inside {@code text} will be processed, otherwise {@code text} will be converted
29    *                    only if its entire content is a path (or URL)
30    */
31   @Contract("null, _ -> null; !null, _ -> !null")
32   String collapsePath(@Nullable String text, boolean recursively);
33
34   /**
35    * Process sub tags of {@code element} recursively and convert paths to absolute forms in all tag texts and attribute values.
36    */
37   void expandPaths(@NotNull Element element);
38
39   default void collapsePaths(@NotNull Element element) {
40     collapsePaths(element, false);
41   }
42
43   default void collapsePathsRecursively(@NotNull Element element) {
44     collapsePaths(element, true);
45   }
46
47   /**
48    * Process sub tags of {@code element} recursively and convert paths to portable forms in all tag texts and attribute values.
49    * @param recursively if {@code true} all occurrences of paths inside tag texts and attribute values will be processed, otherwise
50    * they will be converted only if their entire content is a path (or URL)
51    */
52   void collapsePaths(@NotNull Element element, boolean recursively);
53
54   @Contract("null -> null; !null -> !null")
55   default String collapsePathsRecursively(@Nullable String text) {
56     return collapsePath(text, true);
57   }
58 }