• Home
• com.itemis.maven.plugins
• unleash-scm-provider-api
• 2.8.0
• source code
• ScmProvider.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

com.itemis.maven.plugins.unleash.scm.ScmProvider Maven / Gradle / Ivy

package com.itemis.maven.plugins.unleash.scm;

import com.itemis.maven.plugins.unleash.scm.annotations.ScmProviderType;
import com.itemis.maven.plugins.unleash.scm.requests.BranchRequest;
import com.itemis.maven.plugins.unleash.scm.requests.CheckoutRequest;
import com.itemis.maven.plugins.unleash.scm.requests.CommitRequest;
import com.itemis.maven.plugins.unleash.scm.requests.DeleteBranchRequest;
import com.itemis.maven.plugins.unleash.scm.requests.DeleteTagRequest;
import com.itemis.maven.plugins.unleash.scm.requests.DiffRequest;
import com.itemis.maven.plugins.unleash.scm.requests.HistoryRequest;
import com.itemis.maven.plugins.unleash.scm.requests.PushRequest;
import com.itemis.maven.plugins.unleash.scm.requests.RevertCommitsRequest;
import com.itemis.maven.plugins.unleash.scm.requests.TagRequest;
import com.itemis.maven.plugins.unleash.scm.requests.UpdateRequest;
import com.itemis.maven.plugins.unleash.scm.results.DiffResult;
import com.itemis.maven.plugins.unleash.scm.results.HistoryResult;

/**
 * SCM providers for the unleash-maven-plugin must implement this interface to provide SCM-specific access for the
 * plugin.
 * Furthermore the providers must be annotated witht the {@link ScmProviderType} annotation providing the appropriate
 * SCM type name.
 *
 * @author Stanley Hillner
 * @since 0.1.0
 */
public interface ScmProvider {
  /**
   * Initializes the SCM provider with the working directory and some other optional parameters such as credentials.
   *
   * @param initialization contains some initialization details such as the working directory or authentication details.
   */
  void initialize(ScmProviderInitialization initialization);

  /**
   * Closes the SCM provider and releases all bound resources.
   */
  void close();

  /**
   * Checks out a remote repository into the working directory which has been set during provider initialization.

   * The checkout can be performed from any branch or tag with optional specification of revision information.

   * 

   * Note that the working directory of this provider instance must be empty for checkout operations!
   *
   * @param request the description of what to checkout from where.
   * @throws ScmException if f.i. the working dir is not empty or anything else happens during checkout.
   */
  void checkout(CheckoutRequest request) throws ScmException;

  /**
   * Commits the specified paths or the whole working directory changes. For distributed SCMs a push to the remote
   * repository can be specified. If there are remote changes the provider tries to commit the local changes or fails if
   * there are conflicts.
   *
   * @param request the request containing all relevant settings for the commit.
   * @return the new revision number after the commit which is the remote revision or the new local revision for
   *         distributed SCMs when pushing is not enabled.
   * @throws ScmException if either the commit or the push to the remote repo encountered an error.
   */
  String commit(CommitRequest request) throws ScmException;

  /**
   * Pushes the local changes to the remote repository which is relevant for distributed SCMs only.
   *
   * @param request the request containing all relevant settings for the push.
   * @return the new remote revision after the push has been executed successfully.
   * @throws ScmException if the push encountered an error, f.i. if the remote repo is ahead, ...
   */
  String push(PushRequest request) throws ScmException;

  /**
   * Updates the local repository with changes of the remote repository which might fail due to conflicts. Merging can
   * also be required.
   *
   * @param request the request describing what to update to which revision and how to deal with conflicts.
   * @return the new revision after merging remote changes. This might be the requested remote revision which has been
   *         merged or a newer one if a merge commit was necessary.
   * @throws ScmException if the update fails, f.i. due to unresolvable conflicts.
   */
  String update(UpdateRequest request) throws ScmException;

  /**
   * Creates a tag on the local (and optionally the remote) repository either from the working copy or from a specified
   * remote repository location.
   *
   * @param request the request specifying all relevant information for the tag creation.
   * @return the new revision number after the tag has been created which is the remote revision or the new local
   *         revision for distributed SCMs when pushing is not enabled.
   * @throws ScmException if the tag could not be created.
   */
  String tag(TagRequest request) throws ScmException;

  /**
   * @param tagName the name of the tag which is searched.
   * @return true if the repository contains a tag with the specified name.
   * @throws ScmException if the repository access (local or remote) fails and no exact information about the presence
   *           of the tag can be given.
   */
  boolean hasTag(String tagName) throws ScmException;

  /**
   * Deletes a tag from the repository. In case of distributed SCMs the deletion can only happen locally or also on the
   * remote repository if pushing is enabled.
   *
   * @param request the deletion request specifying all relevant information for tag deletion.
   * @return the new revision number after the tag deletion which is the remote revision or the new local revision for
   *         distributed SCMs when pushing is not enabled.
   * @throws ScmException if the tag could not be deleted.
   */
  String deleteTag(DeleteTagRequest request) throws ScmException;

  /**
   * Creates a branch from the local (and optionally the remote) repository either from the working copy or from a
   * specified remote repository location.
   *
   * @param request the request specifying all relevant information for the branch creation.
   * @return the new revision number after the branch has been created which is the remote revision or the new local
   *         revision for distributed SCMs when pushing is not enabled.
   * @throws ScmException if the branch could not be created.
   */
  String branch(BranchRequest request) throws ScmException;

  /**
   * @param branchName the name of the branch which is searched.
   * @return true if the repository contains a branch with the specified name.
   * @throws ScmException if the repository access (local or remote) fails and no exact information about the presence
   *           of the branch can be given.
   */
  boolean hasBranch(String branchName) throws ScmException;

  /**
   * Deletes a branch from the repository. In case of distributed SCMs the deletion can only happen locally or also on
   * the
   * remote repository if pushing is enabled.
   *
   * @param request the deletion request specifying all relevant information for branch deletion.
   * @return the new revision number after the branch deletion which is the remote revision or the new local revision
   *         for
   *         distributed SCMs when pushing is not enabled.
   * @throws ScmException if the branch could not be deleted.
   */
  String deleteBranch(DeleteBranchRequest request) throws ScmException;

  /**
   * Reverts a number of commits in local and remote repository. If the commits to revert are older than the actual HEAD
   * the diff gets merged on top of the HEAD revision.
   *
   * @param request the request containing the revision range to be reverted and merge information.
   * @return the latest remote revision on the current branch.
   * @throws ScmException if f.i. the specified revisions are newer than the HEAD or FROM and TO are specified in the
   *           wrong order or anything happens during the reversion.
   */
  String revertCommits(RevertCommitsRequest request) throws ScmException;

  /**
   * @return the revision of the current working copy.
   */
  String getLocalRevision();

  /**
   * @return the latest remote revision. In case of distributed SCMs the remote revision is retrieved from the remote
   *         the current branch is tracking.
   */
  String getLatestRemoteRevision();

  /**
   * Calculates the URL of a tag with the given tag name from another connection URL which might just be a basic
   * URL or a URL containing branch info, ...
   *
   * @param currentConnectionString a connection URL from which the tag URL shall be derived assuming standard
   *          directory layout.
   * @param tagName the name of the branch.
   * @return the calculated tag URL.
   */
  String calculateTagConnectionString(String currentConnectionString, String tagName);

  /**
   * Calculates the URL of the branch with the given branch name from another connection URL which might just be a basic
   * URL or a URL containing branch info, ...
   *
   * @param currentConnectionString a connection URL from which the branch URL shall be derived assuming standard
   *          directory layout.
   * @param branchName the name of the branch.
   * @return the calculated branch URL.
   */
  String calculateBranchConnectionString(String currentConnectionString, String branchName);

  /**
   * @return true if the SCM connection URL comprises also the tag name (and path).
   */
  boolean isTagInfoIncludedInConnection();

  /**
   * Calculates the history of the repository which can happen locally only remote-only or combined. Through the request
   * a variety of query conditions can be specified for smaller history results and faster queries, such as a commit
   * range or the maximum number of results.
   *
   * @param request the history request for specifying the history conditions.
   * @return the history produced by the query.
   * @throws ScmException if the SCM provider implementation encountered any error querying the repository history.
   */
  HistoryResult getHistory(HistoryRequest request) throws ScmException;

  /**
   * Calculates a diff between the requested repository paths and objects. The result may only contain diff status
   * information or a full textual diff for each changed object.
   *
   * @param request the request which specifies the diff calculation requirements.
   * @return a result containing a diff object for each changed object of the repository.
   * @throws ScmException if the underlying scm provider implementation encountered an error while creating the diff.
   *           The operation type is alway DIFF.
   */
  DiffResult getDiff(DiffRequest request) throws ScmException;
}