/**
 * The MIT License
 *
 * Copyright (c) 2010-2011 Sonatype, Inc. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */

package org.hudsonci.service;

import com.google.inject.ImplementedBy;
import hudson.model.AbstractProject;
import hudson.model.Item;
import hudson.model.TopLevelItem;

import java.io.InputStream;
import java.util.Collection;
import java.util.List;
import java.util.UUID;

import org.hudsonci.service.internal.ProjectServiceImpl;

/**
 * Service API related to Projects and Job models, such as that by {@link AbstractProject}.
 *
 * @author plynch
 * @since 2.1.0
 */
@ImplementedBy(ProjectServiceImpl.class)
public interface ProjectService
{
    /**
     * Get the project identified by a UUID.
     *
     * @param id UUID identifier of the project to get
     * @return the project associated with the UUID
     * @throws ProjectNotFoundException if a project cannot be found for the given UUID
     */
    AbstractProject<?, ?> getProject(final UUID id);

    /**
     * Get the project identified by a UUID.
     *
     * @param id UUID identifier of the project to get
     * @return the project associated with the UUID or null if not found
     */
    AbstractProject<?, ?> findProject(final UUID id);

    /**
     * Get the project identified by a full project name.
     *
     * The current thread context must have {@link Item#READ} permission on the project in order to
     * get it.
     *
     * @param projectFullName full project name as reported by {@link AbstractProject#getFullName}
     * @return the project associated with projectFullName
     * @throws ProjectNotFoundException if a project with the specified full name does not exist
     */
    AbstractProject<?, ?> getProjectByFullName(String projectFullName);

    /**
     * Find the project identified by a full project name.
     *
     * The current thread context must have {@link Item#READ} permission on the project in order to
     * find it.
     *
     * @param projectFullName full project name as reported by {@link AbstractProject#getFullName}
     * @return the project associated with projectFullName or null if not found
     */
    AbstractProject<?, ?> findProjectByFullName(String projectFullName);

    /**
     * Check if a project with given name as reported by {@link AbstractProject#getName}
     * already exists in the system.
     *
     * In order to determine if a project exists, the current thread context must have {@link Item#READ}
     * permission on it.
     *
     * @param projectName project name to lookup
     * @return true if a project with the specified name is readable and exists in the system
     */
    boolean projectExists(String projectName);

    /**
     * Get a list of all projects of a specific {@literal type} in the system.
     *
     * <p>The current thread must have {@link Item#READ} permission
     * on each project returned and {@link Item#READ} permission on the {@link hudson.model.Node}
     * where the projects reside.
     *
     * @return a list of all projects implemented by type T
     */
    @SuppressWarnings("rawtypes")
    List<AbstractProject> getAllProjects();

    /**
     * Copy a source project to a new project which will be named the
     * value of {@literal targetProjectName}
     *
     * <p>The current thread must have {@link Item#EXTENDED_READ} permission
     * on {@literal src} and {@link Item#CREATE} permission on the {@link hudson.model.Node}
     * where the project will be copied too, in order for the operation to succeed.
     *
     * @param <T> the type of new target project
     * @param src source project to copy from
     * @param targetProjectName the name to create the new project with
     * @return the newly created target project
     * @throws SystemIntegrityViolationException if a project already exists with the targetProjectName
     * @throws ServiceRuntimeException if there was an unexpected problem creating the project
     */
    <T extends AbstractProject<?, ?>> T copyProject(T src, String targetProjectName);

    /**
     * Create a new project in the system from XML.
     *
     * <p>The current thread must have {@link hudson.model.Item#CREATE} permission on the
     * {@link hudson.model.Node} where the project will created, in order for the operation to
     * succeed.
     *
     * <p>Buffering or closing of the InputStream should be done outside of this method.
     *
     * @param projectName the name of the new project.
     * @param xml XML document describing the new project
     * @return a {@link hudson.model.TopLevelItem} representing the newly created project
     * @throws SystemIntegrityViolationException if a project already exists with projectName
     * @throws ServiceRuntimeException if there was an unexpected problem creating the project
     */
    TopLevelItem createProjectFromXML(String projectName, InputStream xml);

    /**
     * Find and return a project with the given name ( as defined by {@link AbstractProject#getName} )
     * , or return {@literal null} if one cannot be found.
     *
     * <p>The current thread context must have {@link Item#READ} permission on the project in order to find it.
     *
     * @param projectName
     * @return a project for the specified name if it is readable and exists, otherwise null
     */
    AbstractProject<?,?> findProject(String projectName);

    /**
     * Tries to find a project with the given name as defined by {@link AbstractProject#getName}.
     *
     * <p>The current thread context must have {@link Item#READ} permission on the project in order to find it.
     *
     * @param projectName the project name for the project
     * @return an AbstractProject for the specified name if one exists, never null
     * @throws ProjectNotFoundException if the project cannot be found
     */
    AbstractProject<?,?> getProject(String projectName);

    /**
     * Return a collection of all project names in the system.
     *
     * <p>{@link Item#READ} access is required to return a job name in the collection.
     *
     * @return a collection, never null, of all project names in the system
     */
    Collection<String> getProjectNames();
}