Package 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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  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 check out 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 final 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 final 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 final 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
  Description
  `CommonsDistributionStagingMojo()`

- ## Method Summary

  Modifier and Type
  Method
  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 Details

  - ### 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 check out 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://dist.apache.org/repos/dist/dev/commons/text/1.4-RC1`.

- ## Constructor Details

  - ### CommonsDistributionStagingMojo

    public CommonsDistributionStagingMojo()

- ## Method Details

  - ### 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.