replaced <code></code> with more concise {@code}
[idea/community.git] / platform / external-system-api / src / com / intellij / openapi / externalSystem / ExternalSystemAutoImportAware.java
1 /*
2  * Copyright 2000-2013 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.externalSystem;
17
18 import com.intellij.openapi.externalSystem.settings.AbstractExternalSystemSettings;
19 import com.intellij.openapi.externalSystem.settings.ExternalProjectSettings;
20 import com.intellij.openapi.project.Project;
21 import org.jetbrains.annotations.NotNull;
22 import org.jetbrains.annotations.Nullable;
23
24 import java.io.File;
25 import java.util.Collections;
26 import java.util.List;
27
28 /**
29  * External system integration provides 'auto-import' feature, i.e. it listens for external system config files changes
30  * and automatically runs external project refresh and sync.
31  * <p/>
32  * Only {@link AbstractExternalSystemSettings#getLinkedProjectsSettings() registered project's}
33  * {@link ExternalProjectSettings#getExternalProjectPath() config files} are processed by default. However, there is a possible case
34  * that there are other auxiliary config files/directories which modification should trigger external project refresh. This interface
35  * is supposed to handle that situation, i.e. any {@link ExternalSystemManager external system implementation} which requires
36  * the functionality described above should implement this interface.
37  * 
38  * @author Denis Zhdanov
39  * @since 6/7/13 6:44 PM
40  */
41 public interface ExternalSystemAutoImportAware {
42
43   /**
44    * This method serves to check if particular file/dir change should trigger external project refresh.
45    * <p/>
46    * <b>Note:</b> there is no need to handle here {@link ExternalProjectSettings#getExternalProjectPath() external project config files}
47    * known to the ide as that functionality is built-in. Only auxiliary files should be processed.
48    * <p/>
49    * <b>Note2:</b> this method is assume to be called rather often, that's why it's very important to return from it quickly.
50    * Caching and simple check algorithms are welcomed.
51    * 
52    * @param changedFileOrDirPath  changed file/dir path
53    * @param project               current project
54    * @return                      {@code null} if target change should not trigger external project refresh;
55    *                              path to config file of an external project which should be refreshed
56    */
57   @Nullable
58   String getAffectedExternalProjectPath(@NotNull String changedFileOrDirPath, @NotNull Project project);
59
60   default List<File> getAffectedExternalProjectFiles(String projectPath, @NotNull Project project) {
61     return Collections.emptyList();
62   }
63 }