package com.atlassian.stash.internal.scm.git.submodule;

import com.atlassian.bitbucket.content.Submodule;
import com.atlassian.bitbucket.repository.Repository;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;

/**
 * Supports the concept of Repository submodules, which is a folder linked to an external Git repository at a specific
 * commit.
 *
 * @since 2.3
 */
public interface GitSubmoduleHelper {

    /**
     * Get all of the submodules associated with this repository.
     * </p>
     * Returns a <i>lazy</i> {@link Submodules}, which will only do the required lookup once when first inspected.
     * Therefore this method can be called safely even when the repository may not contain any submodules.
     *
     * @param repository the repository to use
     * @param objectId   an identifier (name or hash) for the branch, tag or commit where the modules should be retrieved
     * @param root       full relative directory path to the remote, or blank/null
     * @return a non-null lazy {@link Submodules} which can be used to lookup specific {@link Submodule submodules},
     *         indexed by their full path from the root of the repository
     */
    @Nonnull
    Submodules getSubmodules(@Nonnull Repository repository, @Nonnull String objectId, @Nullable String root);
}
