DomTrip

https://maveniverse.github.io/domtrip/
Admin
DomTrip is a lossless XML editing library for Java that preserves all formatting details including...
Tokens:16,258
Snippets:181
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Add Dependency to Maven POM

Source: https://maveniverse.github.io/domtrip/docs/getting-started/quick-start

A practical example of loading a Maven POM file, adding a new dependency, and saving the changes back to the file.

```java
void addDependencyExample(String pomPath, String groupId, String artifactId, String version) throws Exception {
    // Load POM with automatic encoding detection
    Document doc = Document.of(Path.of(pomPath));
    Editor editor = new Editor(doc);

    // Find or create dependencies section
    Element project = editor.root();
    Element dependencies = project.descendant("dependencies").orElse(null);
    if (dependencies == null) {
        dependencies = editor.addElement(project, "dependencies");
    }

    // Add new dependency
    Element dependency = editor.addElement(dependencies, "dependency");
    editor.addElement(dependency, "groupId", groupId);
    editor.addElement(dependency, "artifactId", artifactId);
    editor.addElement(dependency, "version", version);

    // Save back to file (String-based)
    Files.writeString(Path.of(pomPath), editor.toXml());

    // Or save to OutputStream with proper encoding
    try (OutputStream outputStream = Files.newOutputStream(Path.of(pomPath))) {
        editor.document().toXml(outputStream);
    }

    System.out.println("✅ Added dependency: " + groupId + ":" + artifactId);
}
```

--------------------------------

### Pretty Print XML Serialization

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Demonstrates pretty printing an XML document. This involves creating a document, getting the root element, and then serializing it with the pretty print configuration.

```java
// Get document
Editor editor = new Editor();
editor.createDocument("project");
Document document = editor.document();

// Get root element
Element root = editor.root();

// Create document with root element
editor.createDocument("project");
Element newRoot = editor.root(); // <project></project>
Assertions.assertNotNull(newRoot);

// Serialize to XML
String xml = editor.toXml();

// Pretty printing
String prettyXml = editor.toXml(DomTripConfig.prettyPrint());
```

--------------------------------

### Find and Manipulate XML Elements

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Provides examples for finding elements by name, both the first occurrence and all descendants, adding new child elements, removing elements, and getting text content. Assumes an Editor instance is already set up with an XML document.

```java
String xml = "<project><version>1.0</version><dependency><version>2.0</version></dependency></project>";
Editor editor = new Editor(Document.of(xml));
Element root = editor.root();

// Find first element with name
Element version = root.childElement("version").orElse(null);

// Find all elements with name using descendants
List<Element> allVersions = root.descendants("version").toList();

// Add new child element
Element child = editor.addElement(root, "newChild");

// Remove element (if it exists)
Element toRemove = root.childElement("deprecated").orElse(null);
if (toRemove != null) {
    editor.removeElement(toRemove);
}

// Get text content
String content = version != null ? version.textContent() : "";
```

--------------------------------

### Configure DomTrip Parsing and Serialization

Source: https://maveniverse.github.io/domtrip/javadoc/latest

Customize DomTrip's behavior by creating a DomTripConfig object. This example shows how to set options like comment preservation and pretty-printing before parsing and editing XML.

```java
DomTripConfig config = DomTripConfig.defaults()
     .withCommentPreservation(true)
     .withPrettyPrint(false);

 Document doc = Document.of(xmlString);
 Editor editor = new Editor(doc, config);
 
```

--------------------------------

### Thread-Safe Editor Usage with Synchronization

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Provides examples of how to ensure thread safety when using the DomTrip Editor, either by synchronizing access to a single editor instance or by using separate instances per thread.

```java
String xml = "<project></project>";
Editor editor = new Editor(Document.of(xml));
Element parent = editor.root();

// ✅ Thread-safe usage (conceptual example)
synchronized (editor) {
    editor.addElement(parent, "child", "value");
    String result = editor.toXml();
    Assertions.assertTrue(result.contains("child"));
}

// ✅ Or use separate editor instances per thread
Editor editorForThread = new Editor(Document.of(xml));
editorForThread.addElement(editorForThread.root(), "thread-child", "value");
```

--------------------------------

### Handle DomTrip Exceptions

Source: https://maveniverse.github.io/domtrip/docs/getting-started/quick-start

Provides an example of robust error handling for DomTrip operations, specifically catching and differentiating between I/O errors and XML parsing/encoding errors.

```java
try {
    String xml = "<root><child>value</child></root>";
    InputStream inputStream = new ByteArrayInputStream(xml.getBytes(StandardCharsets.UTF_8));
    Document doc = Document.of(inputStream);

    ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
    doc.toXml(outputStream);

    inputStream.close();
    outputStream.close();
} catch (DomTripException e) {
    if (e.getCause() instanceof IOException) {
        // Handle I/O errors
        System.err.println("I/O error: " + e.getMessage());
    } else {
        // Handle parsing/encoding errors
        System.err.println("XML error: " + e.getMessage());
    }
}
```

--------------------------------

### Get Editor Configuration

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Retrieve the configuration object used by the editor instance. This is useful for understanding or modifying editor behavior, such as pretty-printing settings.

```java
DomTripConfig config = DomTripConfig.prettyPrint();
Editor editor = new Editor(config);

// Get the configuration used by this editor
DomTripConfig usedConfig = editor.config();

```

--------------------------------

### Attribute Operations

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Methods for setting, getting, and removing XML attributes while preserving formatting.

```java
String xml = "<dependency scope='test'></dependency>";
Editor editor = new Editor(Document.of(xml));
Element element = editor.root();

// For XML: <element attr1='existing' attr2="another"/>
editor.setAttribute(element, "attr1", "updated"); // Preserves single quotes
editor.setAttribute(element, "attr3", "new"); // Infers quote style from existing

// Remove attribute
editor.removeAttribute(element, "deprecated");

// Set multiple attributes
Map<String, String> attrs = Map.of(
        "scope", "test",
        "optional", "true");
editor.setAttributes(element, attrs);

// Get attribute value
String scopeValue = element.attribute("scope");

// Check if attribute exists
boolean hasOptional = element.hasAttribute("optional");
__
```

```java
String xml = "<dependency scope='test'></dependency>";
Editor editor = new Editor(Document.of(xml));
Element element = editor.root();

// Get attribute value
String scope = element.attribute("scope");

// Set attribute value
editor.setAttribute(element, "optional", "true");

// Remove attribute
editor.removeAttribute(element, "scope");
__
```

```java
String xml = "<dependency scope='test'></dependency>";
Editor editor = new Editor(Document.of(xml));
Element element = editor.root();

// For XML: <element attr1='existing' attr2="another"/>
editor.setAttribute(element, "attr1", "updated"); // Preserves single quotes
editor.setAttribute(element, "attr3", "new"); // Infers quote style from existing

// Remove attribute
editor.removeAttribute(element, "deprecated");

// Set multiple attributes
Map<String, String> attrs = Map.of(
        "scope", "test",
        "optional", "true");
editor.setAttributes(element, attrs);

// Get attribute value
String scopeValue = element.attribute("scope");

// Check if attribute exists
boolean hasOptional = element.hasAttribute("optional");
__
```

--------------------------------

### Attribute Operations

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Methods for setting, getting, and removing attributes from XML elements while preserving formatting.

```APIDOC
## setAttribute(Element element, String name, String value)

### Description
Sets an attribute value on an element, preserving existing quote styles or inferring them.

### Parameters
#### Request Body
- **element** (Element) - Required - The target element.
- **name** (String) - Required - The attribute name.
- **value** (String) - Required - The attribute value.

## getAttribute(Element element, String name)

### Description
Retrieves the value of a specific attribute from an element.

### Parameters
#### Request Body
- **element** (Element) - Required - The target element.
- **name** (String) - Required - The attribute name.

## removeAttribute(Element element, String name)

### Description
Removes a specific attribute from an element.

### Parameters
#### Request Body
- **element** (Element) - Required - The target element.
- **name** (String) - Required - The attribute name to remove.
```

--------------------------------

### Initialize Editor with various configurations

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Demonstrates creating an Editor instance using default settings, custom configurations, or existing Document objects.

```java
// Default constructor
Editor editor = new Editor();

// With custom configuration
DomTripConfig config = DomTripConfig.prettyPrint();
Editor configuredEditor = new Editor(config);

// With existing document
String xml = "<project></project>";
Document doc = Document.of(xml);
Editor documentEditor = new Editor(doc);

// With document and configuration
Editor fullEditor = new Editor(doc, DomTripConfig.defaults());
__
```

--------------------------------

### Create Basic Maven Settings with DomTrip SettingsEditor

Source: https://maveniverse.github.io/domtrip/examples

Illustrates creating a basic Maven settings.xml file using the SettingsEditor. It shows how to insert elements like local repository and offline mode with automatic ordering.

```java
// Create a new settings document
SettingsEditor editor = new SettingsEditor();
editor.createSettingsDocument();
Element root = editor.root();

// Add elements with automatic ordering
editor.insertSettingsElement(root, LOCAL_REPOSITORY, "/custom/repo");
editor.insertSettingsElement(root, OFFLINE, "false");

String result = editor.toXml();
```

--------------------------------

### Handle XML Namespaces with QName

Source: https://maveniverse.github.io/domtrip/javadoc/snapshot

Demonstrates creating elements with namespaces, navigating trees using qualified names, and resolving namespace components.

```java
 // Create elements with namespaces using QName
 QName soapEnvelope = QName.of("http://schemas.xmlsoap.org/soap/envelope/", "Envelope", "soap");
 Element envelope = Element.of(soapEnvelope);

 // Namespace-aware navigation
 Optional<Element> body = root.descendant(
     QName.of("http://schemas.xmlsoap.org/soap/envelope/", "Body"));

 // Namespace resolution
 String namespaceURI = element.namespaceURI();
 String localName = element.localName();
 String prefix = element.prefix();
```

--------------------------------

### Create and Navigate XML with Namespaces

Source: https://maveniverse.github.io/domtrip/docs/getting-started/quick-start

Demonstrates creating elements with namespaces and performing namespace-aware navigation within an XML document using DomTrip.

```java
Element soapEnvelope = Element.of("soap:Envelope").attribute("xmlns:soap", "http://schemas.xmlsoap.org/soap/envelope/");
Assertions.assertNotNull(soapEnvelope);
```

```java
String xml = "<soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\">
    <soap:Body>
        <content>Hello</content>
    </soap:Body>
</soap:Envelope>";
Document doc = Document.of(xml);
Editor editor = new Editor(doc);
Assertions.assertNotNull(editor);
Element root = editor.root();

Optional<Element> body = root.childElement("soap:Body");
if (body.isPresent()) {
    System.out.println("Found SOAP body");
}

// Get namespace information
String localName = root.localName();
String namespaceURI = root.namespaceURI();
Assertions.assertNotNull(namespaceURI);
```

--------------------------------

### Create Editor with Custom Configuration

Source: https://maveniverse.github.io/domtrip/docs/getting-started/quick-start

Illustrates creating an Editor with a custom DomTrip configuration, including pretty printing and specific indentation, for building XML structures.

```java
// Create document programmatically
Document doc = Document.withRootElement("project");

// Create Editor with custom config
DomTripConfig config = DomTripConfig.prettyPrint().withIndentString("  ");
Editor editor = new Editor(doc, config);

// Build document structure
Element root = editor.root();
editor.addElement(root, "groupId", "com.example");
editor.addElement(root, "artifactId", "my-project");
```

--------------------------------

### Create Editor from Existing Document

Source: https://maveniverse.github.io/domtrip/docs/getting-started/quick-start

Demonstrates how to create a DomTrip Editor instance from an already parsed Document object and use its API for modifications.

```java
// Parse with Document directly
String xmlString = createConfigXml();
Document document = Document.of(xmlString);

// Create Editor from existing Document
Editor editor = new Editor(document);

// Now use the convenient Editor API
Element root = editor.root();
editor.addElement(root, "newChild", "value");
editor.setAttribute(root, "version", "2.0");

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

--------------------------------

### Configure XML Output Formatting

Source: https://maveniverse.github.io/domtrip/docs/getting-started/quick-start

Shows how to customize DomTrip's XML output using configuration options for pretty printing, minimal output, and custom indentation.

```java
String xml = createConfigXml();
Document doc = Document.of(xml);
Editor editor = new Editor(doc);

// Pretty printing
DomTripConfig config = DomTripConfig.prettyPrint();
String prettyXml = editor.toXml(config);

// Minimal output
String minimalXml = editor.toXml(DomTripConfig.minimal());

// Custom configuration
DomTripConfig custom = DomTripConfig.defaults()
        .withIndentString("  ") // 2 spaces
        .withCommentPreservation(true);
String customXml = editor.toXml(custom);
```

--------------------------------

### Add Mirrors to Maven Settings with DomTrip SettingsEditor

Source: https://maveniverse.github.io/domtrip/examples

Demonstrates adding mirror configurations to a Maven settings.xml file using the SettingsEditor. This includes defining mirror IDs, names, URLs, and repository IDs.

```java
SettingsEditor editor = new SettingsEditor();
editor.createSettingsDocument();
Element root = editor.root();

// Add mirrors
Element mirrors = editor.insertSettingsElement(root, MIRRORS);
editor.addMirror(mirrors, "central-mirror", "Central Mirror", "https://repo1.maven.org/maven2", "central");
editor.addMirror(
        mirrors, "nexus-mirror", "Nexus Mirror", "https://nexus.example.com/repository/maven-public/", "*");

String result = editor.toXml();
```

--------------------------------

### Add Servers to Maven Settings with DomTrip SettingsEditor

Source: https://maveniverse.github.io/domtrip/examples

Shows how to add server configurations to a Maven settings.xml file using the SettingsEditor's convenience methods. This includes specifying server IDs, usernames, and passwords.

```java
SettingsEditor editor = new SettingsEditor();
editor.createSettingsDocument();
Element root = editor.root();

// Add servers with convenience methods
Element servers = editor.insertSettingsElement(root, SERVERS);
editor.addServer(servers, "my-server", "username", "password");
editor.addServer(servers, "nexus", "admin", "secret123");

String result = editor.toXml();
```

--------------------------------

### Create and Add Maven Extensions

Source: https://maveniverse.github.io/domtrip/examples

Manage extensions.xml files by adding specific extension coordinates and types.

```java
// Create a new extensions document
ExtensionsEditor editor = new ExtensionsEditor();
editor.createExtensionsDocument();
Element root = editor.root();

// Add extensions with convenience methods
editor.addExtension(root, "org.apache.maven.wagon", "wagon-ssh", "3.5.1");
editor.addExtension(root, "io.takari.maven", "takari-smart-builder", "0.6.1");

String result = editor.toXml();
```

```java
ExtensionsEditor editor = new ExtensionsEditor();
editor.createExtensionsDocument();
Element root = editor.root();

// Add various types of extensions
editor.addExtension(root, "org.apache.maven.wagon", "wagon-ssh", "3.5.1");
editor.addExtension(root, "io.takari.maven", "takari-smart-builder", "0.6.1");
editor.addExtension(root, "org.eclipse.tycho", "tycho-maven-plugin", "3.0.4", null, "maven-plugin");

String result = editor.toXml();
```

--------------------------------

### Load XML with Custom Configuration

Source: https://maveniverse.github.io/domtrip/docs/getting-started/quick-start

Loads an XML document with a custom DomTrip configuration, such as enabling pretty printing.

```java
// With custom configuration
Document docWithConfig = Document.of(xmlString);
Editor editorWithConfig = new Editor(docWithConfig, DomTripConfig.prettyPrint());
__
```

--------------------------------

### Configure DomTrip Parsing

Source: https://maveniverse.github.io/domtrip/javadoc/snapshot

Shows how to customize parsing and serialization behavior using DomTripConfig.

```java
 DomTripConfig config = DomTripConfig.defaults()
     .withCommentPreservation(true)
     .withPrettyPrint(false);

 Document doc = Document.of(xmlString);
 Editor editor = new Editor(doc, config);
```

--------------------------------

### Add Plugins to Maven POM with DomTrip Maven Extension

Source: https://maveniverse.github.io/domtrip/examples

Demonstrates adding Maven plugins with configurations to a POM file using the PomEditor. This includes specifying plugin details and setting configuration parameters like source and target versions.

```java
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");
```

--------------------------------

### Use Batch Operations for Adding Elements

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Shows how to efficiently add multiple elements to the DOM using a Map of properties with the addElements method. This is more performant than adding elements one by one.

```java
String xml = "<project></project>";
Editor editor = new Editor(Document.of(xml));
Element parent = editor.root();

// ✅ Efficient batch operation
Map<String, String> properties = Map.of(
        "groupId", "com.example",
        "artifactId", "my-app");
editor.addElements(parent, properties);
```

--------------------------------

### Configure Spring XML Beans

Source: https://maveniverse.github.io/domtrip/examples

Demonstrates parsing a Spring configuration string, locating specific bean elements, and modifying their properties.

```java
String springConfig = """
    <?xml version="1.0" encoding="UTF-8"?>
    <beans xmlns="http://www.springframework.org/schema/beans">
        <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource">
            <property name="driverClassName" value="org.postgresql.Driver"/>
            <property name="url" value="jdbc:postgresql://localhost:5432/mydb"/>
        </bean>
    </beans>
    """;

Document doc = Document.of(springConfig);
Editor editor = new Editor(doc);

// Find the dataSource bean
Element dataSource = editor.root()
        .descendants()
        .filter(e -> "bean".equals(e.name()) && "dataSource".equals(e.attribute("id")))
        .findFirst()
        .orElseThrow();

// Update the URL property
Element urlProperty = dataSource
        .childElements()
        .filter(e -> "property".equals(e.name()) && "url".equals(e.attribute("name")))
        .findFirst()
        .orElseThrow();

editor.setAttribute(urlProperty, "value", "jdbc:postgresql://prod-db:5432/mydb");

// Add new property
Element newProperty = editor.addElement(dataSource, "property");
editor.setAttribute(newProperty, "name", "maxActive");
editor.setAttribute(newProperty, "value", "100");
__
```

--------------------------------

### Manage XML Namespaces

Source: https://maveniverse.github.io/domtrip/examples

Shows how to add elements to an XML document while respecting existing namespace definitions.

```java
String xmlWithNamespaces = """
    <?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <modelVersion>4.0.0</modelVersion>
    </project>
    """;

Document doc = Document.of(xmlWithNamespaces);
Editor editor = new Editor(doc);

// Add element with namespace
Element project = editor.root();
Element build = editor.addElement(project, "build");
Element plugins = editor.addElement(build, "plugins");

// Elements inherit the default namespace automatically
Element plugin = editor.addElement(plugins, "plugin");
editor.addElement(plugin, "groupId", "org.maven.plugins");
editor.addElement(plugin, "artifactId", "maven-compiler-plugin");
__
```

--------------------------------

### Create Basic Maven POM with DomTrip Maven Extension

Source: https://maveniverse.github.io/domtrip/examples

Utilizes the PomEditor to create a new Maven POM file, inserting essential elements like model version, group ID, artifact ID, and version. Elements are automatically ordered according to Maven conventions.

```java
// 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();
```

--------------------------------

### Configuration

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Accessing the editor configuration.

```APIDOC
## config()

### Description
Retrieves the DomTripConfig instance currently used by the editor.
```

--------------------------------

### Load XML from File

Source: https://maveniverse.github.io/domtrip/docs/getting-started/quick-start

Loads an XML document from a file, with DomTrip automatically handling encoding.

```java
// From file (recommended - handles encoding automatically)
Document doc2 = Document.of(tempFile);
Editor editor2 = new Editor(doc2);
__
```

--------------------------------

### AlignOptions Configuration

Source: https://maveniverse.github.io/domtrip/docs/maven/cross-pom

Configuration options for controlling how dependency versions are aligned to the parent POM.

```APIDOC
## AlignOptions

### Description
Controls how versions are stored in the parent POM and how property names are generated.

### Fields
- **versionSource** (AlignOptions.VersionSource) - Required - Specifies how versions are stored in the parent's `dependencyManagement`. Possible values: `PROPERTY`.
- **namingConvention** (AlignOptions.PropertyNamingConvention) - Optional - Specifies the convention for generating property names. Possible values: `DOT_SUFFIX`.
- **propertyName** (string) - Optional - An explicit property name to use for the version.

### Example Usage
```java
AlignOptions options = AlignOptions.builder()
    .versionSource(AlignOptions.VersionSource.PROPERTY)
    .namingConvention(AlignOptions.PropertyNamingConvention.DOT_SUFFIX)
    .propertyName("guava.version")
    .build();
```
```

--------------------------------

### Editor Constructors

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Provides details on the various constructors available for the Editor class, allowing initialization with default settings, custom configurations, or existing documents.

```APIDOC
## Editor()

### Description
Creates a new editor with default configuration.

### Method
Constructor

### Endpoint
N/A

### Parameters
None

### Request Example
```java
Editor editor = new Editor();
```

### Response
N/A
```

```APIDOC
## Editor(DomTripConfig config)

### Description
Creates a new editor with custom configuration.

### Method
Constructor

### Endpoint
N/A

### Parameters
- **config** (DomTripConfig) - Required - The custom configuration for the editor.

### Request Example
```java
DomTripConfig config = DomTripConfig.prettyPrint();
Editor configuredEditor = new Editor(config);
```

### Response
N/A
```

```APIDOC
## Editor(Document document)

### Description
Creates a new editor with an existing Document object.

### Method
Constructor

### Endpoint
N/A

### Parameters
- **document** (Document) - Required - The existing Document object to initialize the editor with.

### Request Example
```java
String xml = "<project></project>";
Document doc = Document.of(xml);
Editor documentEditor = new Editor(doc);
```

### Response
N/A
```

```APIDOC
## Editor(Document document, DomTripConfig config)

### Description
Creates a new editor with an existing Document and custom configuration.

### Method
Constructor

### Endpoint
N/A

### Parameters
- **document** (Document) - Required - The existing Document object.
- **config** (DomTripConfig) - Required - The custom configuration for the editor.

### Request Example
```java
String xml = "<project></project>";
Document doc = Document.of(xml);
Editor fullEditor = new Editor(doc, DomTripConfig.defaults());
```

### Response
N/A

### Throws
- **IllegalArgumentException** - if document is null.
```

--------------------------------

### Perform advanced document editing

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Illustrates working with existing documents or programmatically creating new ones and adding elements.

```java
// Working with an existing document
String xmlString = "<project><version>1.0</version></project>";
Document existingDoc = Document.of(xmlString);
Editor editor = new Editor(existingDoc);

// Working with a programmatically created document
Document doc = Document.withRootElement("project");
Editor programmaticEditor = new Editor(doc);

// Continue editing
Element root = programmaticEditor.root();
programmaticEditor.addElement(root, "version", "1.0");
__
```

--------------------------------

### Handle DomTrip Exceptions Appropriately

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Illustrates how to catch and handle DomTripException, which includes parsing errors, to manage potential issues during XML document processing.

```java
// ✅ Specific exception handling
try {
    String xmlContent = "<root><unclosed>";
    Document doc = Document.of(xmlContent);
    Editor editor = new Editor(doc);
    Assertions.assertNotNull(editor);
} catch (DomTripException e) {
    // Handle DomTrip errors (including parsing errors)
    System.err.println("DomTrip error: " + e.getMessage());
}
```

--------------------------------

### Parse and Edit XML with DomTrip

Source: https://maveniverse.github.io/domtrip/docs/getting-started/quick-start

Demonstrates parsing an XML string, making modifications by adding elements, and serializing back to XML while preserving original formatting and comments.

```java
// Parse XML while preserving all formatting
String originalXml = """
    <?xml version="1.0" encoding="UTF-8"?>
    <!-- Configuration file -->
    <config>
        <database>
            <host>localhost</host>
            <port>5432</port>
        </database>
    </config>
    """;

Document doc = Document.of(originalXml);
Editor editor = new Editor(doc);

// Make some changes
Element database = editor.root().descendant("database").orElseThrow();
editor.addElement(database, "username", "admin");
editor.addElement(database, "password", "secret");

// Serialize back to XML
String result = editor.toXml();
System.out.println(result);
__
```

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- Configuration file -->
<config>
    <database>
        <host>localhost</host>
        <port>5432</port>
        <username>admin</username>
        <password>secret</password>
    </database>
</config>
__
```

--------------------------------

### Add Profiles to Maven Settings

Source: https://maveniverse.github.io/domtrip/examples

Use SettingsEditor to programmatically define profiles and properties within a settings.xml document.

```java
SettingsEditor editor = new SettingsEditor();
editor.createSettingsDocument();
Element root = editor.root();

// Add profiles with properties
Element profiles = editor.insertSettingsElement(root, PROFILES);
Element profile = editor.addProfile(profiles, "development");

Element properties = editor.insertSettingsElement(profile, PROPERTIES);
editor.addProperty(properties, "maven.compiler.source", "17");
editor.addProperty(properties, "maven.compiler.target", "17");
editor.addProperty(properties, "env", "dev");

String result = editor.toXml();
```

--------------------------------

### Manage Maven Toolchains

Source: https://maveniverse.github.io/domtrip/examples

Configure JDK and custom toolchains within toolchains.xml using the ToolchainsEditor.

```java
// Create a new toolchains document
ToolchainsEditor editor = new ToolchainsEditor();
editor.createToolchainsDocument();
Element root = editor.root();

// Add JDK toolchains with convenience methods
editor.addJdkToolchain(root, "17", "openjdk", "/path/to/jdk/17");
editor.addJdkToolchain(root, "11", "adoptium", "/path/to/jdk/11");

String result = editor.toXml();
```

```java
ToolchainsEditor editor = new ToolchainsEditor();
editor.createToolchainsDocument();
Element root = editor.root();

// Add multiple JDK toolchains
editor.addJdkToolchain(root, "17", "openjdk", "/path/to/jdk/17");
editor.addJdkToolchain(root, "11", "adoptium", "/path/to/jdk/11");
editor.addJdkToolchain(root, "1.8", "oracle", "/path/to/jdk/8");

String result = editor.toXml();
```

```java
ToolchainsEditor editor = new ToolchainsEditor();
editor.createToolchainsDocument();
Element root = editor.root();

// Add JDK toolchains
editor.addJdkToolchain(root, "17", "openjdk", "/path/to/jdk/17");

// Add NetBeans toolchain
editor.addNetBeansToolchain(root, "12.0", "/path/to/netbeans");

// Add custom toolchain
Element customToolchain = editor.addToolchain(root, "protobuf");
editor.addProvides(customToolchain, "version", "3.21.0");
editor.addConfiguration(customToolchain, "protocExecutable", "/usr/local/bin/protoc");

String result = editor.toXml();
```

--------------------------------

### Serialize XML with Custom Configuration

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Serializes an XML document using custom configurations such as pretty printing or minimal output. Requires an Editor instance initialized with a Document.

```java
String xml = "<root><child>value</child></root>";
Editor editor = new Editor(Document.of(xml));

// Default serialization
String defaultXml = editor.toXml();

// Pretty printed
String prettyXml = editor.toXml(DomTripConfig.prettyPrint());

// Minimal output
String minimalXml = editor.toXml(DomTripConfig.minimal());
```

--------------------------------

### Aligning All Dependencies to Parent

Source: https://maveniverse.github.io/domtrip/docs/maven/cross-pom

Moves all dependency versions to the parent POM's dependencyManagement. Skips dependencies that are already version-less (managed).

```APIDOC
## POST /dependencies/alignAllToParent

### Description
Moves all dependency versions to the parent POM's dependencyManagement.

### Method
POST

### Endpoint
/dependencies/alignAllToParent

### Parameters
#### Query Parameters
- **parentEditor** (object) - Required - An editor object for the parent POM.
- **options** (AlignOptions) - Optional - Configuration for how versions are stored and named.

### Request Example
```json
{
  "parentEditor": { /* ... parent POM editor object ... */ },
  "options": {
    "versionSource": "PROPERTY",
    "namingConvention": "DOT_SUFFIX",
    "propertyName": "example.version"
  }
}
```

### Response
#### Success Response (200)
- **count** (integer) - The number of dependencies moved.

#### Response Example
```json
{
  "count": 5
}
```
```

--------------------------------

### Parse and Modify XML

Source: https://maveniverse.github.io/domtrip/javadoc/snapshot

Demonstrates basic parsing, element addition, and serialization using the Editor API.

```java
 // Parse XML while preserving formatting
 Document doc = Document.of(xmlString);
 Editor editor = new Editor(doc);

 // Make modifications
 Element root = editor.root();
 editor.addElement(root, "newChild", "content");

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

 // Use configuration for different output styles
 String prettyXml = editor.toXml(DomTripConfig.prettyPrint());
 String minimalXml = editor.toXml(DomTripConfig.minimal());
```

--------------------------------

### Manage and serialize documents

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Covers common document management tasks including retrieving the document or root element, creating new documents, and serializing to XML with optional pretty printing.

```java
// Get document
Editor editor = new Editor();
editor.createDocument("project");
Document document = editor.document();

// Get root element
Element root = editor.root();

// Create document with root element
editor.createDocument("project");
Element newRoot = editor.root(); // <project></project>
Assertions.assertNotNull(newRoot);

// Serialize to XML
String xml = editor.toXml();

// Pretty printing
String prettyXml = editor.toXml(DomTripConfig.prettyPrint());
__
```

--------------------------------

### Parse, Edit, and Serialize XML with DomTrip

Source: https://maveniverse.github.io/domtrip/javadoc/latest

Use this snippet to parse an XML string, make modifications using the Editor API, and then serialize the result. It demonstrates basic editing operations and serialization to different formats.

```java
// Parse XML while preserving formatting
 Document doc = Document.of(xmlString);
 Editor editor = new Editor(doc);

 // Make modifications
 Element root = editor.root();
 editor.addElement(root, "newChild", "content");

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

 // Use configuration for different output styles
 String prettyXml = editor.toXml(DomTripConfig.prettyPrint());
 String minimalXml = editor.toXml(DomTripConfig.minimal());
 
```

--------------------------------

### Check for Null Returns with Optional and Null Checks

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Demonstrates safe navigation using Optional for child elements and the traditional null check pattern with orElse(null). Use Optional for modern, concise null handling.

```java
String xml = "<project><version>1.0</version></project>";
Editor editor = new Editor(Document.of(xml));
Element root = editor.root();

// ✅ Safe navigation using Optional
Optional<Element> element = root.childElement("optional");
element.ifPresent(el -> editor.setTextContent(el, "value"));

// ✅ Or use null check pattern
Element version = root.childElement("version").orElse(null);
if (version != null) {
    editor.setTextContent(version, "updated");
}
```

--------------------------------

### Add New Elements to XML with DomTrip

Source: https://maveniverse.github.io/domtrip/examples

Demonstrates adding new elements and nested structures to an XML document using DomTrip's Editor. This is useful for building XML from scratch or extending existing structures.

```java
Document doc = Document.of("<project></project>");
Editor editor = new Editor(doc);

Element root = editor.root();

// Add dependencies section
Element dependencies = editor.addElement(root, "dependencies");

// Add a dependency with multiple children
Element dependency = editor.addElement(dependencies, "dependency");
editor.addElement(dependency, "groupId", "junit");
editor.addElement(dependency, "artifactId", "junit");
editor.addElement(dependency, "version", "4.13.2");
editor.addElement(dependency, "scope", "test");

String result = editor.toXml();
```

--------------------------------

### Use Builder Patterns for Elements

Source: https://maveniverse.github.io/domtrip/examples

Utilizes factory methods to construct new elements and append them to an existing document structure.

```java
// Create elements using factory methods (simplified builder pattern)
Element dependency = Element.of("dependency");
dependency.addChild(Element.text("groupId", "org.junit.jupiter"));
dependency.addChild(Element.text("artifactId", "junit-jupiter"));
dependency.addChild(Element.text("version", "5.9.2"));
dependency.addChild(Element.text("scope", "test"));

// Add to existing document
String pomXml = createMavenPomXml();
Document doc = Document.of(pomXml);
Editor editor = new Editor(doc);

Element dependencies = editor.root().descendant("dependencies").orElse(null);
if (dependencies == null) {
    dependencies = editor.addElement(editor.root(), "dependencies");
}
dependencies.addChild(dependency);
__
```

--------------------------------

### Fluent Builder API

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Provides a fluent interface for adding nodes to the document.

```APIDOC
## add()

### Description
Creates a fluent builder for adding nodes such as elements or comments to the document structure.
```

--------------------------------

### Add Dependencies to Maven POM with DomTrip Maven Extension

Source: https://maveniverse.github.io/domtrip/examples

Shows how to add dependencies to a Maven POM file using the PomEditor. It includes adding a dependency with its scope, ensuring correct structure and ordering.

```java
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");
```

--------------------------------

### Align Single Dependency Version to Parent POM

Source: https://maveniverse.github.io/domtrip/docs/maven/cross-pom

Move a single dependency's version to the parent POM's dependencyManagement. Configure version source and property naming convention using AlignOptions.

```java
String childPom = """
        <?xml version="1.0" encoding="UTF-8"?>
        <project xmlns="http://maven.apache.org/POM/4.0.0">
          <modelVersion>4.0.0</modelVersion>
          <parent>
            <groupId>com.example</groupId>
            <artifactId>parent-project</artifactId>
            <version>1.0.0</version>
          </parent>
          <artifactId>child-module</artifactId>
          <dependencies>
            <dependency>
              <groupId>com.google.guava</groupId>
              <artifactId>guava</artifactId>
              <version>32.1.2-jre</version>
            </dependency>
          </dependencies>
        </project>
        """;

String parentPom = """
        <?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>parent-project</artifactId>
          <version>1.0.0</version>
          <packaging>pom</packaging>
        </project>
        """;

PomEditor child = new PomEditor(Document.of(childPom));
PomEditor parent = new PomEditor(Document.of(parentPom));

// Move a single dependency's version to the parent's dependencyManagement
Coordinates guava = Coordinates.of("com.google.guava", "guava", null);
child.dependencies()
        .alignToParent(
                guava,
                parent,
                AlignOptions.builder()
                        .versionSource(AlignOptions.VersionSource.PROPERTY)
                        .namingConvention(AlignOptions.PropertyNamingConvention.DOT_SUFFIX)
                        .build());

// Child POM: dependency is now version-less
// Parent POM: has dependencyManagement entry + guava.version property
__
```

--------------------------------

### Preserve XML Formatting

Source: https://maveniverse.github.io/domtrip/examples

Confirms that DomTrip maintains original document indentation and style during serialization.

```java
String xml = createConfigXml();
Document doc = Document.of(xml);
Editor editor = new Editor(doc);

// DomTrip automatically preserves formatting
// No special configuration needed
String result = editor.toXml(); // Maintains original indentation and style
__
```

--------------------------------

### Set and Manage XML Attributes

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Use `setAttribute`, `removeAttribute`, and `setAttributes` for efficient attribute management. The API intelligently infers quote styles and preserves existing formatting.

```java
String xml = "<dependency scope='test'></dependency>";
Editor editor = new Editor(Document.of(xml));
Element element = editor.root();

// For XML: <element attr1='existing' attr2="another"/>
editor.setAttribute(element, "attr1", "updated"); // Preserves single quotes
editor.setAttribute(element, "attr3", "new"); // Infers quote style from existing

// Remove attribute
editor.removeAttribute(element, "deprecated");

// Set multiple attributes
Map<String, String> attrs = Map.of(
        "scope", "test",
        "optional", "true");
editor.setAttributes(element, attrs);

// Get attribute value
String scopeValue = element.attribute("scope");

// Check if attribute exists
boolean hasOptional = element.hasAttribute("optional");

```

--------------------------------

### Load XML from String

Source: https://maveniverse.github.io/domtrip/docs/getting-started/quick-start

Loads an XML document from a string representation using DomTrip's Document.of() method.

```java
// From string
String xmlString = createConfigXml();
Document doc = Document.of(xmlString);
Editor editor = new Editor(doc);
__
```

--------------------------------

### Serialization

Source: https://maveniverse.github.io/domtrip/docs/api/editor

Methods for serializing the XML document to a string.

```APIDOC
## toXml()

### Description
Serializes the document to an XML string with preserved formatting.

### Method
GET

### Endpoint
N/A

### Parameters
None

### Request Example
```java
Editor editor = new Editor();
editor.createDocument("project");
String xml = editor.toXml();
```

### Response
#### Success Response (200)
- **xml** (String) - The XML representation of the document.
```

```APIDOC
## toXml(DomTripConfig config)

### Description
Serializes the document to an XML string with preserved formatting using a specified configuration.

### Method
GET

### Endpoint
N/A

### Parameters
- **config** (DomTripConfig) - Required - The configuration for serialization, e.g., pretty printing.

### Request Example
```java
Editor editor = new Editor();
editor.createDocument("project");
String prettyXml = editor.toXml(DomTripConfig.prettyPrint());
```

### Response
#### Success Response (200)
- **xml** (String) - The XML representation of the document with specified formatting.
```

--------------------------------

### Manipulate POM Files with Core Library

Source: https://maveniverse.github.io/domtrip/examples

Use the core Editor class for low-level XML manipulation, such as adding dependencies or updating version tags.

```java
String pomXml = """
    <?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-app</artifactId>
        <version>1.0.0</version>
    </project>
    """;

Document doc = Document.of(pomXml);
Editor editor = new Editor(doc);
Element project = editor.root();

// Add dependencies section if it doesn't exist
Element dependencies = project.descendant("dependencies").orElse(null);
if (dependencies == null) {
    dependencies = editor.addElement(project, "dependencies");
}

// Add Spring Boot starter
Element springDep = editor.addElement(dependencies, "dependency");
editor.addElement(springDep, "groupId", "org.springframework.boot");
editor.addElement(springDep, "artifactId", "spring-boot-starter-web");
editor.addElement(springDep, "version", "3.2.0");

String result = editor.toXml();}
```

```java
String pomContent = createMavenPomXml();
Document doc = Document.of(pomContent);
Editor editor = new Editor(doc);

// Update project version
Element version = editor.root().descendant("version").orElse(null);
if (version != null) {
    editor.setTextContent(version, "2.0.0");
}

// Update parent version if exists
Element parent = editor.root().descendant("parent").orElse(null);
if (parent != null) {
    Element parentVersion = parent.descendant("version").orElse(null);
    if (parentVersion != null) {
        editor.setTextContent(parentVersion, "2.1.0");
    }
}}
```

--------------------------------

### Fluent Builder API for Node Creation

Source: https://maveniverse.github.io/domtrip/docs/api/editor

The fluent builder API provides a concise way to add elements and comments to the XML document. It supports adding attributes and text content to new elements.

```java
String xml = "<project></project>";
Editor editor = new Editor(Document.of(xml));
Element parent = editor.root();

editor.add()
        .element("dependency")
        .to(parent)
        .withAttribute("scope", "test")
        .withText("content")
        .build();

editor.add().comment().to(parent).withContent(" This is a comment ").build();

```

--------------------------------

### Load XML from InputStream

Source: https://maveniverse.github.io/domtrip/docs/getting-started/quick-start

Loads an XML document from an InputStream, with automatic encoding detection. Asserts the root element name.

```java
// From InputStream with automatic encoding detection
try (InputStream inputStream = Files.newInputStream(tempFile)) {
    Document doc3 = Document.of(inputStream);
    Editor editor3 = new Editor(doc3);
    Assertions.assertEquals("config", editor3.root().name());
}
__
```

--------------------------------

### Use Optional for Safe Navigation

Source: https://maveniverse.github.io/domtrip/examples

Leverages Java Optional API to perform conditional element creation and modification.

```java
String xml = createMavenPomXml();
Document doc = Document.of(xml);
Editor editor = new Editor(doc);

editor.root()
        .descendant("dependencies")
        .map(deps -> editor.addElement(deps, "dependency"))
        .ifPresent(dep -> {
            editor.addElement(dep, "groupId", "org.example");
            editor.addElement(dep, "artifactId", "example-lib");
        });
__
```

--------------------------------

### Add XML Element with Attributes

Source: https://maveniverse.github.io/domtrip/docs/getting-started/quick-start

Adds a new XML element and then sets its attributes and child elements.

```java
// Element with attributes
Element element = editor.addElement(parent, "dependency");
editor.setAttribute(element, "scope", "test");
editor.addElement(element, "groupId", "junit");
__
```

--------------------------------

### Aligning Single Dependency to Parent

Source: https://maveniverse.github.io/domtrip/docs/maven/cross-pom

Moves a single dependency's version to the parent POM's dependencyManagement. Skips dependencies that are already version-less (managed).

```APIDOC
## POST /dependencies/alignToParent

### Description
Moves a single dependency's version to the parent POM's dependencyManagement.

### Method
POST

### Endpoint
/dependencies/alignToParent

### Parameters
#### Query Parameters
- **coords** (string) - Required - The coordinates of the dependency to align.
- **parentEditor** (object) - Required - An editor object for the parent POM.
- **options** (AlignOptions) - Optional - Configuration for how versions are stored and named.

### Request Example
```json
{
  "coords": "com.example:my-library",
  "parentEditor": { /* ... parent POM editor object ... */ },
  "options": {
    "versionSource": "PROPERTY",
    "namingConvention": "DOT_SUFFIX",
    "propertyName": "example.version"
  }
}
```

### Response
#### Success Response (200)
- **count** (integer) - The number of dependencies moved.

#### Response Example
```json
{
  "count": 1
}
```
```

--------------------------------

### Configure AlignOptions for Cross-POM Alignment

Source: https://maveniverse.github.io/domtrip/docs/maven/cross-pom

Use AlignOptions to specify how versions are managed in the parent POM. Configure the version source, property naming convention, or explicit property names.

```java
AlignOptions options = AlignOptions.builder()
    .versionSource(AlignOptions.VersionSource.PROPERTY)
    .namingConvention(AlignOptions.PropertyNamingConvention.DOT_SUFFIX)
    .propertyName("guava.version")
    .build();
```

--------------------------------

### Manipulate XML Attributes

Source: https://maveniverse.github.io/domtrip/examples

Demonstrates setting, removing, and checking for the existence of attributes on XML elements.

```java
String xmlContent = createConfigXml();
Document doc = Document.of(xmlContent);
Editor editor = new Editor(doc);

// Set attributes
Element element = editor.root().descendant("database").orElseThrow();
editor.setAttribute(element, "scope", "test");
editor.setAttribute(element, "optional", "true");

// Remove attributes
editor.removeAttribute(element, "scope");

// Check if attribute exists
if (element.hasAttribute("optional")) {
    String value = element.attribute("optional");
    System.out.println("Optional: " + value);
}
__
```

--------------------------------

### Find XML Elements with Streams

Source: https://maveniverse.github.io/domtrip/docs/getting-started/quick-start

Finds XML elements using stream-based navigation and filtering by element name.

```java
String xml = createConfigXml();
Document doc = Document.of(xml);
Editor editor = new Editor(doc);

// Stream-based navigation
editor.root()
        .descendants()
        .filter(e -> e.name().equals("port"))
        .findFirst()
        .ifPresent(port -> System.out.println("Port: " + port.textContent()));
__
```
Tokens:
Raw