1. Atlassian Avatar Atlassian
  2. Product Fabric
  3. adf-builder-java

Wiki

Clone wiki

adf-builder-java / Home

View History

Quick Start Guide

Too simple for you? Check out the Technical guide.

Just looking for the node reference? Jump directly to the Index.

Introduction

This library is meant to make it a bit easier to programmatically construct an ADF document from Java code. The core library operates entirely with basic Java collections, using Map<String, ?> to represent JSON objects and List<?> to represent arrays. It does, however, also provide several small adapter libraries so that you can use something like Jackson to marshall the ADF documents all the way to String and back. Or you can create your own parser, if you prefer – there's some glue available for that, too.

License

This library is part of the Atlassian Platform, and is licensed to external developers under Section 3 of the Atlassian Developer Terms.

Change Log

Each release is documented in the Change Log.

Module List

This project is split over several modules that are published to packages.atlassian.com with com.atlassian.adf as the groupId. They use the following artifactId values:

  • adf-builder-java – the core library, based around the Doc class
  • adf-builder-java-gson – an adapter that uses Google GSON for JSON serialization
  • adf-builder-java-html – an EXPERIMENTAL parser to generate ADF from HTML
  • adf-builder-java-jackson1 – an adapter that uses Jackson v1 for JSON serialization
  • adf-builder-java-jackson2 – an adapter that uses Jackson v2 for JSON serialization
  • adf-builder-java-markdown – an EXPERIMENTAL parser to generate ADF from Markdown
  • adf-builder-java-schema – a formal JSON schema validator (requires Jackson v2)
  • adf-builder-java-wiki - a library for converting between ADF and the legacy Wiki Markup format

Quick Example

Maven Dependencies

The most recent version of this library can be found on packages.atlassian.com. These packages and some of their dependencies are provided by Atlassian and may not be available on public mirrors. You will need to ensure that your project is configured to use the Atlassian repositories by following these instructions.

The following pom.xml excerpt should give a general idea of what you will need:

  <properties>
    <adf-builder-java.version>0.34.1</adf-builder-java.version>
  </properties>

  <!-- Enable Atlassian Maven repository -->
  <repositories>
    <repository>
        <id>atlassian-public</id>
        <url>https://packages.atlassian.com/mvn/maven-external/</url>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
            <checksumPolicy>warn</checksumPolicy>
        </snapshots>
        <releases>
            <enabled>true</enabled>
            <checksumPolicy>warn</checksumPolicy>
        </releases>
    </repository>
  </repositories>

  <!-- Using the core library, Jackson 2 for JSON parsing, and Markdown conversion support -->
  <dependencies>
    <dependency>
      <groupId>com.atlassian.adf</groupId>
      <artifactId>adf-builder-java</artifactId>
      <version>${adf-builder-java.version}</version>
    </dependency>
    <dependency>
        <groupId>com.atlassian.adf</groupId>
        <artifactId>adf-builder-java-jackson2</artifactId>
        <version>${adf-builder-java.version}</version>
    </dependency>
    <dependency>
      <groupId>com.atlassian.adf</groupId>
      <artifactId>adf-builder-java-markdown</artifactId>
      <version>${adf-builder-java.version}</version>
    </dependency>
  </dependencies>

Java

import com.atlassian.adf.jackson2.AdfJackson2;
import com.atlassian.adf.model.node.Doc;

import static com.atlassian.adf.model.mark.Strong.strong;
import static com.atlassian.adf.model.node.Doc.doc;
import static com.atlassian.adf.model.node.Paragraph.p;
import static com.atlassian.adf.model.node.Rule.hr;
import static com.atlassian.adf.model.node.Text.text;

public class Example {
    public static void main(String[] args) {
        Doc doc = doc(
                p("Hello"),
                hr(),
                p(
                        text("world", strong()),
                        text("!")
                )
        );

        AdfJackson2 parser = new AdfJackson2();
        String json = parser.marshall(doc);
        System.out.println(json);
        Doc reconstructed = parser.unmarshall(json);
        if (!doc.equals(reconstructed)) {
            throw new AssertionError("Hmmmm... they should have matched...");
        }
    }
}

ADF

{
    "type": "doc",
    "version": 1,
    "content": [
        {
            "type": "paragraph",
            "content": [
                {
                    "type": "text",
                    "text": "Hello"
                }
            ]
        },
        {
            "type": "rule"
        },
        {
            "type": "paragraph",
            "content": [
                {
                    "type": "text",
                    "text": "world",
                    "marks": [
                        {
                            "type": "strong"
                        }
                    ]
                },
                {
                    "type": "text",
                    "text": "!"
                }
            ]
        }
    ]
}

Result

Hello

world!

Additional Resources

Public

Atlassian Internal

Updated