package com.atlassian.bitbucket.internal.importer;

import com.atlassian.bitbucket.util.Page;
import com.atlassian.bitbucket.util.PageRequest;

import javax.annotation.Nonnull;

/**
 * A service for interacting with external repository sources.
 */
public interface ExternalRepositoryService {

    /**
     * Get the missing OAuth-Scopes(required for importing a repository)
     * for the user as per the credentials in {@link ExternalRequest)
     *
     * @param request a request object describing the external request
     * @return the missing oauth scopes for importing a repository
     * @throws UnsupportedSourceException if the specified source type is not supported
     * @see ExternalRequest
     */
    @Nonnull
    Iterable<OAuthScope> getMissingOAuthScopes(@Nonnull ExternalRequest request);

    /**
     * Get the user specified in the {@link ExternalRequest#getCredential}
     *
     * @param request a request object describing the external request
     * @return the currently authenticated external user
     * @throws UnsupportedSourceException if the specified source type is not supported
     * @see ExternalRequest
     */
    @Nonnull
    ExternalUser getUser(ExternalRequest request);

    /**
     * Searches for {@link ExternalOwner owners} that match the provided
     * {@link ExternalOwnerSearchRequest request}.
     *
     * @param request     a request object describing the external owners to return
     * @param pageRequest the bounds of the page
     * @return a page containing 0 or more {@link ExternalOwner external owners} that match the provided
     * {@link ExternalOwnerSearchRequest criteria}
     * @throws UnsupportedSourceException if the specified source type is not supported
     * @see ExternalOwnerSearchRequest
     */
    @Nonnull
    Page<ExternalOwner> searchOwners(@Nonnull ExternalOwnerSearchRequest request, @Nonnull PageRequest pageRequest);

    /**
     * Searches for {@link ExternalRepository external repositories} that match the provided
     * {@link ExternalRepositorySearchRequest request}.
     *
     * @param request     a request object describing the external repositories to return
     * @param pageRequest the bounds of the page
     * @return a page containing 0 or more {@link ExternalRepository external repositories} that match the provided
     * {@link ExternalRepositorySearchRequest criteria}
     * @throws UnsupportedSourceException if the specified source type is not supported
     * @see ExternalRepositorySearchRequest
     */
    @Nonnull
    Page<ExternalRepository> searchRepositories(@Nonnull ExternalRepositorySearchRequest request,
                                                @Nonnull PageRequest pageRequest);
}
