Repository: commons-release-plugin Updated Branches: refs/heads/master 3250bf66b -> 9a2db79a9
COMMONSSITE-97: Javadocs on some main classes. Project: http://git-wip-us.apache.org/repos/asf/commons-release-plugin/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-release-plugin/commit/9a2db79a Tree: http://git-wip-us.apache.org/repos/asf/commons-release-plugin/tree/9a2db79a Diff: http://git-wip-us.apache.org/repos/asf/commons-release-plugin/diff/9a2db79a Branch: refs/heads/master Commit: 9a2db79a9e514afd8d7b7c8964166a0086f136d0 Parents: 3250bf6 Author: Rob Tompkins <chtom...@gmail.com> Authored: Tue Jan 9 09:28:31 2018 -0500 Committer: Rob Tompkins <chtom...@gmail.com> Committed: Tue Jan 9 09:28:31 2018 -0500 ---------------------------------------------------------------------- .../commons/release/plugin/SharedFunctions.java | 15 ++- .../CommonsDistributionDetachmentMojo.java | 46 +++++++- src/site/xdoc/development.xml | 110 +++++++++++++++++++ 3 files changed, 164 insertions(+), 7 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-release-plugin/blob/9a2db79a/src/main/java/org/apache/commons/release/plugin/SharedFunctions.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/release/plugin/SharedFunctions.java b/src/main/java/org/apache/commons/release/plugin/SharedFunctions.java index 741cd29..eaf7927 100644 --- a/src/main/java/org/apache/commons/release/plugin/SharedFunctions.java +++ b/src/main/java/org/apache/commons/release/plugin/SharedFunctions.java @@ -33,6 +33,15 @@ import java.io.IOException; */ public final class SharedFunctions { + /** + * I want a buffer that is an array with 1024 elements of bytes. We declare + * the constant here for the sake of making the code more readable. + */ + private static final int BUFFER_BYTE_SIZE = 1024; + + /** + * Making the constructor private because the class only contains static methods. + */ private SharedFunctions() { //Uitility Class } @@ -43,6 +52,8 @@ public final class SharedFunctions { * * @param log is the maven log for output logging, particularly in regards to error management. * @param workingDirectory is a {@link File} that represents the directory to first attempt to delete then create. + * @throws MojoExecutionException when an {@link IOException} occurrs for the purpose of bubbling the exception + * up to maven properly. */ public static void initDirectory(Log log, File workingDirectory) throws MojoExecutionException { if (workingDirectory.exists()) { @@ -67,13 +78,13 @@ public final class SharedFunctions { * @param toFile the {@link File} to which to copy into. * @throws MojoExecutionException if an {@link IOException} occurs. */ - public static void copyFile(Log log, File fromFile, File toFile) throws MojoExecutionException{ + public static void copyFile(Log log, File fromFile, File toFile) throws MojoExecutionException { FileInputStream in; FileOutputStream out; try { in = new FileInputStream(fromFile); out = new FileOutputStream(toFile); - byte[] buf = new byte[1024]; + byte[] buf = new byte[BUFFER_BYTE_SIZE]; int len; while ((len = in.read(buf)) > 0) { out.write(buf, 0, len); http://git-wip-us.apache.org/repos/asf/commons-release-plugin/blob/9a2db79a/src/main/java/org/apache/commons/release/plugin/mojos/CommonsDistributionDetachmentMojo.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/release/plugin/mojos/CommonsDistributionDetachmentMojo.java b/src/main/java/org/apache/commons/release/plugin/mojos/CommonsDistributionDetachmentMojo.java index 4d99942..4031089 100644 --- a/src/main/java/org/apache/commons/release/plugin/mojos/CommonsDistributionDetachmentMojo.java +++ b/src/main/java/org/apache/commons/release/plugin/mojos/CommonsDistributionDetachmentMojo.java @@ -30,7 +30,11 @@ import java.io.File; import java.io.FileInputStream; import java.io.IOException; import java.io.PrintWriter; -import java.util.*; +import java.util.ArrayList; +import java.util.Collections; +import java.util.HashSet; +import java.util.List; +import java.util.Set; /** * The purpose of this maven mojo is to detach the artifacts generated by the maven-assembly-plugin, @@ -40,7 +44,7 @@ import java.util.*; * @author chtompki * @since 1.0 */ -@Mojo( name = "detach-distributions", defaultPhase = LifecyclePhase.VERIFY, threadSafe = true) +@Mojo(name = "detach-distributions", defaultPhase = LifecyclePhase.VERIFY, threadSafe = true) public class CommonsDistributionDetachmentMojo extends AbstractMojo { /** @@ -69,19 +73,22 @@ public class CommonsDistributionDetachmentMojo extends AbstractMojo { /** * The maven project context injection so that we can get a hold of the variables at hand. */ - @Parameter( defaultValue = "${project}", required = true ) + @Parameter(defaultValue = "${project}", required = true) private MavenProject project; /** + * The working directory in <code>target</code> that we use as a sandbox for the plugin. */ - @Parameter( defaultValue = "${project.build.directory}/commons-release-plugin", alias = "outputDirectory" ) + @Parameter(defaultValue = "${project.build.directory}/commons-release-plugin", alias = "outputDirectory") private File workingDirectory; /** + * The subversion staging url to which we upload all of our staged artifacts. */ @Parameter(required = true) private String distSvnStagingUrl; + @Override public void execute() throws MojoExecutionException { getLog().info("Detatching Assemblies"); for (Object attachedArtifact : project.getAttachedArtifacts()) { @@ -89,7 +96,7 @@ public class CommonsDistributionDetachmentMojo extends AbstractMojo { detatchedArtifacts.add((Artifact) attachedArtifact); } } - for(Artifact artifactToRemove : detatchedArtifacts) { + for (Artifact artifactToRemove : detatchedArtifacts) { project.getAttachedArtifacts().remove(artifactToRemove); } if (!workingDirectory.exists()) { @@ -100,6 +107,13 @@ public class CommonsDistributionDetachmentMojo extends AbstractMojo { sha1AndMd5SignArtifacts(); } + /** + * A helper method to copy the newly detached artifacts to <code>target/commons-release-plugin</code> + * so that the {@link CommonsDistributionStagingMojo} can find the artifacts later. + * + * @throws MojoExecutionException if some form of an {@link IOException} occurs, we want it + * properly wrapped so that maven can handle it. + */ private void copyRemovedArtifactsToWorkingDirectory() throws MojoExecutionException { StringBuffer copiedArtifactAbsolutePath; getLog().info("Copying detatched artifacts to working directory."); @@ -114,6 +128,14 @@ public class CommonsDistributionDetachmentMojo extends AbstractMojo { } } + /** + * A helper method that creates md5 and sha1 signature files for our detached artifacts in the + * <code>target/commons-release-plugin</code> directory for the purpose of being uploade by + * the {@link CommonsDistributionStagingMojo}. + * + * @throws MojoExecutionException if some form of an {@link IOException} occurs, we want it + * properly wrapped so that maven can handle it. + */ private void sha1AndMd5SignArtifacts() throws MojoExecutionException { for (Artifact artifact : detatchedArtifacts) { if (!artifact.getFile().getName().contains("asc")) { @@ -136,6 +158,13 @@ public class CommonsDistributionDetachmentMojo extends AbstractMojo { } } + /** + * A helper method to create a file path for the <code>md5</code> signature file from a given file. + * + * @param workingDirectory is the {@link File} for the directory in which to make the <code>.md5</code> file. + * @param file the {@link File} whose name we should use to create the <code>.md5</code> file. + * @return a {@link String} that is the absolute path to the <code>.md5</code> file. + */ private String getMd5FilePath(File workingDirectory, File file) { StringBuffer buffer = new StringBuffer(workingDirectory.getAbsolutePath()); buffer.append("/"); @@ -144,6 +173,13 @@ public class CommonsDistributionDetachmentMojo extends AbstractMojo { return buffer.toString(); } + /** + * A helper method to create a file path for the <code>sha1</code> signature file from a given file. + * + * @param workingDirectory is the {@link File} for the directory in which to make the <code>.sha1</code> file. + * @param file the {@link File} whose name we should use to create the <code>.sha1</code> file. + * @return a {@link String} that is the absolute path to the <code>.sha1</code> file. + */ private String getSha1FilePath(File workingDirectory, File file) { StringBuffer buffer = new StringBuffer(workingDirectory.getAbsolutePath()); buffer.append("/"); http://git-wip-us.apache.org/repos/asf/commons-release-plugin/blob/9a2db79a/src/site/xdoc/development.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/development.xml b/src/site/xdoc/development.xml new file mode 100644 index 0000000..afd5186 --- /dev/null +++ b/src/site/xdoc/development.xml @@ -0,0 +1,110 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + 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. +--> +<!-- + $HeadURL$ + $Revision$ $Date$ + --> +<document> + + <properties> + <title>Development</title> + <author email="d...@commons.apache.org">Apache Commons Documentation Team</author> + </properties> + + <body> + + <section name="Help with Maven Mojos"> + + <p> + The best sources of information are + <a href="http://maven.apache.org/guides/plugin/guide-java-plugin-development.html";>Developing Java Plugins for Maven 3.x</a> + and <a href="http://www.sonatype.com/book/chapter-11.html";>Maven: The Definitive Guide: Chapter 11 Writing Plugins</a>. + </p> + + </section> + + <section name="New Mojos"> + + <p> + Each Mojo is a java file that extends <code>Abstract</code> + <ul> + <li>An ant build file + <ul><li>[naming convention: <i>basename</i><b>.build.xml</b>]</li></ul> + </li> + <li>A <i>mapping document</i> which wires the build file into maven's plugin framework + <ul><li>[naming convention: <i>basename</i><b>.mojos.xml</b>]</li></ul> + </li> + </ul> + </p> + + <p> + So if you want to add a new <i>foo-bar</i> ant script you would create a <code>foo-bar.build.xml</code> + ant script file and <code>foo-bar.mojos.xml</code> mapping document. + </p> + + <p> + Both these files should be located in the + <a href="http://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/main/scripts/";>src/main/scripts</a> + directory. + </p> + + <p> + If you want to access variables from the component's <code>pom.xml</code> in the ant script + then you need to do two things in the <i>mapping document</i>: + <ul> + <li>Add the <code><requiresProject>true</requiresProject></code></li> + <li>Add <code><parameter></code> elements for each of the variables you + want to use.</li> + </ul> + </p> + + </section> + + <section name="Goal Prefix"> + + <p> + This plugin uses <code>commons</code> as the goal prefix. So if you add a new <code>foo-bar</code> + goal, then it can be executed on the command line using <code>mvn commons:foo-bar</code>. This prefix + is defined in this plugin's + <a href="http://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/pom.xml";>pom.xml</a>. + </p> + + </section> + + <section name="Modifying Existing Scripts"> + + <p> + Not alot to say about this except, if you need access to additional variables from the component's + <code>pom.xml</code> in the ant build script then you will need to define additional <i>parameters</i> + for these in the associated <i>mapping document</i>. + </p> + + </section> + + <section name="Debugging"> + + <p> + The <i>message level</i> for ant is <i>info</i> by default. Running the plugin goal using a message + level of <i>debug</i> can help in discovering problems - for example: + <source><![CDATA[ + mvn commons:jira-page -DantMessageLevel=debug +]]></source> + </p> + + </section> + + </body> +</document> \ No newline at end of file
