Maven Quick Start

Get up and running with the DomTrip Maven extension in just a few minutes. This guide shows you the most common use cases with practical examples.

Your First POM Edit

Let's start by modifying an existing POM file:

String existingPom = """
        <?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>existing-project</artifactId>
          <version>1.0.0</version>
        </project>
        """;

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

// Add new elements - formatting and comments are preserved
editor.insertMavenElement(root, NAME, "Existing Project");
editor.insertMavenElement(root, DESCRIPTION, "Updated with DomTrip");

String result = editor.toXml();

Notice how the name and description elements were automatically placed in the correct order with appropriate blank lines!

Creating a POM from Scratch

// Create a new POM with Maven-aware ordering
PomEditor editor = new PomEditor();
editor.createMavenDocument("project");
Element root = editor.root();

// Add elements - they'll be automatically ordered
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, NAME, "My Project");

String result = editor.toXml();

Adding Dependencies

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

// Add dependencies with proper structure
Element dependencies = editor.insertMavenElement(root, DEPENDENCIES);
editor.dependencies().addDependency(dependencies, "org.junit.jupiter", "junit-jupiter", "5.9.2");

// Add scope to the dependency
Element junitDep = editor.findChildElement(dependencies, DEPENDENCY);
editor.insertMavenElement(junitDep, SCOPE, "test");

Adding Plugins

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

// Add build plugins with configuration
Element build = editor.insertMavenElement(root, BUILD);
Element plugins = editor.insertMavenElement(build, PLUGINS);

Element compilerPlugin =
        editor.plugins().addPlugin(plugins, "org.apache.maven.plugins", "maven-compiler-plugin", "3.11.0");
Element config = editor.insertMavenElement(compilerPlugin, CONFIGURATION);
editor.addElement(config, "source", "17");
editor.addElement(config, "target", "17");

Working with Multi-Module Projects

// Create parent POM
PomEditor parentEditor = new PomEditor();
parentEditor.createMavenDocument("project");
Element parentRoot = parentEditor.root();

// Set up parent project
parentEditor.insertMavenElement(parentRoot, MODEL_VERSION, "4.0.0");
parentEditor.insertMavenElement(parentRoot, GROUP_ID, "com.example");
parentEditor.insertMavenElement(parentRoot, ARTIFACT_ID, "parent-project");
parentEditor.insertMavenElement(parentRoot, VERSION, "1.0.0");
parentEditor.insertMavenElement(parentRoot, PACKAGING, "pom");

// Add modules
Element modules = parentEditor.insertMavenElement(parentRoot, MODULES);
parentEditor.subprojects().addModule(modules, "core");
parentEditor.subprojects().addModule(modules, "web");
parentEditor.subprojects().addModule(modules, "cli");

String parentPom = parentEditor.toXml();

Common Patterns

Finding and Modifying Existing 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 for Type Safety

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

Preserving Existing Formatting

// The PomEditor preserves existing formatting and comments
String existingPom = """
    <?xml version="1.0" encoding="UTF-8"?>
    <!-- This is my project -->
    <project xmlns="http://maven.apache.org/POM/4.0.0">
      <modelVersion>4.0.0</modelVersion>

      <!-- Project coordinates -->
      <groupId>com.example</groupId>
      <artifactId>existing-project</artifactId>
      <version>1.0.0</version>
    </project>
    """;

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

// Add new elements - comments and formatting are preserved
editor.insertMavenElement(editor.root(), "name", "Existing Project");

// The result maintains the original structure and comments
String result = editor.toXml();

Next Steps

Now that you've seen the basics:

1. Explore the API: Check out the PomEditor API Reference
2. Learn Element Ordering: Understand how Maven Element Ordering works
3. See More Examples: Browse Maven Examples for advanced use cases
4. Dependency Alignment: Learn about auto-detecting conventions
5. Core Features: Learn about DomTrip Core Features that work with Maven extension