package org.apache.maven.scm.manager;

 /*

  * Licensed to the Apache Software Foundation (ASF) under one

  * or more contributor license agreements.  See the NOTICE file

  * distributed with this work for additional information

  * regarding copyright ownership.  The ASF licenses this file

  * to you under the Apache License, Version 2.0 (the

  * "License"); you may not use this file except in compliance

  * with the License.  You may obtain a copy of the License at

  *

  * http://www.apache.org/licenses/LICENSE-2.0

  *

  * Unless required by applicable law or agreed to in writing,

  * software distributed under the License is distributed on an

  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY

  * KIND, either express or implied.  See the License for the

  * specific language governing permissions and limitations

  * under the License.

  */

 import org.apache.maven.scm.ScmBranch;

 import org.apache.maven.scm.ScmException;

 import org.apache.maven.scm.ScmFileSet;

 import org.apache.maven.scm.ScmVersion;

 import org.apache.maven.scm.command.add.AddScmResult;

 import org.apache.maven.scm.command.blame.BlameScmResult;

 import org.apache.maven.scm.command.branch.BranchScmResult;

 import org.apache.maven.scm.command.changelog.ChangeLogScmResult;

 import org.apache.maven.scm.command.checkin.CheckInScmResult;

 import org.apache.maven.scm.command.checkout.CheckOutScmResult;

 import org.apache.maven.scm.command.diff.DiffScmResult;

 import org.apache.maven.scm.command.edit.EditScmResult;

 import org.apache.maven.scm.command.export.ExportScmResult;

 import org.apache.maven.scm.command.list.ListScmResult;

 import org.apache.maven.scm.command.mkdir.MkdirScmResult;

 import org.apache.maven.scm.command.remove.RemoveScmResult;

 import org.apache.maven.scm.command.status.StatusScmResult;

 import org.apache.maven.scm.command.tag.TagScmResult;

 import org.apache.maven.scm.command.unedit.UnEditScmResult;

 import org.apache.maven.scm.command.update.UpdateScmResult;

 import org.apache.maven.scm.provider.ScmProvider;

 import org.apache.maven.scm.repository.ScmRepository;

 import org.apache.maven.scm.repository.ScmRepositoryException;

 import org.apache.maven.scm.repository.UnknownRepositoryStructure;

 import java.io.File;

 import java.util.Date;

 import java.util.List;

 /**

  * @author <a href="mailto:trygvis@inamo.no">Trygve Laugst&oslash;l</a>

  * @author <a href="mailto:brett@apache.org">Brett Porter</a>

  * @author <a href="mailto:evenisse@apache.org">Emmanuel Venisse</a>

  * @author Olivier Lamy

  * @version $Id: ScmManager.java 1054215 2011-01-01 09:45:44Z olamy $

  */

 public interface ScmManager

 {

     String ROLE = ScmManager.class.getName();

     // ----------------------------------------------------------------------

     // Repository

     // ----------------------------------------------------------------------

     /**

      * Generate a SCMRepository from a SCM url.

      * 

      * @param scmUrl the scm url

      * @return The scm repository

      * @throws ScmRepositoryException if an error occurs in the scm repository construction

      * @throws NoSuchScmProviderException if the provider doesn't exist

      */

     ScmRepository makeScmRepository( String scmUrl )

         throws ScmRepositoryException, NoSuchScmProviderException;

     ScmRepository makeProviderScmRepository( String providerType, File path )

         throws ScmRepositoryException, UnknownRepositoryStructure, NoSuchScmProviderException;

     /**

      * Validate a SCM URL.

      * 

      * @param scmUrl the SCM URL to validate

      * @return <code>List</code> of <code>String</code> objects with the messages returned by the SCM provider

      */

     List<String> validateScmRepository( String scmUrl );

     ScmProvider getProviderByUrl( String scmUrl )

         throws ScmRepositoryException, NoSuchScmProviderException;

     /**

      * Returns the default provider registered for this providerType or a specific implementation if the

      * 'maven.scm.provider.providerType.implementation' system property is defined. For example:

      * maven.scm.provider.cvs.implementation=cvs_native

      * 

      * @param providerType The provider type (cvs, svn...)

      * @return The scm provider

      * @throws NoSuchScmProviderException if the provider doesn't exist

      */

     ScmProvider getProviderByType( String providerType )

         throws NoSuchScmProviderException;

     ScmProvider getProviderByRepository( ScmRepository repository )

         throws NoSuchScmProviderException;

     /**

      * Set a provider to be used for a type of SCM. If there was already a designed provider for that type it will be

      * replaced.

      * 

      * @param providerType the type of SCM, eg. <code>svn</code>, <code>cvs</code>

      * @param provider the provider that will be used for that SCM type

      */

     void setScmProvider( String providerType, ScmProvider provider );

     /**

      * Set the provider implementation

      * 

      * @param providerType The provider type, eg. <code>cvs</code>

      * @param providerImplementation The provider implementation (the role-hint of the provider), eg. <code>cvs</code>,

      *            <code>cvs_native</code>

      */

     void setScmProviderImplementation( String providerType, String providerImplementation );

     /**

      * Adds the given files to the source control system

      * 

      * @param repository the source control system

      * @param fileSet the files to be added

      * @return an {@link org.apache.maven.scm.command.add.AddScmResult} that contains the files that have been added

      * @throws org.apache.maven.scm.ScmException

      */

     AddScmResult add( ScmRepository repository, ScmFileSet fileSet )

         throws ScmException;

     /**

      * Adds the given files to the source control system

      * 

      * @param repository the source control system

      * @param fileSet the files to be added

      * @param message a string that is a comment on the new added file

      * @return an {@link AddScmResult} that contains the files that have been added

      * @throws ScmException if any

      */

     AddScmResult add( ScmRepository repository, ScmFileSet fileSet, String message )

         throws ScmException;

     /**

      * Branch (or label in some systems) will create a branch of the source file with a certain branch name

      * 

      * @param repository the source control system

      * @param fileSet the files to branch. Implementations can also give the changes from the

      *            {@link org.apache.maven.scm.ScmFileSet#getBasedir()} downwards.

      * @param branchName the branch name to apply to the files

      * @return

      * @throws ScmException if any

      */

     BranchScmResult branch( ScmRepository repository, ScmFileSet fileSet, String branchName )

         throws ScmException;

     /**

      * Branch (or label in some systems) will create a branch of the source file with a certain branch name

      * 

      * @param repository the source control system

      * @param fileSet the files to branch. Implementations can also give the changes from the

      *            {@link org.apache.maven.scm.ScmFileSet#getBasedir()} downwards.

      * @param branchName the branch name to apply to the files

      * @param message the commit message used for the tag creation

      * @return

      * @throws ScmException if any

      */

     BranchScmResult branch( ScmRepository repository, ScmFileSet fileSet, String branchName, String message )

         throws ScmException;

     /**

      * Returns the changes that have happend in the source control system in a certain period of time. This can be

      * adding, removing, updating, ... of files

      * 

      * @param repository the source control system

      * @param fileSet the files to know the changes about. Implementations can also give the changes from the

      *            {@link org.apache.maven.scm.ScmFileSet#getBasedir()} downwards.

      * @param startDate the start date of the period

      * @param endDate the end date of the period

      * @param numDays the number days before the current time if startdate and enddate are null

      * @param branch the branch/tag

      * @return The SCM result of the changelog command

      * @throws ScmException if any

      */

     ChangeLogScmResult changeLog( ScmRepository repository, ScmFileSet fileSet, Date startDate, Date endDate,

                                   int numDays, ScmBranch branch )

         throws ScmException;

     /**

      * Returns the changes that have happend in the source control system in a certain period of time. This can be

      * adding, removing, updating, ... of files

      * 

      * @param repository the source control system

      * @param fileSet the files to know the changes about. Implementations can also give the changes from the

      *            {@link org.apache.maven.scm.ScmFileSet#getBasedir()} downwards.

      * @param startDate the start date of the period

      * @param endDate the end date of the period

      * @param numDays the number days before the current time if startdate and enddate are null

      * @param branch the branch/tag

      * @param datePattern the date pattern use in changelog output returned by scm tool

      * @return The SCM result of the changelog command

      * @throws ScmException if any

      */

     ChangeLogScmResult changeLog( ScmRepository repository, ScmFileSet fileSet, Date startDate, Date endDate,

                                   int numDays, ScmBranch branch, String datePattern )

         throws ScmException;

     /**

      * Returns the changes that have happend in the source control system between two tags. This can be adding,

      * removing, updating, ... of files

      * 

      * @param repository the source control system

      * @param fileSet the files to know the changes about. Implementations can also give the changes from the

      *            {@link org.apache.maven.scm.ScmFileSet#getBasedir()} downwards.

      * @param startVersion the start branch/tag/revision

      * @param endVersion the end branch/tag/revision

      * @return The SCM result of the changelog command

      * @throws ScmException if any

      */

     ChangeLogScmResult changeLog( ScmRepository repository, ScmFileSet fileSet, ScmVersion startVersion,

                                   ScmVersion endVersion )

         throws ScmException;

     /**

      * Returns the changes that have happend in the source control system between two tags. This can be adding,

      * removing, updating, ... of files

      * 

      * @param repository the source control system

      * @param fileSet the files to know the changes about. Implementations can also give the changes from the

      *            {@link org.apache.maven.scm.ScmFileSet#getBasedir()} downwards.

      * @param startRevision the start revision

      * @param endRevision the end revision

      * @param datePattern the date pattern use in changelog output returned by scm tool

      * @return

      * @throws ScmException if any

      */

     ChangeLogScmResult changeLog( ScmRepository repository, ScmFileSet fileSet, ScmVersion startRevision,

                                   ScmVersion endRevision, String datePattern )

         throws ScmException;

     /**

      * Save the changes you have done into the repository. This will create a new version of the file or directory in

      * the repository.

      * <p/>

      * When the fileSet has no entries, the fileSet.getBaseDir() is recursively committed. When the fileSet has entries,

      * the commit is non-recursive and only the elements in the fileSet are committed.

      * 

      * @param repository the source control system

      * @param fileSet the files to check in (sometimes called commit)

      * @param message a string that is a comment on the changes that where done

      * @return

      * @throws ScmException if any

      */

     CheckInScmResult checkIn( ScmRepository repository, ScmFileSet fileSet, String message )

         throws ScmException;

     /**

      * Save the changes you have done into the repository. This will create a new version of the file or directory in

      * the repository.

      * <p/>

      * When the fileSet has no entries, the fileSet.getBaseDir() is recursively committed. When the fileSet has entries,

      * the commit is non-recursive and only the elements in the fileSet are committed.

      * 

      * @param repository the source control system

      * @param fileSet the files to check in (sometimes called commit)

      * @param revision branch/tag/revision

      * @param message a string that is a comment on the changes that where done

      * @return

      * @throws ScmException if any

      */

     CheckInScmResult checkIn( ScmRepository repository, ScmFileSet fileSet, ScmVersion revision, String message )

         throws ScmException;

     /**

      * Create a copy of the repository on your local machine

      * 

      * @param repository the source control system

      * @param fileSet the files are copied to the {@link org.apache.maven.scm.ScmFileSet#getBasedir()} location

      * @return

      * @throws ScmException if any

      */

     CheckOutScmResult checkOut( ScmRepository repository, ScmFileSet fileSet )

         throws ScmException;

     /**

      * Create a copy of the repository on your local machine

      * 

      * @param repository the source control system

      * @param fileSet the files are copied to the {@link org.apache.maven.scm.ScmFileSet#getBasedir()} location

      * @param version get the version defined by the revision, branch or tag

      * @return

      * @throws ScmException if any

      */

     CheckOutScmResult checkOut( ScmRepository repository, ScmFileSet fileSet, ScmVersion version )

         throws ScmException;

     /**

      * Create a copy of the repository on your local machine.

      * 

      * @param scmRepository the source control system

      * @param scmFileSet the files are copied to the {@link org.apache.maven.scm.ScmFileSet#getBasedir()} location

      * @param recursive whether to check out recursively

      * @return

      * @throws ScmException if any

      */

     CheckOutScmResult checkOut( ScmRepository scmRepository, ScmFileSet scmFileSet, boolean recursive )

         throws ScmException;

     /**

      * Create a copy of the repository on your local machine.

      * 

      * @param scmRepository the source control system

      * @param scmFileSet the files are copied to the {@link org.apache.maven.scm.ScmFileSet#getBasedir()} location

      * @param version get the version defined by the revision, branch or tag

      * @param recursive whether to check out recursively

      * @return

      * @throws ScmException if any

      */

     CheckOutScmResult checkOut( ScmRepository scmRepository, ScmFileSet scmFileSet, ScmVersion version,

                                 boolean recursive )

         throws ScmException;

     /**

      * Create a diff between two branch/tag/revision.

      * 

      * @param scmRepository the source control system

      * @param scmFileSet the files are copied to the {@link org.apache.maven.scm.ScmFileSet#getBasedir()} location

      * @param startVersion the start branch/tag/revision

      * @param endVersion the end branch/tag/revision

      * @return

      * @throws ScmException if any

      */

     DiffScmResult diff( ScmRepository scmRepository, ScmFileSet scmFileSet, ScmVersion startVersion,

                         ScmVersion endVersion )

         throws ScmException;

     /**

      * Make a file editable. This is used in source control systems where you look at read-only files and you need to

      * make them not read-only anymore before you can edit them. This can also mean that no other user in the system can

      * make the file not read-only anymore.

      * 

      * @param repository the source control system

      * @param fileSet the files to make editable

      * @return

      * @throws ScmException if any

      */

     EditScmResult edit( ScmRepository repository, ScmFileSet fileSet )

         throws ScmException;

     /**

      * Create an exported copy of the repository on your local machine

      * 

      * @param repository the source control system

      * @param fileSet the files are copied to the {@link org.apache.maven.scm.ScmFileSet#getBasedir()} location

      * @return

      * @throws ScmException if any

      */

     ExportScmResult export( ScmRepository repository, ScmFileSet fileSet )

         throws ScmException;

     /**

      * Create an exported copy of the repository on your local machine

      * 

      * @param repository the source control system

      * @param fileSet the files are copied to the {@link org.apache.maven.scm.ScmFileSet#getBasedir()} location

      * @param version get the version defined by the branch/tag/revision

      * @return

      * @throws ScmException if any

      */

     ExportScmResult export( ScmRepository repository, ScmFileSet fileSet, ScmVersion version )

         throws ScmException;

     /**

      * Create an exported copy of the repository on your local machine

      * 

      * @param repository the source control system

      * @param fileSet the files are copied to the {@link org.apache.maven.scm.ScmFileSet#getBasedir()} location

      * @param outputDirectory the directory where the export will be stored

      * @return

      * @throws ScmException if any

      */

     ExportScmResult export( ScmRepository repository, ScmFileSet fileSet, String outputDirectory )

         throws ScmException;

     /**

      * Create an exported copy of the repository on your local machine

      * 

      * @param repository the source control system

      * @param fileSet the files are copied to the {@link org.apache.maven.scm.ScmFileSet#getBasedir()} location

      * @param version get the version defined by the branch/tag/revision

      * @param outputDirectory the directory where the export will be stored

      * @return

      * @throws ScmException if any

      */

     ExportScmResult export( ScmRepository repository, ScmFileSet fileSet, ScmVersion version, String outputDirectory )

         throws ScmException;

     /**

      * List each element (files and directories) of <B>fileSet</B> as they exist in the repository.

      * 

      * @param repository the source control system

      * @param fileSet the files to list

      * @param recursive descend recursively

      * @param version use the version defined by the branch/tag/revision

      * @return the list of files in the repository

      */

     ListScmResult list( ScmRepository repository, ScmFileSet fileSet, boolean recursive, ScmVersion version )

         throws ScmException;

     /**

      * Create new directory/directories in the repository.

      * 

      * @param repository

      * @param fileSet

      * @param message

      * @param createInLocal 

      * @return

      * @throws ScmException

      */

     MkdirScmResult mkdir( ScmRepository repository, ScmFileSet fileSet, String message, boolean createInLocal )

         throws ScmException;

     /**

      * Removes the given files from the source control system

      * 

      * @param repository the source control system

      * @param fileSet the files to be removed

      * @param message

      * @return

      * @throws ScmException if any

      */

     RemoveScmResult remove( ScmRepository repository, ScmFileSet fileSet, String message )

         throws ScmException;

     /**

      * Returns the status of the files in the source control system. The state of each file can be one of the

      * {@link org.apache.maven.scm.ScmFileStatus} flags.

      * 

      * @param repository the source control system

      * @param fileSet the files to know the status about. Implementations can also give the changes from the

      *            {@link org.apache.maven.scm.ScmFileSet#getBasedir()} downwards.

      * @return

      * @throws ScmException if any

      */

     StatusScmResult status( ScmRepository repository, ScmFileSet fileSet )

         throws ScmException;

     /**

      * Tag (or label in some systems) will tag the source file with a certain tag

      * 

      * @param repository the source control system

      * @param fileSet the files to tag. Implementations can also give the changes from the

      *            {@link org.apache.maven.scm.ScmFileSet#getBasedir()} downwards.

      * @param tagName the tag name to apply to the files

      * @return

      * @throws ScmException if any

      */

     TagScmResult tag( ScmRepository repository, ScmFileSet fileSet, String tagName )

         throws ScmException;

     /**

      * Tag (or label in some systems) will tag the source file with a certain tag

      * 

      * @param repository the source control system

      * @param fileSet the files to tag. Implementations can also give the changes from the

      *            {@link org.apache.maven.scm.ScmFileSet#getBasedir()} downwards.

      * @param tagName the tag name to apply to the files

      * @param message the commit message used for the tag creation

      * @return

      * @throws ScmException if any

      */

     TagScmResult tag( ScmRepository repository, ScmFileSet fileSet, String tagName, String message )

         throws ScmException;

     /**

      * Make a file no longer editable. This is the conterpart of

      * {@link #edit(org.apache.maven.scm.repository.ScmRepository,org.apache.maven.scm.ScmFileSet)}. It makes the file

      * read-only again.

      * 

      * @param repository the source control system

      * @param fileSet the files to make uneditable

      * @return

      * @throws ScmException if any

      */

     UnEditScmResult unedit( ScmRepository repository, ScmFileSet fileSet )

         throws ScmException;

     /**

      * Updates the copy on the local machine with the changes in the repository

      * 

      * @param repository the source control system

      * @param fileSet location of your local copy

      * @return

      * @throws ScmException if any

      */

     UpdateScmResult update( ScmRepository repository, ScmFileSet fileSet )

         throws ScmException;

     /**

      * Updates the copy on the local machine with the changes in the repository

      * 

      * @param repository the source control system

      * @param fileSet location of your local copy

      * @param version use the version defined by the branch/tag/revision

      * @return

      * @throws ScmException if any

      */

     UpdateScmResult update( ScmRepository repository, ScmFileSet fileSet, ScmVersion version )

         throws ScmException;

     /**

      * Updates the copy on the local machine with the changes in the repository

      * 

      * @param repository the source control system

      * @param fileSet location of your local copy

      * @param runChangelog Run the changelog command after the update

      * @return

      * @throws ScmException if any

      */

     UpdateScmResult update( ScmRepository repository, ScmFileSet fileSet, boolean runChangelog )

         throws ScmException;

     /**

      * Updates the copy on the local machine with the changes in the repository

      * 

      * @param repository the source control system

      * @param fileSet location of your local copy

      * @param version use the version defined by the branch/tag/revision

      * @param runChangelog Run the changelog command after the update

      * @return

      * @throws ScmException if any

      */

     UpdateScmResult update( ScmRepository repository, ScmFileSet fileSet, ScmVersion version, boolean runChangelog )

         throws ScmException;

     /**

      * Updates the copy on the local machine with the changes in the repository

      * 

      * @param repository the source control system

      * @param fileSet location of your local copy

      * @param datePattern the date pattern use in changelog output returned by scm tool

      * @return

      * @throws ScmException if any

      */

     UpdateScmResult update( ScmRepository repository, ScmFileSet fileSet, String datePattern )

         throws ScmException;

     /**

      * Updates the copy on the local machine with the changes in the repository

      * 

      * @param repository the source control system

      * @param fileSet location of your local copy

      * @param version use the version defined by the branch/tag/revision

      * @param datePattern the date pattern use in changelog output returned by scm tool

      * @return

      * @throws ScmException if any

      */

     UpdateScmResult update( ScmRepository repository, ScmFileSet fileSet, ScmVersion version, String datePattern )

         throws ScmException;

     /**

      * Updates the copy on the local machine with the changes in the repository

      * 

      * @param repository the source control system

      * @param fileSet location of your local copy

      * @param lastUpdate

      * @return

      * @throws ScmException if any

      */

     UpdateScmResult update( ScmRepository repository, ScmFileSet fileSet, Date lastUpdate )

         throws ScmException;

     /**

      * Updates the copy on the local machine with the changes in the repository

      * 

      * @param repository the source control system

      * @param fileSet location of your local copy

      * @param version use the version defined by the branch/tag/revision

      * @param lastUpdate

      * @return

      * @throws ScmException if any

      */

     UpdateScmResult update( ScmRepository repository, ScmFileSet fileSet, ScmVersion version, Date lastUpdate )

         throws ScmException;

     /**

      * Updates the copy on the local machine with the changes in the repository

      * 

      * @param repository the source control system

      * @param fileSet location of your local copy

      * @param lastUpdate Date of last update

      * @param datePattern the date pattern use in changelog output returned by scm tool

      * @return

      * @throws ScmException if any

      */

     UpdateScmResult update( ScmRepository repository, ScmFileSet fileSet, Date lastUpdate, String datePattern )

         throws ScmException;

     /**

      * Updates the copy on the local machine with the changes in the repository

      * 

      * @param repository the source control system

      * @param fileSet location of your local copy

      * @param version use the version defined by the branch/tag/revision

      * @param lastUpdate Date of last update

      * @param datePattern the date pattern use in changelog output returned by scm tool

      * @return

      * @throws ScmException if any

      */

     UpdateScmResult update( ScmRepository repository, ScmFileSet fileSet, ScmVersion version, Date lastUpdate,

                             String datePattern )

         throws ScmException;

     /**

      * Returns the blame of specified file

      * 

      * @param repository the source control system

      * @param fileSet location of your local copy

      * @param filename file

      * @return blame for specified file

      * @since 1.4

      * @throws ScmException if any

      */

     BlameScmResult blame( ScmRepository repository, ScmFileSet fileSet, String filename )

         throws ScmException;

 }