Class PomEditor

java.lang.Object
eu.maveniverse.domtrip.Editor
eu.maveniverse.domtrip.maven.AbstractMavenEditor
eu.maveniverse.domtrip.maven.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:

  • Constructor Details

    • 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 Details

    • getOrderListForParent

      protected List<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(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, String elementName, eu.maveniverse.domtrip.Element insertBefore, eu.maveniverse.domtrip.Element insertAfter, List<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, 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, String elementName, 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, 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(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

    • plugins

      public PomEditor.Plugins plugins()

    • extensions

      public PomEditor.Extensions extensions()

    • subprojects

      public PomEditor.Subprojects subprojects()

    • properties

      public PomEditor.Properties properties()

    • parent

      public PomEditor.Parent parent()

    • 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(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(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, 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:

    • getChildElementText

      public String getChildElementText(eu.maveniverse.domtrip.Element parent, 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:

    • updateOrCreateChildElement

      public eu.maveniverse.domtrip.Element updateOrCreateChildElement(eu.maveniverse.domtrip.Element parent, String childName, 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: