org.apache.commons.release.plugin.mojos

## Class CommonsDistributionStagingMojo

- java.lang.Object
- - org.apache.maven.plugin.AbstractMojo
  - - org.apache.commons.release.plugin.mojos.CommonsDistributionStagingMojo

- All Implemented Interfaces:
    org.apache.maven.plugin.ContextEnabled, org.apache.maven.plugin.Mojo

      @Mojo(name="stage-distributions",
            defaultPhase=DEPLOY,
            threadSafe=true,
            aggregator=true)
      public class CommonsDistributionStagingMojo
      extends org.apache.maven.plugin.AbstractMojo

  This class checks out the dev distribution location, copies the distributions into that directory structure under the `target/commons-release-plugin/scm` directory. Then commits the distributions back up to SVN. Also, we include the built and zipped site as well as the RELEASE-NOTES.txt.
  Since:
    1.0
  Author:
    chtompki

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private File` | `baseDir` The `File` that contains a file to the root directory of the working project.
    `private String` | `commonsRcVersion` The RC version of the release.
    `private String` | `commonsReleaseVersion` The release version of the artifact to be built.
    `private File` | `distCheckoutDirectory` The location to which to checkout the dist subversion repository under our working directory, which was given above.
    `private File` | `distRcVersionDirectory` A subdirectory of the dist directory into which we are going to stage the release candidate.
    `private String` | `distServer` The ID of the server (specified in settings.xml) which should be used for dist authentication.
    `private String` | `distSvnStagingUrl` The url of the subversion repository to which we wish the artifacts to be staged.
    `private Boolean` | `dryRun` A boolean that determines whether or not we actually commit the files up to the subversion repository.
    `private static String` | `HEADER_FILE_NAME` The name of file generated from the HEADER.vm velocity template to be checked into the dist svn repo.
    `private Boolean` | `isDistModule` A parameter to generally avoid running unless it is specifically turned on by the consuming module.
    `private String` | `password` The password associated with `username`.
    `private org.apache.maven.project.MavenProject` | `project` The `MavenProject` object is essentially the context of the maven build at a given time.
    `private static String` | `README_FILE_NAME` The name of file generated from the README.vm velocity template to be checked into the dist svn repo.
    `private File` | `releaseNotesFile` The location of the RELEASE-NOTES.txt file such that multi-module builds can configure it.
    `private org.apache.maven.settings.Settings` | `settings` Maven `Settings`.
    `private org.apache.maven.settings.crypto.SettingsDecrypter` | `settingsDecrypter` Maven `SettingsDecrypter` component.
    `private static String` | `SIGNATURE_VALIDATOR_NAME` The name of the signature validation shell script to be checked into the dist svn repo.
    `private File` | `siteDirectory` The location to which the site gets built during running `mvn site`.
    `private String` | `username` The username for the distribution subversion repository.
    `private File` | `workingDirectory` The main working directory for the plugin, namely `target/commons-release-plugin`, but that assumes that we're using the default maven `${project.build.directory}`.

    - ### Fields inherited from interface org.apache.maven.plugin.Mojo

      `ROLE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CommonsDistributionStagingMojo()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `private List<File>` | `buildReadmeAndHeaderHtmlFiles()` Builds up `README.html` and `HEADER.html` that reside in following.
    `private List<File>` | `copyDistributionsIntoScmDirectoryStructureAndAddToSvn(File copiedReleaseNotes, org.apache.maven.scm.provider.ScmProvider provider, org.apache.maven.scm.repository.ScmRepository repository)` Copies the list of files at the root of the `workingDirectory` into the directory structure of the distribution staging repository.
    `private List<File>` | `copyHeaderAndReadmeToSubdirectories(File headerFile, File readmeFile)` Copies `README.html` and `HEADER.html` to the source and binaries directories.
    `private File` | `copyReleaseNotesToWorkingDirectory()` A utility method that takes the `RELEASE-NOTES.txt` file from the base directory of the project and copies it into `workingDirectory`.
    `private File` | `copySignatureValidatorScriptToScmDirectory()` Copies our `signature-validator.sh` script into `${basedir}/target/commons-release-plugin/scm/signature-validator.sh`.
    `private List<File>` | `copySiteToScmDirectory()` Copies `${basedir}/target/site` to `${basedir}/target/commons-release-plugin/scm/site`.
    `void` | `execute()`
    `private void` | `listNotHiddenFilesAndDirectories(File directory, List<File> files)` Lists all directories and files to a flat list.
    `protected void` | `setBaseDir(File baseDir)` This method is the setter for the `baseDir` field, specifically for the usage in the unit tests.

    - ### Methods inherited from class org.apache.maven.plugin.AbstractMojo

      `getLog, getPluginContext, setLog, setPluginContext`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### README_FILE_NAME

          private static final String README_FILE_NAME

      The name of file generated from the README.vm velocity template to be checked into the dist svn repo.
      See Also:
        Constant Field Values

    - #### HEADER_FILE_NAME

          private static final String HEADER_FILE_NAME

      The name of file generated from the HEADER.vm velocity template to be checked into the dist svn repo.
      See Also:
        Constant Field Values

    - #### SIGNATURE_VALIDATOR_NAME

          private static final String SIGNATURE_VALIDATOR_NAME

      The name of the signature validation shell script to be checked into the dist svn repo.
      See Also:
        Constant Field Values

    - #### project

          @Parameter(defaultValue="${project}",
                     required=true)
          private org.apache.maven.project.MavenProject project

      The `MavenProject` object is essentially the context of the maven build at a given time.

    - #### baseDir

          @Parameter(defaultValue="${basedir}")
          private File baseDir

      The `File` that contains a file to the root directory of the working project. Typically this directory is where the `pom.xml` resides.

    - #### siteDirectory

          @Parameter(defaultValue="${project.build.directory}/site",
                     property="commons.siteOutputDirectory")
          private File siteDirectory

      The location to which the site gets built during running `mvn site`.

    - #### workingDirectory

          @Parameter(defaultValue="${project.build.directory}/commons-release-plugin",
                     property="commons.outputDirectory")
          private File workingDirectory

      The main working directory for the plugin, namely `target/commons-release-plugin`, but that assumes that we're using the default maven `${project.build.directory}`.

    - #### distCheckoutDirectory

          @Parameter(defaultValue="${project.build.directory}/commons-release-plugin/scm",
                     property="commons.distCheckoutDirectory")
          private File distCheckoutDirectory

      The location to which to checkout the dist subversion repository under our working directory, which was given above.

    - #### releaseNotesFile

          @Parameter(defaultValue="${basedir}/RELEASE-NOTES.txt",
                     property="commons.releaseNotesLocation")
          private File releaseNotesFile

      The location of the RELEASE-NOTES.txt file such that multi-module builds can configure it.

    - #### dryRun

          @Parameter(property="commons.release.dryRun",
                     defaultValue="false")
          private Boolean dryRun

      A boolean that determines whether or not we actually commit the files up to the subversion repository. If this is set to `true`, we do all but make the commits. We do checkout the repository in question though.

    - #### distSvnStagingUrl

          @Parameter(defaultValue="",
                     property="commons.distSvnStagingUrl")
          private String distSvnStagingUrl

      The url of the subversion repository to which we wish the artifacts to be staged. Typically this would need to be of the form: `scm:svn:https://dist.apache.org/repos/dist/dev/commons/foo/version-RC#`. Note. that the prefix to the substring `https` is a requirement.

    - #### isDistModule

          @Parameter(defaultValue="false",
                     property="commons.release.isDistModule")
          private Boolean isDistModule

      A parameter to generally avoid running unless it is specifically turned on by the consuming module.

    - #### commonsReleaseVersion

          @Parameter(property="commons.release.version")
          private String commonsReleaseVersion

      The release version of the artifact to be built.

    - #### commonsRcVersion

          @Parameter(property="commons.rc.version")
          private String commonsRcVersion

      The RC version of the release. For example the first voted on candidate would be "RC1".

    - #### distServer

          @Parameter(property="commons.distServer")
          private String distServer

      The ID of the server (specified in settings.xml) which should be used for dist authentication. This will be used in preference to `username`/`password`.

    - #### username

          @Parameter(property="user.name")
          private String username

      The username for the distribution subversion repository. This is typically your Apache id.

    - #### password

          @Parameter(property="user.password")
          private String password

      The password associated with `username`.

    - #### settings

          @Parameter(defaultValue="${settings}",
                     readonly=true,
                     required=true)
          private org.apache.maven.settings.Settings settings

      Maven `Settings`.

    - #### settingsDecrypter

          @Component
          private org.apache.maven.settings.crypto.SettingsDecrypter settingsDecrypter

      Maven `SettingsDecrypter` component.

    - #### distRcVersionDirectory

          private File distRcVersionDirectory

      A subdirectory of the dist directory into which we are going to stage the release candidate. We build this up in the `execute()` method. And, for example, the directory should look like `https://https://dist.apache.org/repos/dist/dev/commons/text/1.4-RC1`.

  - ### Constructor Detail

    - #### CommonsDistributionStagingMojo

          public CommonsDistributionStagingMojo()

  - ### Method Detail

    - #### execute

          public void execute()
                       throws org.apache.maven.plugin.MojoExecutionException,
                              org.apache.maven.plugin.MojoFailureException

      Throws:
        `org.apache.maven.plugin.MojoExecutionException`
        `org.apache.maven.plugin.MojoFailureException`

    - #### listNotHiddenFilesAndDirectories

          private void listNotHiddenFilesAndDirectories(File directory,
                                                        List<File> files)

      Lists all directories and files to a flat list.
      Parameters:
        `directory` - `File` containing directory to list
        `files` - a `List` of `File` to which to append the files.

    - #### copyReleaseNotesToWorkingDirectory

          private File copyReleaseNotesToWorkingDirectory()
                                                   throws org.apache.maven.plugin.MojoExecutionException

      A utility method that takes the `RELEASE-NOTES.txt` file from the base directory of the project and copies it into `workingDirectory`.
      Returns:
        the RELEASE-NOTES.txt file that exists in the `target/commons-release-notes/scm` directory for the purpose of adding it to the scm change set in the method `copyDistributionsIntoScmDirectoryStructureAndAddToSvn(File, ScmProvider, ScmRepository)`.
      Throws:
        `org.apache.maven.plugin.MojoExecutionException` - if an `IOException` occurs as a wrapper so that maven can properly handle the exception.

    - #### copyDistributionsIntoScmDirectoryStructureAndAddToSvn

          private List<File> copyDistributionsIntoScmDirectoryStructureAndAddToSvn(File copiedReleaseNotes,
                                                                                   org.apache.maven.scm.provider.ScmProvider provider,
                                                                                   org.apache.maven.scm.repository.ScmRepository repository)
                                                                            throws org.apache.maven.plugin.MojoExecutionException

      Copies the list of files at the root of the `workingDirectory` into the directory structure of the distribution staging repository. Specifically:
      - root:
        - site
        - site.zip
        - RELEASE-NOTES.txt
        - source:
          - -src artifacts....
        - binaries:
          - -bin artifacts....
      Parameters:
        `copiedReleaseNotes` - is the RELEASE-NOTES.txt file that exists in the `target/commons-release-plugin/scm` directory.
        `provider` - is the `ScmProvider` that we will use for adding the files we wish to commit.
        `repository` - is the `ScmRepository` that we will use for adding the files that we wish to commit.
      Returns:
        a `List` of `File`'s in the directory for the purpose of adding them to the maven `ScmFileSet`.
      Throws:
        `org.apache.maven.plugin.MojoExecutionException` - if an `IOException` occurs so that Maven can handle it properly.

    - #### copySignatureValidatorScriptToScmDirectory

          private File copySignatureValidatorScriptToScmDirectory()
                                                           throws org.apache.maven.plugin.MojoExecutionException

      Copies our `signature-validator.sh` script into `${basedir}/target/commons-release-plugin/scm/signature-validator.sh`.
      Returns:
        the `File` for the signature-validator.sh
      Throws:
        `org.apache.maven.plugin.MojoExecutionException` - if an error occurs while the resource is being copied

    - #### copySiteToScmDirectory

          private List<File> copySiteToScmDirectory()
                                             throws org.apache.maven.plugin.MojoExecutionException

      Copies `${basedir}/target/site` to `${basedir}/target/commons-release-plugin/scm/site`.
      Returns:
        the `List` of `File`'s contained in `${basedir}/target/commons-release-plugin/scm/site`, after the copy is complete.
      Throws:
        `org.apache.maven.plugin.MojoExecutionException` - if the site copying fails for some reason.

    - #### buildReadmeAndHeaderHtmlFiles

          private List<File> buildReadmeAndHeaderHtmlFiles()
                                                    throws org.apache.maven.plugin.MojoExecutionException

      Builds up `README.html` and `HEADER.html` that reside in following.
      - distRoot
        - binaries/HEADER.html (symlink)
        - binaries/README.html (symlink)
        - source/HEADER.html (symlink)
        - source/README.html (symlink)
        - HEADER.html
        - README.html
      Returns:
        the `List` of created files above
      Throws:
        `org.apache.maven.plugin.MojoExecutionException` - if an `IOException` occurs in the creation of these files fails.

    - #### copyHeaderAndReadmeToSubdirectories

          private List<File> copyHeaderAndReadmeToSubdirectories(File headerFile,
                                                                 File readmeFile)
                                                          throws org.apache.maven.plugin.MojoExecutionException

      Copies `README.html` and `HEADER.html` to the source and binaries directories.
      Parameters:
        `headerFile` - The originally created `HEADER.html` file.
        `readmeFile` - The originally created `README.html` file.
      Returns:
        a `List` of created files.
      Throws:
        `org.apache.maven.plugin.MojoExecutionException` - if the `SharedFunctions.copyFile(Log, File, File)` fails.

    - #### setBaseDir

          protected void setBaseDir(File baseDir)

      This method is the setter for the `baseDir` field, specifically for the usage in the unit tests.
      Parameters:
        `baseDir` - is the `File` to be used as the project's root directory when this mojo is invoked.

Copyright © 2018–2022 The Apache Software Foundation. All rights reserved.