package com.atlassian.bitbucket.mesh.git.submodule;

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

/**
 * Encapsulates a repository's configured submodules.
 */
public interface Submodules {

    /**
     * Retrieves the submodule for the specified path, <i>if it has a valid configuration</i>. The provided
     * {@code contentId} identifies the specific commit within the <i>external</i> repository for the
     * submodule.
     * <p>
     * The {@code path} to use may be relative if a {@code basePath} was provided to {@link SubmoduleManager#get}
     * when submodules were retrieved.
     *
     * @param path      the submodule's path
     * @param contentId the submodule's content ID, which indicates the commit within the <i>external</i>
     *                  repository that the submodule should fetch
     * @return the matching submodule, or {@code null} if the submodule's configuration is missing or is
     *         otherwise invalid (e.g. has no URL defined)
     */
    @Nullable
    Submodule get(@Nonnull String path, @Nonnull String contentId);
}
