PomEditor API Reference

The PomEditor class extends the core Editor class with Maven-specific functionality for working with POM files. It provides sub-object APIs for dependencies, plugins, properties, subprojects, and parent management.

Overview

// PomEditor uses sub-object APIs for domain-specific operations
PomEditor editor = new PomEditor();
editor.createMavenDocument("project");
Element root = editor.root();

editor.insertMavenElement(root, MODEL_VERSION, "4.0.0");
editor.insertMavenElement(root, GROUP_ID, "com.example");
editor.insertMavenElement(root, ARTIFACT_ID, "my-project");
editor.insertMavenElement(root, VERSION, "1.0.0");

// Dependencies API
Element deps = editor.insertMavenElement(root, DEPENDENCIES);
editor.dependencies().addDependency(deps, "org.slf4j", "slf4j-api", "2.0.7");

// Plugins API
Element build = editor.insertMavenElement(root, BUILD);
Element plugins = editor.insertMavenElement(build, PLUGINS);
editor.plugins().addPlugin(plugins, "org.apache.maven.plugins", "maven-compiler-plugin", "3.11.0");

// Properties API
Element properties = editor.insertMavenElement(root, PROPERTIES);
editor.properties().addProperty(properties, "maven.compiler.source", "17");

// Subprojects API (for modules)
// editor.subprojects().addModule(modules, "core");

String result = editor.toXml();

Sub-Object APIs

The PomEditor organizes operations into domain-specific sub-objects:

API	Access	Purpose
`Dependencies`	`editor.dependencies()`	Dependency CRUD, exclusions, alignment, convention detection
`Plugins`	`editor.plugins()`	Plugin CRUD, pluginManagement
`Properties`	`editor.properties()`	Property CRUD
`Subprojects`	`editor.subprojects()`	Module management
`Parent`	`editor.parent()`	Parent POM management
`Profiles`	`editor.profiles()`	Profile lookup

Constructors

// Default configuration
PomEditor editor = new PomEditor();

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

// From existing document
Document doc = Document.of(pomXmlString);
PomEditor editor = new PomEditor(doc);

// Document + configuration
PomEditor editor = new PomEditor(doc, config);

Core Methods

insertMavenElement()

Inserts elements with Maven-aware ordering and formatting:

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

Features:

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

findChildElement()

Finds a direct child element by name:

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

createMavenDocument()

Creates a new Maven POM document with proper namespace:

PomEditor editor = new PomEditor();
editor.createMavenDocument("project");

Coordinates

The Coordinates class represents Maven artifact coordinates (GAV):

// Create coordinates for a dependency
Coordinates junit = Coordinates.of("org.junit.jupiter", "junit-jupiter", "5.10.0");

// Access coordinate components
String groupId = junit.groupId(); // "org.junit.jupiter"
String artifactId = junit.artifactId(); // "junit-jupiter"
String version = junit.version(); // "5.10.0"

// String representations
String ga = junit.toGA(); // "org.junit.jupiter:junit-jupiter"
String gav = junit.toGAV(); // "org.junit.jupiter:junit-jupiter:5.10.0"

// Coordinates with classifier and type
Coordinates sources = Coordinates.of("org.example", "my-lib", "1.0.0", "sources", "jar");

// Create new coordinates with different version
Coordinates updated = junit.withVersion("5.11.0");

// Use Coordinates with PomEditor operations
PomEditor editor = new PomEditor(Document.of("""
        <?xml version="1.0" encoding="UTF-8"?>
        <project xmlns="http://maven.apache.org/POM/4.0.0">
          <modelVersion>4.0.0</modelVersion>
          <groupId>com.example</groupId>
          <artifactId>my-project</artifactId>
          <version>1.0.0</version>
        </project>
        """));
editor.dependencies().updateDependency(true, junit);
editor.dependencies().updateManagedDependency(true, updated);

Dependencies API

Access via editor.dependencies().

CRUD Operations

String pom = """
        <?xml version="1.0" encoding="UTF-8"?>
        <project xmlns="http://maven.apache.org/POM/4.0.0">
          <modelVersion>4.0.0</modelVersion>
          <groupId>com.example</groupId>
          <artifactId>my-project</artifactId>
          <version>1.0.0</version>
          <dependencies>
            <dependency>
              <groupId>org.slf4j</groupId>
              <artifactId>slf4j-api</artifactId>
              <version>2.0.7</version>
            </dependency>
          </dependencies>
        </project>
        """;

PomEditor editor = new PomEditor(Document.of(pom));
Coordinates slf4j = Coordinates.of("org.slf4j", "slf4j-api", "2.0.9");

// Update an existing dependency version
editor.dependencies().updateDependency(false, slf4j);

// Upsert: update if exists, create if not
Coordinates guava = Coordinates.of("com.google.guava", "guava", "32.1.2-jre");
editor.dependencies().updateDependency(true, guava);

// Add to dependencyManagement
Coordinates junit = Coordinates.of("org.junit.jupiter", "junit-jupiter", "5.10.0");
editor.dependencies().updateManagedDependency(true, junit);

// Delete a dependency
editor.dependencies().deleteDependency(guava);

// Delete a managed dependency
editor.dependencies().deleteManagedDependency(junit);

For convention-aware managed dependency updates (creating version properties automatically), see updateManagedDependencyAligned() in Dependency Alignment.

Exclusion Management

See Exclusion Management for full documentation.

Convention Detection & Alignment

See Dependency Alignment for full documentation.

Profile-Scoped Operations

See Profile-Scoped Operations for full documentation.

Cross-POM Alignment

See Cross-POM Alignment for full documentation.

Plugins API

Access via editor.plugins().

String pom = """
        <?xml version="1.0" encoding="UTF-8"?>
        <project xmlns="http://maven.apache.org/POM/4.0.0">
          <modelVersion>4.0.0</modelVersion>
          <groupId>com.example</groupId>
          <artifactId>my-project</artifactId>
          <version>1.0.0</version>
          <build>
            <plugins>
              <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.11.0</version>
              </plugin>
            </plugins>
          </build>
        </project>
        """;

PomEditor editor = new PomEditor(Document.of(pom));

// Update a plugin version
Coordinates compiler = Coordinates.of("org.apache.maven.plugins", "maven-compiler-plugin", "3.12.0");
editor.plugins().updatePlugin(false, compiler);

// Upsert a plugin
Coordinates surefire = Coordinates.of("org.apache.maven.plugins", "maven-surefire-plugin", "3.2.0");
editor.plugins().updatePlugin(true, surefire);

// Add to pluginManagement
editor.plugins().updateManagedPlugin(true, surefire);

// Delete a plugin
editor.plugins().deletePlugin(surefire);

Properties API

Access via editor.properties().

PomEditor editor = new PomEditor();
editor.createMavenDocument("project");
Element root = editor.root();
editor.insertMavenElement(root, MODEL_VERSION, "4.0.0");

// Add properties section and properties
Element properties = editor.insertMavenElement(root, PROPERTIES);
editor.properties().addProperty(properties, "maven.compiler.source", "17");
editor.properties().addProperty(properties, "maven.compiler.target", "17");
editor.properties().addProperty(properties, "project.build.sourceEncoding", "UTF-8");
editor.properties().addProperty(properties, "junit.version", "5.9.2");

// Update an existing property
editor.properties().updateProperty(false, "junit.version", "5.10.0");

// Upsert: update or create
editor.properties().updateProperty(true, "slf4j.version", "2.0.9");

// Delete a property
editor.properties().deleteProperty("slf4j.version");

Parent API

Access via editor.parent().

PomEditor editor = new PomEditor();
editor.createMavenDocument("project");
Element root = editor.root();
editor.insertMavenElement(root, MODEL_VERSION, "4.0.0");
editor.insertMavenElement(root, ARTIFACT_ID, "my-project");

// Set a parent POM
Coordinates parent = Coordinates.of("org.springframework.boot", "spring-boot-starter-parent", "3.2.0");
editor.parent().setParent(parent);

// Update parent version
Coordinates updatedParent = Coordinates.of("org.springframework.boot", "spring-boot-starter-parent", "3.3.0");
editor.parent().updateParent(false, updatedParent);

// Delete parent
// editor.parent().deleteParent();

Utility Methods

Finding and Modifying Elements

String pom = """
        <?xml version="1.0" encoding="UTF-8"?>
        <project xmlns="http://maven.apache.org/POM/4.0.0">
          <modelVersion>4.0.0</modelVersion>
          <groupId>com.example</groupId>
          <artifactId>my-project</artifactId>
          <version>1.0.0</version>
          <properties>
            <junit.version>5.9.2</junit.version>
          </properties>
          <dependencies>
            <dependency>
              <groupId>org.junit.jupiter</groupId>
              <artifactId>junit-jupiter</artifactId>
              <version>${junit.version}</version>
              <scope>test</scope>
            </dependency>
          </dependencies>
        </project>
        """;

PomEditor editor = new PomEditor(Document.of(pom));
Element root = editor.root();

// Find a child element
Element dependencies = editor.findChildElement(root, DEPENDENCIES);
assertNotNull(dependencies);

// Check if element exists
boolean hasProps = editor.hasChildElement(root, PROPERTIES);

// Get child element text
String version = editor.getChildElementText(root, VERSION);

// Update or create child element
editor.updateOrCreateChildElement(root, DESCRIPTION, "My project description");

// Set project version
editor.setVersion("2.0.0");

Using Constants

// Use MavenPomElements constants for type-safe element names
// import static eu.maveniverse.domtrip.maven.MavenPomElements.Elements.*;

PomEditor editor = new PomEditor();
editor.createMavenDocument("project");
Element root = editor.root();

// Constants prevent typos and enable IDE autocompletion
editor.insertMavenElement(root, MODEL_VERSION, "4.0.0");
editor.insertMavenElement(root, GROUP_ID, "com.example");
editor.insertMavenElement(root, ARTIFACT_ID, "my-project");
editor.insertMavenElement(root, VERSION, "1.0.0");
editor.insertMavenElement(root, PACKAGING, "jar");
editor.insertMavenElement(root, NAME, "My Project");
editor.insertMavenElement(root, DESCRIPTION, "A sample project");

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
modules
blank line
properties
blank line
dependencyManagement, dependencies
blank line
build
blank line
profiles

Dependency Elements

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

Plugin Elements

groupId, artifactId, version
extensions
executions
dependencies
goals
inherited
configuration

Error Handling

The PomEditor throws DomTripException for error conditions:

Invalid XML structure
Null parent elements
Missing required elements (e.g., profile not found)
Invalid coordinates

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);

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

Next Steps

Maven Quick Start - Get started in 5 minutes
Maven Examples - Real-world usage examples
Element Ordering - How ordering works in detail