1 files changed, 126 insertions, 0 deletions
diff --git a/platform/dvcs-api/src/com/intellij/dvcs/repo/Repository.java b/platform/dvcs-api/src/com/intellij/dvcs/repo/Repository.java
new file mode 100644
index 000000000000..47cc17866c08
--- /dev/null
+++ b/platform/dvcs-api/src/com/intellij/dvcs/repo/Repository.java
@@ -0,0 +1,126 @@
+/*
+ * Copyright 2000-2013 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.intellij.dvcs.repo;
+
+import com.intellij.openapi.Disposable;
+import com.intellij.openapi.project.Project;
+import com.intellij.openapi.vcs.AbstractVcs;
+import com.intellij.openapi.vfs.VirtualFile;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * <p>
+ * Repository is a representation of a Git repository stored under the specified directory.
+ * It stores the information about the repository, which is frequently requested by other plugin components.
+ * All get-methods (like {@link #getCurrentRevision()}) are just getters of the correspondent fields and thus are very fast.
+ * </p>
+ * <p>
+ * The Repository is updated "externally" by the appropriate Updater class}, when correspondent {@code .git/ or .hg/} service files
+ * change.
+ * </p>
+ * <p>
+ * To force asynchronous update, it is enough to call {@link VirtualFile#refresh(boolean, boolean) refresh} on the root directory.
+ * </p>
+ * <p>
+ * To make a synchronous update of the repository call {@link #update()}.
+ * Updating requires reading from disk, so it may take some time, however, updating the whole community repository took ~10 ms at the time
+ * of measurement, so must be fast enough. Better not to be called in AWT though.
+ * <p/>
+ * <p>
+ * Getters and setters (update...()-methods) are not synchronized intentionally - to avoid live- and deadlocks.
+ * GitRepository is updated asynchronously,
+ * so even if the getters would have been synchronized, it wouldn't guarantee that they return actual values (as they are in .git).
+ * <br/>
+ * If one needs a really 100 % up-to-date value, one should call {@link #update()} and then get...().
+ * update() is a synchronous read from repository file (.git or .hg), so it is guaranteed to query the real value.
+ * </p>
+ *
+ * @author Nadya Zabrodina
+ */
+public interface Repository extends Disposable {
+
+
+  /**
+   * Current state of the repository.
+   */
+  enum State {
+    /**
+     * HEAD is on branch, no merge process is in progress (and no rebase as well).
+     */
+    NORMAL,
+    /**
+     * During merge (for instance, merge failed with conflicts that weren't immediately resolved).
+     */
+    MERGING {
+      @Override
+      public String toString() {
+        return "Merging";
+      }
+    },
+    /**
+     * During rebase.
+     */
+    REBASING {
+      @Override
+      public String toString() {
+        return "Rebasing";
+      }
+    },
+    /**
+     * Detached HEAD state, but not during rebase (for example, manual checkout of a commit hash).
+     */
+    DETACHED
+  }
+
+  @NotNull
+  VirtualFile getRoot();
+
+  @NotNull
+  String getPresentableUrl();
+
+  @NotNull
+  Project getProject();
+
+  @NotNull
+  State getState();
+
+  @Nullable
+  AbstractVcs getVcs();
+
+  /**
+   * Returns the hash of the revision, which HEAD currently points to.
+   * Returns null only in the case of a fresh repository, when no commit have been made.
+   */
+  @Nullable
+  String getCurrentRevision();
+
+  /**
+   * @return true if current repository is "fresh", i.e. if no commits have been made yet.
+   */
+  boolean isFresh();
+
+  /**
+   * Synchronously updates the Repository by reading information about it from disk (e.g. for Git: from .git/config and .git/refs/...)
+   */
+  void update();
+
+  /**
+   * Returns a detailed String representation suitable for logging purposes.
+   */
+  @NotNull
+  String toLogString();
+}