PomEditor API Reference

The PomEditor class extends the core Editor class with Maven-specific functionality for working with POM files.

Class Overview

public class PomEditor extends Editor {
    // Constructors
    public PomEditor()
    public PomEditor(DomTripConfig config)
    public PomEditor(Document document)
    public PomEditor(Document document, DomTripConfig config)
    
    // Maven-specific methods
    public Element insertMavenElement(Element parent, String elementName)
    public Element insertMavenElement(Element parent, String elementName, String textContent)
    public Element findChildElement(Element parent, String elementName)
    public void createMavenDocument(String rootElementName)
    
    // Convenience methods
    public Element addDependency(Element dependenciesElement, String groupId, String artifactId, String version)
    public Element addPlugin(Element pluginsElement, String groupId, String artifactId, String version)
    public Element addModule(Element modulesElement, String moduleName)
    public Element addProperty(Element propertiesElement, String propertyName, String propertyValue)
}

Constructors

Default Constructor

PomEditor editor = new PomEditor();

Creates a new PomEditor with default configuration.

With Configuration

DomTripConfig config = DomTripConfig.builder()
    .indentSize(4)
    .build();
PomEditor editor = new PomEditor(config);

Creates a PomEditor with custom configuration.

With Existing Document

Document doc = Document.of(pomXmlString);
PomEditor editor = new PomEditor(doc);

Creates a PomEditor for an existing Document.

With Document and Configuration

Document doc = Document.of(pomXmlString);
DomTripConfig config = DomTripConfig.builder()
    .preserveWhitespace(true)
    .build();
PomEditor editor = new PomEditor(doc, config);

Core Methods

insertMavenElement()

Inserts elements with Maven-aware ordering and formatting.

Basic Usage

Element insertMavenElement(Element parent, String elementName)

Example:

Element root = editor.root();
Element dependencies = editor.insertMavenElement(root, "dependencies");

With Text Content

Element insertMavenElement(Element parent, String elementName, String textContent)

Example:

editor.insertMavenElement(root, "groupId", "com.example");
editor.insertMavenElement(root, "artifactId", "my-project");
editor.insertMavenElement(root, "version", "1.0.0");

Features:

Automatically orders elements according to Maven conventions
Adds appropriate blank lines between element groups
Preserves existing formatting and comments
Handles nested element structures intelligently

findChildElement()

Finds a direct child element by name.

Element findChildElement(Element parent, String elementName)

Example:

Element root = editor.root();
Element dependencies = editor.findChildElement(root, "dependencies");
if (dependencies == null) {
    dependencies = editor.insertMavenElement(root, "dependencies");
}

Returns: The child element if found, null otherwise.

createMavenDocument()

Creates a new Maven POM document with proper namespace.

void createMavenDocument(String rootElementName)

Example:

PomEditor editor = new PomEditor();
editor.createMavenDocument("project");
Element root = editor.root();
// root now has xmlns="http://maven.apache.org/POM/4.0.0"

Convenience Methods

addDependency()

Adds a dependency with proper structure and ordering.

Element addDependency(Element dependenciesElement, String groupId, String artifactId, String version)

Example:

Element dependencies = editor.insertMavenElement(root, "dependencies");
Element dep = editor.addDependency(dependencies, "org.junit.jupiter", "junit-jupiter", "5.9.2");

// Add additional elements to the dependency
editor.insertMavenElement(dep, "scope", "test");
editor.insertMavenElement(dep, "optional", "true");

Generated Structure:

<dependency>
  <groupId>org.junit.jupiter</groupId>
  <artifactId>junit-jupiter</artifactId>
  <version>5.9.2</version>
  <scope>test</scope>
  <optional>true</optional>
</dependency>

addPlugin()

Adds a plugin with proper structure and ordering.

Element addPlugin(Element pluginsElement, String groupId, String artifactId, String version)

Example:

Element build = editor.insertMavenElement(root, "build");
Element plugins = editor.insertMavenElement(build, "plugins");

Element plugin = editor.addPlugin(plugins, 
    "org.apache.maven.plugins", "maven-compiler-plugin", "3.11.0");

// Add configuration
Element config = editor.insertMavenElement(plugin, "configuration");
editor.addElement(config, "source", "17");
editor.addElement(config, "target", "17");

Notes:

groupId can be null for plugins with default groupId
version can be null for plugins managed by parent or pluginManagement

addModule()

Adds a module to a multi-module project.

Element addModule(Element modulesElement, String moduleName)

Example:

Element modules = editor.insertMavenElement(root, "modules");
editor.addModule(modules, "core");
editor.addModule(modules, "web");
editor.addModule(modules, "cli");

Generated Structure:

<modules>
  <module>core</module>
  <module>web</module>
  <module>cli</module>
</modules>

addProperty()

Adds a property to the properties section.

Element addProperty(Element propertiesElement, String propertyName, String propertyValue)

Example:

Element properties = editor.insertMavenElement(root, "properties");
editor.addProperty(properties, "maven.compiler.source", "17");
editor.addProperty(properties, "maven.compiler.target", "17");
editor.addProperty(properties, "project.build.sourceEncoding", "UTF-8");

Element Ordering

The PomEditor automatically orders elements according to Maven conventions:

Project Level Elements

modelVersion
blank line
parent
blank line
groupId, artifactId, version, packaging
blank line
name, description, url, inceptionYear, organization, licenses
blank line
developers, contributors
blank line
mailingLists
blank line
prerequisites
blank line
modules
blank line
scm, issueManagement, ciManagement, distributionManagement
blank line
properties
blank line
dependencyManagement, dependencies
blank line
repositories, pluginRepositories
blank line
build
blank line
reporting
blank line
profiles

Build Elements

defaultGoal, directory, finalName
sourceDirectory, scriptSourceDirectory, testSourceDirectory
outputDirectory, testOutputDirectory
extensions
blank line
pluginManagement, plugins

Plugin Elements

groupId, artifactId, version
extensions
executions
dependencies
goals
inherited
configuration

Dependency Elements

groupId, artifactId, version
classifier, type
scope
systemPath
optional
exclusions

Error Handling

The PomEditor throws DomTripException for various error conditions:

try {
    editor.insertMavenElement(root, "invalidElement", "value");
} catch (DomTripException e) {
    System.err.println("Error: " + e.getMessage());
}

Common error scenarios:

Invalid XML structure
Null parent elements
Invalid element names
Document parsing errors

Integration with Core Editor

PomEditor inherits all methods from the core Editor class:

// Core Editor methods are available
Element element = editor.addElement(parent, "customElement");
editor.removeElement(element);
editor.insertElementBefore(referenceElement, "newElement");
editor.insertElementAfter(referenceElement, "newElement");

// Comment methods
editor.addComment(element, "This is a comment");

// Serialization
String xml = editor.toXml();
byte[] bytes = editor.toBytes();

Best Practices

Use Constants

import static org.maveniverse.domtrip.maven.MavenPomElements.Elements.*;

// Good
editor.insertMavenElement(root, GROUP_ID, "com.example");

// Avoid
editor.insertMavenElement(root, "groupId", "com.example");

Check for Existing Elements

Element dependencies = editor.findChildElement(root, DEPENDENCIES);
if (dependencies == null) {
    dependencies = editor.insertMavenElement(root, DEPENDENCIES);
}

Handle Null Versions

// For managed dependencies/plugins
editor.addDependency(dependencies, "org.junit.jupiter", "junit-jupiter", null);
editor.addPlugin(plugins, "org.apache.maven.plugins", "maven-surefire-plugin", null);

Preserve Existing Structure

// Work with existing POMs
Document doc = Document.of(existingPomContent);
PomEditor editor = new PomEditor(doc);
// Modifications preserve original formatting and comments