diff: improve javadoc for DiffRequestChain
[idea/community.git] / platform / diff-api / src / com / intellij / diff / chains / DiffRequestChain.java
1 // Copyright 2000-2021 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.diff.chains;
3
4 import com.intellij.diff.DiffDialogHints;
5 import com.intellij.openapi.project.Project;
6 import com.intellij.openapi.util.UserDataHolder;
7 import com.intellij.util.concurrency.annotations.RequiresEdt;
8 import org.jetbrains.annotations.NotNull;
9
10 import java.util.List;
11
12 /**
13  * Represents a list of changed files (ex: singular commit).
14  * The list is not supposed to be changed and can be shown multiple times.
15  * <p>
16  * Use {@link SimpleDiffRequestChain} and {@link com.intellij.openapi.vcs.changes.ui.ChangeDiffRequestChain} as typical implementations.
17  * <p>
18  * Use {@link AsyncDiffRequestChain} instead if loading the list of changed files is a slow operation
19  *
20  * @see DiffRequestSelectionChain
21  * @see com.intellij.diff.DiffManager#showDiff(Project, DiffRequestChain, DiffDialogHints)
22  * @see com.intellij.diff.impl.CacheDiffRequestChainProcessor
23  */
24 public interface DiffRequestChain extends UserDataHolder {
25   /**
26    * NB: if you're calling this method for an unknown chain type, you should be ready to handle {@link AsyncDiffRequestChain}.
27    */
28   @NotNull
29   @RequiresEdt
30   List<? extends DiffRequestProducer> getRequests();
31
32   @RequiresEdt
33   int getIndex();
34
35   /**
36    * @see com.intellij.diff.impl.CacheDiffRequestChainProcessor#setCurrentRequest
37    * @deprecated This method will not change selected position if chain was already shown.
38    */
39   @Deprecated(forRemoval = true)
40   @RequiresEdt
41   default void setIndex(int index) {
42   }
43 }