package com.atlassian.bitbucket.build;

import com.atlassian.bitbucket.AuthorisationException;
import com.atlassian.bitbucket.commit.Commit;
import com.atlassian.bitbucket.util.Page;

import javax.annotation.Nonnull;
import java.util.Collection;
import java.util.Map;

/**
 * Manages build {@link BuildStatus statuses}.
 */
public interface BuildStatusService {

    /**
     * Retrieves a page of {@link BuildStatus build statuses} associated with the specified commit.
     *
     * @param commitId the {@link Commit#getId() ID} of the commit to retrieve builds for
     * @return a page of build statuses
     * @throws AuthorisationException if the current user is not licensed
     */
    @Nonnull
    Page<BuildStatus> findAll(@Nonnull String commitId);

    /**
     * Retrieves a {@link BuildSummary summary} of all the builds associated with the specified commit.
     *
     * @param commitId the {@link Commit#getId() ID} of the commit to retrieve a summary for
     * @return {@link BuildSummary stats} for all the builds associated with the {@code commitId}.
     * @throws AuthorisationException if the current user is not licensed
     */
    @Nonnull
    BuildSummary getSummary(@Nonnull String commitId);

    /**
     * Retrieves {@link BuildSummary summaries} for the builds associated with all of the specified commits. If
     * any of the specified commits do not have builds associated with them, their ID will not be included in
     * the returned {@code Map}.
     *
     * @return a map from {@code commit IDs} to {@link BuildSummary summaries}, which can have a length smaller than
     *         the number of specified commits if any do not have build statuses associated with them.
     * @throws AuthorisationException if the current user is not licensed
     * @see #getSummary(String)
     */
    @Nonnull
    Map<String, BuildSummary> getSummaries(@Nonnull Collection<String> commitIds);

    /**
     * Sets the build status for a commit, replacing any existing status <em>with the same
     * <u>{@link BuildStatus#getKey key}</u></em>
     *
     * @param request describes the build status and the commit it should be associated with
     * @throws AuthorisationException if the current user is not licensed
     */
    void set(@Nonnull BuildStatusSetRequest request);
}
