Package eu.maveniverse.domtrip.maven

Class PomEditor

  • public class PomEditor
extends AbstractMavenEditor
    Specialized editor for Maven POM files that extends the base Editor class with Maven-specific functionality and element ordering.

    The PomEditor provides lossless XML editing capabilities specifically tailored for Maven POM files, including:

    • Maven Element Ordering - Automatically orders elements according to Maven conventions
    • Formatting Preservation - Maintains original formatting, whitespace, and comments
    • Intelligent Blank Lines - Adds appropriate blank lines between element groups
    • Maven-specific Methods - Convenience methods for common POM operations

    Basic Usage:

    
 // Parse existing POM
 Document doc = Document.of(pomXmlString);
 PomEditor editor = new PomEditor(doc);

 // Add elements with proper ordering
 Element root = editor.root();
 editor.insertMavenElement(root, "description", "My project description");
 editor.insertMavenElement(root, "name", "My Project");  // Will be ordered before description

 // Serialize with preserved formatting
 String result = editor.toXml();

    Element Ordering:

    The PomEditor automatically orders elements according to Maven POM conventions:

    • Project elements: modelVersion, parent, groupId, artifactId, version, packaging, name, description, etc.
    • Build elements: defaultGoal, directory, finalName, sourceDirectory, etc.
    • Plugin elements: groupId, artifactId, version, extensions, executions, etc.
    • Dependency elements: groupId, artifactId, version, classifier, type, scope, etc.
    Since:
    0.1
    See Also:
    Editor, MavenPomElements

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      class  PomEditor.Dependencies
      Helper for managing regular and managed Maven dependencies within a POM.
      class  PomEditor.Extensions  
      class  PomEditor.Parent  
      class  PomEditor.Plugins  
      class  PomEditor.Profiles
      Helper for inspecting Maven profiles within a POM.
      class  PomEditor.Properties  
      class  PomEditor.Subprojects  

      • 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 
      Constructor Description
      PomEditor()
      Creates a new PomEditor with default configuration.
      PomEditor​(eu.maveniverse.domtrip.Document document)
      Creates a new PomEditor with an existing Document.
      PomEditor​(eu.maveniverse.domtrip.Document document, eu.maveniverse.domtrip.DomTripConfig config)
      Creates a new PomEditor with an existing Document and custom configuration.
      PomEditor​(eu.maveniverse.domtrip.DomTripConfig config)
      Creates a new PomEditor with custom configuration.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void createMavenDocument​(java.lang.String rootElementName)
      Creates a new Maven POM document with the specified root element name.
      PomEditor.Dependencies dependencies()
      Create a helper for managing regular and managed Maven dependencies within this POM.
      PomEditor.Extensions extensions()  
      eu.maveniverse.domtrip.Element findChildElement​(eu.maveniverse.domtrip.Element parent, java.lang.String elementName)
      Finds a child element by name under the specified parent.
      java.lang.String getChildElementText​(eu.maveniverse.domtrip.Element parent, java.lang.String childName)
      Gets the text content of a child element, or returns null if not found.
      protected java.util.List<java.lang.String> getOrderListForParent​(eu.maveniverse.domtrip.Element parent)
      Gets the appropriate element order list for the given parent element.
      boolean hasChildElement​(eu.maveniverse.domtrip.Element parent, java.lang.String childName)
      Checks if an element exists as a child of the given parent.
      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)
      Enhanced element insertion with POM-specific blank line handling.
      eu.maveniverse.domtrip.Element insertMavenElement​(eu.maveniverse.domtrip.Element parent, java.lang.String elementName)
      Inserts a new Maven element with proper ordering and formatting.
      eu.maveniverse.domtrip.Element insertMavenElement​(eu.maveniverse.domtrip.Element parent, java.lang.String elementName, java.lang.String textContent)
      Inserts a new Maven element with text content and proper ordering.
      PomEditor.Parent parent()  
      PomEditor.Plugins plugins()  
      PomEditor.Profiles profiles()
      Create a helper for inspecting Maven profiles within this POM.
      PomEditor.Properties properties()  
      void setPackaging​(java.lang.String value)
      Sets project/packaging to the given value.
      void setVersion​(java.lang.String value)
      Sets project/version or project/parent/version (if project version doesn't exist).
      protected boolean shouldSkipInOrdering​(java.lang.String elementName)
      Determines whether an element name should be skipped during ordering analysis.
      PomEditor.Subprojects subprojects()  
      eu.maveniverse.domtrip.Element updateOrCreateChildElement​(eu.maveniverse.domtrip.Element parent, java.lang.String childName, java.lang.String content)
      Updates or creates a child element with the given content.

      • 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

      • PomEditor

        public PomEditor()
        Creates a new PomEditor with default configuration.

      • PomEditor

        public PomEditor​(eu.maveniverse.domtrip.DomTripConfig config)
        Creates a new PomEditor with custom configuration.
        Parameters:
        config - the configuration to use

      • PomEditor

        public PomEditor​(eu.maveniverse.domtrip.Document document)
        Creates a new PomEditor with an existing Document.
        Parameters:
        document - the existing Document to edit

      • PomEditor

        public PomEditor​(eu.maveniverse.domtrip.Document document,
                 eu.maveniverse.domtrip.DomTripConfig config)
        Creates a new PomEditor with an existing Document and custom configuration.
        Parameters:
        document - the existing Document to edit
        config - the configuration to use

    • Method Detail

      • getOrderListForParent

        protected java.util.List<java.lang.String> getOrderListForParent​(eu.maveniverse.domtrip.Element parent)
        Gets the appropriate element order list for the given parent element. This implementation provides POM-specific ordering with blank line markers.
        Specified by:
        getOrderListForParent in class AbstractMavenEditor
        Parameters:
        parent - the parent element
        Returns:
        the ordered list of element names, or null if no specific ordering is defined

      • shouldSkipInOrdering

        protected boolean shouldSkipInOrdering​(java.lang.String elementName)
        Determines whether an element name should be skipped during ordering analysis. For POM files, empty strings represent blank line markers.
        Overrides:
        shouldSkipInOrdering in class AbstractMavenEditor
        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
        Enhanced element insertion with POM-specific blank line handling.
        Overrides:
        insertElementAtPosition in class AbstractMavenEditor
        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

      • insertMavenElement

        public eu.maveniverse.domtrip.Element insertMavenElement​(eu.maveniverse.domtrip.Element parent,
                                                         java.lang.String elementName)
                                                  throws eu.maveniverse.domtrip.DomTripException
        Inserts a new Maven element with proper ordering and formatting.

        This method automatically determines the correct position for the new element based on Maven POM conventions and adds appropriate blank lines.

        Parameters:
        parent - the parent element
        elementName - the name of the new element
        Returns:
        the newly created element
        Throws:
        eu.maveniverse.domtrip.DomTripException - if the element cannot be added

      • insertMavenElement

        public eu.maveniverse.domtrip.Element insertMavenElement​(eu.maveniverse.domtrip.Element parent,
                                                         java.lang.String elementName,
                                                         java.lang.String textContent)
                                                  throws eu.maveniverse.domtrip.DomTripException
        Inserts a new Maven element with text content and proper ordering.
        Parameters:
        parent - the parent element
        elementName - the name of the new element
        textContent - the text content for the element
        Returns:
        the newly created element
        Throws:
        eu.maveniverse.domtrip.DomTripException - if the element cannot be added

      • findChildElement

        public eu.maveniverse.domtrip.Element findChildElement​(eu.maveniverse.domtrip.Element parent,
                                                       java.lang.String elementName)
        Finds a child element by name under the specified parent.
        Parameters:
        parent - the parent element
        elementName - the child element name to find
        Returns:
        the child element if found, null otherwise

      • createMavenDocument

        public void createMavenDocument​(java.lang.String rootElementName)
                         throws eu.maveniverse.domtrip.DomTripException
        Creates a new Maven POM document with the specified root element name.
        Parameters:
        rootElementName - the name of the root element (typically "project")
        Throws:
        eu.maveniverse.domtrip.DomTripException - if the document cannot be created

      • dependencies

        public PomEditor.Dependencies dependencies()
        Create a helper for managing regular and managed Maven dependencies within this POM. Provides high-level operations for adding, updating, deleting, aligning, and inspecting dependencies, including support for exclusions, dependencyManagement, and convention detection.
        Returns:
        a Dependencies helper bound to this PomEditor instance

      • profiles

        public PomEditor.Profiles profiles()
        Create a helper for inspecting Maven profiles within this POM.
        Returns:
        a Profiles helper bound to this PomEditor instance
        Since:
        1.1.0

      • setVersion

        public void setVersion​(java.lang.String value)
                throws eu.maveniverse.domtrip.DomTripException
        Sets project/version or project/parent/version (if project version doesn't exist).
        Parameters:
        value - the version value
        Throws:
        eu.maveniverse.domtrip.DomTripException - if no version element can be found

      • setPackaging

        public void setPackaging​(java.lang.String value)
                  throws eu.maveniverse.domtrip.DomTripException
        Sets project/packaging to the given value.
        Parameters:
        value - the packaging value (e.g., "jar", "pom", "war")
        Throws:
        eu.maveniverse.domtrip.DomTripException - if an error occurs during editing

      • hasChildElement

        public boolean hasChildElement​(eu.maveniverse.domtrip.Element parent,
                               java.lang.String childName)
        Checks if an element exists as a child of the given parent.

        This is a convenience method that provides a simple boolean check for child element existence without needing to handle Optional.

        Example:

        
 PomEditor editor = new PomEditor(document);
 Element root = editor.root();
 if (editor.hasChildElement(root, "properties")) {
     // Properties section exists
 }
        Parameters:
        parent - the parent element
        childName - the child element name to check
        Returns:
        true if the child element exists, false otherwise
        Since:
        0.3.0
        See Also:
        findChildElement(Element, String), getChildElementText(Element, String)

      • getChildElementText

        public java.lang.String getChildElementText​(eu.maveniverse.domtrip.Element parent,
                                            java.lang.String childName)
        Gets the text content of a child element, or returns null if not found.

        This is a convenience method that provides a simple way to get child element text content with null fallback instead of handling Optional.

        Example:

        
 PomEditor editor = new PomEditor(document);
 Element dependency = // ... get dependency element
 String version = editor.getChildElementText(dependency, "version");
 if (version != null) {
     // Process version
 }
        Parameters:
        parent - the parent element
        childName - the child element name
        Returns:
        the text content of the child element, or null if not found
        Since:
        0.3.0
        See Also:
        findChildElement(Element, String), hasChildElement(Element, String), updateOrCreateChildElement(Element, String, String)

      • updateOrCreateChildElement

        public eu.maveniverse.domtrip.Element updateOrCreateChildElement​(eu.maveniverse.domtrip.Element parent,
                                                                 java.lang.String childName,
                                                                 java.lang.String content)
                                                          throws eu.maveniverse.domtrip.DomTripException
        Updates or creates a child element with the given content.

        If the child element exists, updates its text content. If it doesn't exist, creates it with the specified content using proper Maven element ordering.

        Example:

        
 PomEditor editor = new PomEditor(document);
 Element root = editor.root();
 // This will update existing description or create new one
 editor.updateOrCreateChildElement(root, "description", "My project description");
        Parameters:
        parent - the parent element
        childName - the child element name
        content - the content to set
        Returns:
        the updated or created element
        Throws:
        eu.maveniverse.domtrip.DomTripException - if an error occurs during editing
        Since:
        0.3.0
        See Also:
        findChildElement(Element, String), insertMavenElement(Element, String, String), getChildElementText(Element, String)