Apache Maven SCM – 如何编写新的 SCM 提供程序

如何编写新的 SCM 提供程序？

编写新的 Maven SCM 提供程序的步骤是什么？

为此提供程序定义允许的 scm url
创建一个扩展org.apache.maven.scm.provider.ScmProviderRepository或org.apache.maven.scm.provider.ScmProviderRepositoryWithHost的类，这个类是scm url对应的bean
创建一个扩展org.apache.maven.scm.provider.AbstractScmProvider的类。此类解析 scm url 并将所有 scm 命令方法链接到它们的实现。重要的方法是makeProviderScmRepository()和validateScmUrl()
实现所有命令并将它们链接到上一步中创建的 scm 提供程序类中
对于每个命令，实施测试命令行格式的 junit 测试
对于每个命令，执行 TCK 测试
使用新的提供者测试发布插件。为此，您必须将依赖项添加到发布插件并运行它
将依赖项添加到 Continuum 库并使用示例项目测试提供程序
更新网站

在下一节中，我们将详细了解编写新的 Maven SCM 提供程序的所有步骤。

为提供者创建一个新的 Maven 项目

您的项目需要使用 Maven SCM 框架中的一些 jar。将它们添加到您的 POM。

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <artifactId>maven-scm-providers</artifactId>
    <groupId>org.apache.maven.scm</groupId>
    <version>LATEST VERSION OF MAVEN-SCM PROVIDERS MASTER POM</version>
  </parent>

  <artifactId>maven-scm-provider-YOUR_PROVIDER_NAME</artifactId>
  <version>1.0-SNAPSHOT</version>

  <name>My Maven SCM Provider</name>

  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.plexus</groupId>
        <artifactId>plexus-component-metadata</artifactId>
        <version>1.7.1</version>
        <executions>
          <execution>
            <goals>
              <goal>generate-metadata</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

plexus-component-metadata maven 插件将生成 Maven SCM 管理器使用的 Plexus 元数据文件。

创建 SCM Provider Repository 类

此类将包含有关您的 SCM 连接的所有 SCM 信息（用户、密码、主机、端口、路径...）。

package org.apache.maven.scm.provider.myprovider.repository;

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

public class MyScmProviderRepository
    extends ScmProviderRepository
{
}

在向此类添加更多信息之前，您可以查看ScmProviderRepository子类（如果它们已实现）。

创建提供者类

这个类是提供者的中心点。Maven SCM 框架将只知道提供程序中的此类，因此此类必须验证 scm url，填充ScmProviderRepository并提供您的提供程序支持的所有命令。我们从一个基本类开始，然后在实现它们时向它添加命令。

在开始编写 SCM 提供程序之前，您必须定义要支持的 SCM URL。

package org.apache.maven.scm.provider.myprovider;

import org.apache.maven.scm.provider.myprovider.repository.MyScmProviderRepository;

import org.apache.maven.scm.provider.AbstractScmProvider;
import org.apache.maven.scm.provider.ScmProviderRepository;
import org.apache.maven.scm.repository.ScmRepositoryException;

/**
 * @plexus.component role="org.apache.maven.scm.provider.ScmProvider" role-hint="provider_name"
 */
public class MyScmProvider
    extends AbstractScmProvider
{
    public String getScmType()
    {
        return "provider_name";
    }

    /**
     * This method parse the scm URL and return a SCM provider repository.
     * At this point, the scmSpecificUrl is the part after scm:provider_name: in your SCM URL.
     */
    public ScmProviderRepository makeProviderScmRepository( String scmSpecificUrl, char delimiter )
        throws ScmRepositoryException
    {
         MyScmProviderRepository providerRepository = new MyScmProviderRepository();
         //Parse scmSpecificUrl and populate there your provider repository

         return providerRepository;
    }
}

plexus.component javadoc 标签将被 POM 中声明的 plexus maven 插件用来生成 plexus 元数据。通常，我们在 scm URL 中使用scm:之后的字符串作为provider_name。

命令实现

当您编写新的 SCM 命令时，您必须扩展 Maven SCM 框架的基类。对于 Maven SCM 支持的每个命令，我们都有一个基本命令，每个命令都有一个返回 SCM 结果的执行方法。

package org.apache.maven.scm.provider.myprovider.command.checkout;

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

public class MyCheckoutCommand
    extends AbstractCheckOutCommand
{
    protected abstract CheckOutScmResult executeCheckOutCommand( ScmProviderRepository repository, ScmFileSet fileSet, String tag )
        throws ScmException
    {
        CheckOutScmResult result = new CheckOutScmResult();

        //Add the code there to run the command
        //If you need to run a native commandline like git/svn/..., look at other providers how to launch it and parse the output

        return result;
    }
}

允许 SCM 提供程序中的命令

现在您的命令已实现，您需要将其添加到您的 SCM 提供程序 ( MyScmProvider ) 中。打开提供程序类并覆盖与您的命令相关的方法。

public class MyScmProvider
    extends AbstractScmProvider
{
    ...

    protected CheckOutScmResult checkout( ScmRepository repository, ScmFileSet fileSet, CommandParameters params )
        throws ScmException
    {
        MyCheckoutCommand command = new MyCheckoutCommand();
        command.setLogger( getLogger() );
        return (CheckOutScmResult) command.execute( repository.getProviderRepository(), fileSet, params );
    }
}

提供者测试

自动化测试

为确保您的提供程序按预期工作，您必须实施一些测试。您可以实现两个级别的测试：

直接使用您的命令并测试您在 SCM 命令中启动的命令行是否正确的简单 JUnit 测试
TCK 的实施。TCK 提供了一组测试来验证您的实现是否与 Maven SCM 框架兼容。TCK 需要访问 SCM 工具。

其他测试

您可以使用 Maven SCM 插件、maven 发布插件、maven changelog 插件和 Continuum 在现实世界中进行手动测试。

使用这些工具测试您的 SCM 提供程序很重要，因为它们由将使用您的提供程序的用户使用。

记录您的提供者

现在您的提供程序工作正常，您必须记录它（支持哪些 scm URL，支持哪些命令......）。您可以使用其他提供商使用的相同模板。