Package eu.maveniverse.domtrip.maven

Class AbstractMavenEditor

  • Direct Known Subclasses:
    ExtensionsEditor, PomEditor, SettingsEditor, ToolchainsEditor
    public abstract class AbstractMavenEditor
extends eu.maveniverse.domtrip.Editor
    Abstract base class for Maven-specific editors that provides common element ordering functionality.

    This class encapsulates the logic for inserting elements at the correct position based on Maven-specific element ordering rules. Subclasses should implement getOrderListForParent(Element) to provide the appropriate ordering for their specific document types.

    • Nested Class Summary

      • Nested classes/interfaces inherited from class eu.maveniverse.domtrip.Editor

        eu.maveniverse.domtrip.Editor.EditorCommentBuilder, eu.maveniverse.domtrip.Editor.EditorElementBuilder, eu.maveniverse.domtrip.Editor.EditorTextBuilder, eu.maveniverse.domtrip.Editor.NodeBuilder

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected AbstractMavenEditor()
      Creates a new editor with default configuration.
      protected AbstractMavenEditor​(eu.maveniverse.domtrip.Document document)
      Creates a new editor for the specified document.
      protected AbstractMavenEditor​(eu.maveniverse.domtrip.Document document, eu.maveniverse.domtrip.DomTripConfig config)
      Creates a new editor for the specified document with the given configuration.
      protected AbstractMavenEditor​(eu.maveniverse.domtrip.DomTripConfig config)
      Creates a new editor with the specified configuration.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected abstract java.util.List<java.lang.String> getOrderListForParent​(eu.maveniverse.domtrip.Element parent)
      Gets the appropriate element order list for the given parent element.
      protected eu.maveniverse.domtrip.Element insertElementAtCorrectPosition​(eu.maveniverse.domtrip.Element parent, java.lang.String elementName, java.lang.String textContent)
      Inserts an element at the correct position based on Maven element ordering.
      protected eu.maveniverse.domtrip.Element insertElementAtCorrectPosition​(eu.maveniverse.domtrip.Element parent, java.lang.String elementName, java.lang.String textContent, java.util.List<java.lang.String> order)
      Inserts an element at the correct position based on the provided element ordering.
      protected eu.maveniverse.domtrip.Element insertElementAtPosition​(eu.maveniverse.domtrip.Element parent, java.lang.String elementName, eu.maveniverse.domtrip.Element insertBefore, eu.maveniverse.domtrip.Element insertAfter, java.util.List<java.lang.String> order, int elementIndex)
      Inserts an element at the determined position, with optional enhanced formatting.
      protected boolean shouldSkipInOrdering​(java.lang.String elementName)
      Determines whether an element name should be skipped during ordering analysis.
      Coordinates toCoordinates​(eu.maveniverse.domtrip.Element element, java.lang.String extension)
      Creates a coordinates from an element with the specified extension/type.
      static java.lang.String toGA​(eu.maveniverse.domtrip.Element element)
      Constructs a GA (groupId:artifactId) string from an element.
      static java.lang.String toGATC​(eu.maveniverse.domtrip.Element element)
      Constructs a GATC (groupId:artifactId:type[:classifier]) string from an element.
      Coordinates toJarCoordinates​(eu.maveniverse.domtrip.Element element)
      Creates a JAR Coordinates from an element.
      static java.lang.String toPluginGA​(eu.maveniverse.domtrip.Element element)
      Constructs a GA string for a Maven plugin element (groupId defaults to "org.apache.maven.plugins" if absent).
      Coordinates toPomCoordinates​(eu.maveniverse.domtrip.Element element)
      Creates a POM Coordinates from an element.

      • Methods inherited from class eu.maveniverse.domtrip.Editor

        add, addBlankLineAfter, addBlankLineBefore, addComment, addElement, addElement, addElement, addElement, addElements, addQNameElements, commentOutElement, commentOutElements, config, createDocument, document, documentStats, insertElementAfter, insertElementAfter, insertElementAt, insertElementAt, insertElementBefore, insertElementBefore, isWellFormed, removeAttribute, removeElement, root, select, selectFirst, setAttribute, setAttributes, setTextContent, toXml, toXml, toXmlPretty, uncommentElement, walk

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • AbstractMavenEditor

        protected AbstractMavenEditor()
        Creates a new editor with default configuration.

      • AbstractMavenEditor

        protected AbstractMavenEditor​(eu.maveniverse.domtrip.DomTripConfig config)
        Creates a new editor with the specified configuration.
        Parameters:
        config - the configuration to use

      • AbstractMavenEditor

        protected AbstractMavenEditor​(eu.maveniverse.domtrip.Document document)
        Creates a new editor for the specified document.
        Parameters:
        document - the document to edit

      • AbstractMavenEditor

        protected AbstractMavenEditor​(eu.maveniverse.domtrip.Document document,
                              eu.maveniverse.domtrip.DomTripConfig config)
        Creates a new editor for the specified document with the given configuration.
        Parameters:
        document - the document to edit
        config - the configuration to use

    • Method Detail

      • getOrderListForParent

        protected abstract java.util.List<java.lang.String> getOrderListForParent​(eu.maveniverse.domtrip.Element parent)
        Gets the appropriate element order list for the given parent element. Subclasses must implement this method to provide ordering specific to their document type.
        Parameters:
        parent - the parent element
        Returns:
        the ordered list of element names, or null if no specific ordering is defined

      • insertElementAtCorrectPosition

        protected eu.maveniverse.domtrip.Element insertElementAtCorrectPosition​(eu.maveniverse.domtrip.Element parent,
                                                                        java.lang.String elementName,
                                                                        java.lang.String textContent)
                                                                 throws eu.maveniverse.domtrip.DomTripException
        Inserts an element at the correct position based on Maven element ordering.

        This method respects the element ordering defined by getOrderListForParent(Element) and handles proper positioning of new elements relative to existing siblings.

        Parameters:
        parent - the parent element to insert into
        elementName - the name of the element to insert
        textContent - the text content (null for empty element)
        Returns:
        the newly created element
        Throws:
        eu.maveniverse.domtrip.DomTripException - if the element cannot be added

      • insertElementAtCorrectPosition

        protected eu.maveniverse.domtrip.Element insertElementAtCorrectPosition​(eu.maveniverse.domtrip.Element parent,
                                                                        java.lang.String elementName,
                                                                        java.lang.String textContent,
                                                                        java.util.List<java.lang.String> order)
                                                                 throws eu.maveniverse.domtrip.DomTripException
        Inserts an element at the correct position based on the provided element ordering.

        This is the core implementation that handles element positioning logic. It can be used directly when a specific ordering list is available, or indirectly through insertElementAtCorrectPosition(Element, String, String) which uses the ordering from getOrderListForParent(Element).

        Parameters:
        parent - the parent element to insert into
        elementName - the name of the element to insert
        textContent - the text content (null for empty element)
        order - the ordered list of element names, or null if no specific ordering
        Returns:
        the newly created element
        Throws:
        eu.maveniverse.domtrip.DomTripException - if the element cannot be added

      • shouldSkipInOrdering

        protected boolean shouldSkipInOrdering​(java.lang.String elementName)
        Determines whether an element name should be skipped during ordering analysis. This allows subclasses to handle special markers (like blank line indicators).
        Parameters:
        elementName - the element name to check
        Returns:
        true if this element should be skipped during ordering

      • insertElementAtPosition

        protected eu.maveniverse.domtrip.Element insertElementAtPosition​(eu.maveniverse.domtrip.Element parent,
                                                                 java.lang.String elementName,
                                                                 eu.maveniverse.domtrip.Element insertBefore,
                                                                 eu.maveniverse.domtrip.Element insertAfter,
                                                                 java.util.List<java.lang.String> order,
                                                                 int elementIndex)
                                                          throws eu.maveniverse.domtrip.DomTripException
        Inserts an element at the determined position, with optional enhanced formatting. This method can be overridden by subclasses to provide specialized insertion logic.
        Parameters:
        parent - the parent element
        elementName - the element name to insert
        insertBefore - element to insert before (may be null)
        insertAfter - element to insert after (may be null)
        order - the complete ordering list
        elementIndex - the index of this element in the ordering
        Returns:
        the newly created element
        Throws:
        eu.maveniverse.domtrip.DomTripException - if the element cannot be added

      • toGA

        public static java.lang.String toGA​(eu.maveniverse.domtrip.Element element)
        Constructs a GA (groupId:artifactId) string from an element.

        With Maven 4's inference mechanism, groupId and artifactId might not be present in the build POM. This method returns null for missing coordinates rather than throwing an exception, allowing for graceful handling of inferred values.

        Example:

        
 PomEditor editor = new PomEditor(document);
 Element dependency = editor.root().child("dependencies")
     .flatMap(deps -> deps.child("dependency"))
     .orElseThrow();
 String ga = editor.toGA(dependency); // "org.junit.jupiter:junit-jupiter"
        Parameters:
        element - the element containing groupId and artifactId children
        Returns:
        GA string, or null if groupId or artifactId is missing
        Since:
        0.3.0

      • toPluginGA

        public static java.lang.String toPluginGA​(eu.maveniverse.domtrip.Element element)
        Constructs a GA string for a Maven plugin element (groupId defaults to "org.apache.maven.plugins" if absent).

        Example:

        
 PomEditor editor = new PomEditor(document);
 Element plugin = ...;
 String ga = editor.toPluginGA(plugin); // "org.apache.maven.plugins:maven-compiler-plugin"
        Parameters:
        element - the plugin element
        Returns:
        GA string, or null if artifactId is missing
        Since:
        0.3.0

      • toGATC

        public static java.lang.String toGATC​(eu.maveniverse.domtrip.Element element)
        Constructs a GATC (groupId:artifactId:type[:classifier]) string from an element.

        With Maven 4's inference mechanism, groupId and artifactId might not be present in the build POM. This method returns null for missing coordinates rather than throwing an exception, allowing for graceful handling of inferred values.

        Example:

        
 PomEditor editor = new PomEditor(document);
 Element dependency = ...;
 String gatc = editor.toGATC(dependency); // "org.junit.jupiter:junit-jupiter:jar"
        Parameters:
        element - the element containing artifact coordinates
        Returns:
        GATC string, or null if groupId or artifactId is missing
        Since:
        0.3.0

      • toCoordinates

        public Coordinates toCoordinates​(eu.maveniverse.domtrip.Element element,
                                 java.lang.String extension)
        Creates a coordinates from an element with the specified extension/type.

        With Maven 4's inference mechanism, groupId and version might not be present in the build POM. This method uses null for missing coordinates, allowing the Coordinates record to be created but with incomplete information. The caller should handle null values appropriately.

        Example:

        
 PomEditor editor = new PomEditor(document);
 Element dependency = ...;
 Coordinates coordinates = editor.toCoordinates(dependency, "jar");
        Parameters:
        element - the element containing groupId, artifactId, and version children
        extension - the artifact extension/type
        Returns:
        a new Coordinates instance (may have null groupId or version)
        Throws:
        eu.maveniverse.domtrip.DomTripException - if artifactId is missing (always required)
        Since:
        0.3.0

      • toJarCoordinates

        public Coordinates toJarCoordinates​(eu.maveniverse.domtrip.Element element)
        Creates a JAR Coordinates from an element.

        Example:

        
 PomEditor editor = new PomEditor(document);
 Element dependency = ...;
 Coordinates artifact = editor.toJarCoordinates(dependency);
        Parameters:
        element - the element containing artifact coordinates
        Returns:
        a new Coordinates instance with JAR type
        Since:
        0.3.0

      • toPomCoordinates

        public Coordinates toPomCoordinates​(eu.maveniverse.domtrip.Element element)
        Creates a POM Coordinates from an element.

        Example:

        
 PomEditor editor = new PomEditor(document);
 Element parent = editor.root().child("parent").orElseThrow();
 Coordinates parentArtifact = editor.toPomCoordinates(parent);
        Parameters:
        element - the element containing artifact coordinates
        Returns:
        a new Coordinates instance with POM type
        Since:
        0.3.0