You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ch...@apache.org on 2018/01/09 14:28:45 UTC
commons-release-plugin git commit: COMMONSSITE-97: Javadocs on some
main classes.
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 <ch...@gmail.com>
Authored: Tue Jan 9 09:28:31 2018 -0500
Committer: Rob Tompkins <ch...@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><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