commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chtom...@apache.org
Subject commons-release-plugin git commit: COMMONSSITE-97: Javadocs on some main classes.
Date Tue, 09 Jan 2018 14:28:45 GMT
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 <chtompki@gmail.com>
Authored: Tue Jan 9 09:28:31 2018 -0500
Committer: Rob Tompkins <chtompki@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="dev@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>&lt;requiresProject&gt;true&lt;/requiresProject&gt;</code></li>
+          <li>Add <code>&lt;parameter&gt;</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


Mime
View raw message