From f4b5d31042af30d214a7ef490ce890ee88687624 Mon Sep 17 00:00:00 2001 From: Isaac Becerra Llanos Date: Mon, 8 Jul 2024 12:01:23 -0400 Subject: [PATCH] #18 Update current README and javadocs --- README.md | 3 + .../baton/util/pom/PomHelper.java | 15 ++++- .../baton/util/pom/PomModifications.java | 67 ++++++++++++++----- 3 files changed, 69 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index e98bf74..aa3aaea 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,9 @@ public class FooToBarMigration extends AbstractMigration { The following Java classes in `org.technologybrewery.baton.util` can be leveraged to easily implement common migration logic into your extension: * `CommonUtils` * `FileUtils` +* `pom.PomHelper` +* `pom.PomModifications` +* `pom.LocationAwareMavenReader` ### Configure Baton to use the migration With a migration to apply, we both configure and tailor that use through a simple json file. This file can live anywhere diff --git a/baton-maven-plugin/src/main/java/org/technologybrewery/baton/util/pom/PomHelper.java b/baton-maven-plugin/src/main/java/org/technologybrewery/baton/util/pom/PomHelper.java index 926c77f..f191a0d 100644 --- a/baton-maven-plugin/src/main/java/org/technologybrewery/baton/util/pom/PomHelper.java +++ b/baton-maven-plugin/src/main/java/org/technologybrewery/baton/util/pom/PomHelper.java @@ -17,6 +17,9 @@ import java.nio.file.Paths; import java.nio.file.StandardCopyOption; +/** + * Generalized static utilities for assisting with altering Maven POM files. + */ public final class PomHelper { private PomHelper(){ @@ -24,6 +27,7 @@ private PomHelper(){ /** * Helper function to construct a Model of a pom file. + * * @param file File object representing a pom file. * @return the constructed Model. */ @@ -40,6 +44,7 @@ public static Model getLocationAnnotatedModel(File file) { /** * Writes a finalized set of modifications back to a pom file. + * * @param file The original pom file. * @param modifications Finalized set of modifications. * @return true iff the write operation completes successfully. @@ -68,7 +73,15 @@ public static boolean writeModifications(File file, PomModifications.Final modif return true; } - public static InputLocation incrementColumn(InputLocation location, int i) { + /** + * Shifts the given column index for a given InputLocation type by a given amount. + * + * @param location the initial location to be updated with a new column index as a InputLocation. + * @param columnIndexShift number of column indexes to move by represented as a signed integer. + * @return a new InputLocation type with an updated column index. + * @see org.apache.maven.model.InputLocation + */ + public static InputLocation incrementColumn(InputLocation location, int columnIndexShift) { return new InputLocation(location.getLineNumber(), location.getColumnNumber() + i, location.getSource()); } } diff --git a/baton-maven-plugin/src/main/java/org/technologybrewery/baton/util/pom/PomModifications.java b/baton-maven-plugin/src/main/java/org/technologybrewery/baton/util/pom/PomModifications.java index d9898b5..47176bc 100644 --- a/baton-maven-plugin/src/main/java/org/technologybrewery/baton/util/pom/PomModifications.java +++ b/baton-maven-plugin/src/main/java/org/technologybrewery/baton/util/pom/PomModifications.java @@ -17,14 +17,31 @@ */ public final class PomModifications extends TreeSet { + /** + * Returns an instance of the Final class configure with an iterable of all loaded POM file modifications. + * + * @see org.technologybrewery.baton.util.pom.PomModifications.Final + */ public Final finalizeMods() { return new Final(iterator()); } + /** + * A class to iteratively apply a series of POM file modifications. + * + * @see org.technologybrewery.baton.util.pom.PomModifications.Modification + */ public static class Final { private Iterator iterator; private Modification next; + /** + * Constructor that initializes a series of POM file modifications passed in as an Iterator of the + * internally defined Modification class. + * + * @param iterator A given Iterator of the type Modification. + * @see org.technologybrewery.baton.util.pom.PomModifications.Modification + */ private Final(Iterator iterator) { this.iterator = iterator; next = iterator.next(); @@ -38,11 +55,11 @@ public boolean appliesTo(int lineNumber) { /** * Applies the next modification to the input reader, writing the result to the output writer. * - * @param in the input reader - * @param out the output writer - * @param line the current line of the input reader - * @return the line number of `in` after the modification has been applied (changes iff the input reader was advanced) - * @throws IOException if an I/O error occurs + * @param in the input reader. + * @param out the output writer. + * @param line the current line of the input reader. + * @return the line number of `in` after the modification has been applied (changes iff the input reader was advanced). + * @throws IOException if an I/O error occurs. */ public int apply(BufferedReader in, Writer out, String line) throws IOException { int newInputLine = next.apply(in, out, line); @@ -55,9 +72,19 @@ public int apply(BufferedReader in, Writer out, String line) throws IOException } } + /** + * The abstract class by which all POM file modifications inherit from. + */ public static abstract class Modification implements Comparable { private final InputLocation start; + /** + * The constructor accepts an InputLocation type representing the line and column of the file + * where modifications will start being applied. + * + * @param start the location to begin modifying the content. + * @see org.apache.maven.model.InputLocation + */ public Modification(InputLocation start) { this.start = start; } @@ -85,6 +112,13 @@ public int compareTo(Modification o) { public static class Deletion extends Modification { private final InputLocation end; + /** + * Constructor to delete content between the given start and end parameters. + * + * @param start the location to begin deleting POM file content (inclusive). + * @param end the location to stop deleting POM file content (exclusive). + * @see org.apache.maven.model.InputLocation + */ public Deletion(InputLocation start, InputLocation end) { super(start); this.end = end; @@ -125,9 +159,12 @@ public static class Insertion extends Modification { private final int currentIndent; /** - * @param start the location to insert the content (will insert before the existing content on that line) - * @param currentIndent the indent level of the current content on the line - * @param contentProducer a function that produces the content to insert, given a one-level indent string + * Constructor to insert content before the given start existing content on the given start index. + * + * @param start the location to insert the content (before the existing content on that line). + * @param currentIndent the indent level of the current content on the line. + * @param contentProducer a function that produces the content to insert, given a one-level indent string. + * @see org.apache.maven.model.InputLocation */ public Insertion(InputLocation start, int currentIndent, Function contentProducer) { super(start); @@ -156,9 +193,9 @@ public static class Replacement extends Modification { /** * Constructor for replacing content within a single line. * - * @param start the location to insert the new content - * @param end the location to skip to, existing content between start and end will be deleted - * @param content the new content + * @param start the location to insert the new content. + * @param end the location to skip to, existing content between start and end will be deleted. + * @param content the new content. */ public Replacement(InputLocation start, InputLocation end, String content) { this(start, end, 0, l -> content); @@ -167,10 +204,10 @@ public Replacement(InputLocation start, InputLocation end, String content) { /** * Constructor for multi-line replacements. * - * @param start the location to insert the new content - * @param end the location to skip to, existing content between start and end will be deleted - * @param indentLvl the indent level of the current content on the line - * @param contentProducer a function that produces the content to insert, given a one-level indent string + * @param start the location to insert the new content. + * @param end the location to skip to, existing content between start and end will be deleted. + * @param indentLvl the indent level of the current content on the line. + * @param contentProducer a function that produces the content to insert, given a one-level indent string. */ public Replacement(InputLocation start, InputLocation end, int indentLvl, Function contentProducer) { super(start);