#18 Implement new migration utilities for Maven POM files

[cpointe-ibllanos]

Original issue: #18
Continuation of PR #19

[cpointe-ibllanos]

I: To give some context to this file, this is a modified version of org.apache.maven.model.io.xpp3.MavenXpp3ReaderEx to support better cursor awareness and extend element selection functionality.

The main change is the addition of the setWrapLocation function. This new function is called across the majority of the builder's original methods and allows the user to more easily position the cursor to capture the beginning and end of a line containing an xml element using the START and END markers.

Examples of this are used in the unit tests e.g. InputLocation insertLocation = plugin.getLocation(TEST_ELEMENT_TAG + LocationAwareMavenReader.END); is called to reference the position at the end of an XML element and prep the insertion of a new element.

The main additions are outlined below:

      //-----------------/
     //- Inner Classes -/
    //-----------------/

    /**
     * Class Xpp3DomBuilderInputLocationBuilder.
     *
     * @version $Revision$ $Date$
     */
    private static class Xpp3DomBuilderInputLocationBuilder
        implements org.codehaus.plexus.util.xml.Xpp3DomBuilder.InputLocationBuilder
    {

          //--------------------------/
         //- Class/Member Variables -/
        //--------------------------/

        /**
         * Field rootLocation.
         */
        private final InputLocation rootLocation;


          //----------------/
         //- Constructors -/
        //----------------/

        public Xpp3DomBuilderInputLocationBuilder(InputLocation rootLocation)
        {
            this.rootLocation = rootLocation;
        } //-- org.apache.maven.model.io.xpp3.Xpp3DomBuilderInputLocationBuilder(InputLocation)


          //-----------/
         //- Methods -/
        //-----------/

        /**
         * Method toInputLocation.
         *
         * @param parser
         * @return Object
         */
        public Object toInputLocation( XmlPullParser parser )
        {
            return new InputLocation( parser.getLineNumber(), parser.getColumnNumber(), rootLocation.getSource() );
        } //-- Object toInputLocation( XmlPullParser )

    }

    public static interface ContentTransformer
{
    /**
     * Interpolate the value read from the xpp3 document
     * @param source The source value
     * @param fieldName A description of the field being interpolated. The implementation may use this to
     *                           log stuff.
     * @return The interpolated value.
     */
    String transform( String source, String fieldName );
}


    /**
     * Adds the location of the first character of the opening tag and the last character of the closing tag to the
     * given model element.  This method is one of the few customizations that differ from the standard
     * {@link org.apache.maven.model.io.xpp3.MavenXpp3ReaderEx}.
     *
     * @param element the model element to update.
     * @param parser  the parser object.
     * @param key     the key of the sub-element to record (empty if element == sub-element).
     */
    private void setWrapLocation(InputLocationTracker element, XmlPullParser parser, Object key) {
        int line = parser.getLineNumber();
        int col = parser.getColumnNumber(); // column is the last char of the tag (`>`)
        element.setLocation(key + END, new InputLocation(line, col));
        InputLocation endOfStart = element.getLocation(key);
        line = endOfStart.getLineNumber();
        col = endOfStart.getColumnNumber() - parser.getName().length() - 2; // column is the last char of the tag (`>`)
        element.setLocation(key + START, new InputLocation(line, col));
    }

    private void setWrapLocation(InputLocationTracker element, XmlPullParser parser) {
        setWrapLocation(element, parser, "");
    }

    public static final String START = new Object().toString();
    public static final String END = new Object().toString();
}

[csun-cpointe]

Q: wondering if we can achieve this by extending from the org.apache.maven.model.io.xpp3.MavenXpp3ReaderEx class and overwrite some function instead?

[cpointe-ibllanos]

Tried looking into this as a stretch goal from DoD but a lot of the members and methods we want to alter are either private or final in the original class.

[carter-cundiff]

Q: Should this scenario have an steps to it?

[cpointe-ibllanos]

Nope! I included Scenarios but no steps for functionality that was too straightforward to need unit tests for. If you think it's an unnecessary practice, I can remove these kinds of scenarios.