Package com.atlassian.adf.model.node

Class Doc

  • All Implemented Interfaces:
    Element, Node, ContentNode<Doc,​DocContent>
    @Documentation(state=REVIEWED,
               date="2023-07-26")
public class Doc
extends AbstractContentNode<Doc,​DocContent>
    The root container node of every Atlassian Document Format (ADF) document.

    About ADF

    ADF stands for Atlassian Document Format. It is a structured JSON document, conforming to a documented JSON schema, that represents a piece of rich content to be displayed in an Atlassian Cloud application. It might represent a comment on a Confluence page or the description of an issue in Jira.

    About ADF's Structure

    An ADF document is composed of a hierarchy of nodes. There are two categories of nodes: block and inline. Block nodes define the structural elements of the document such as headings, paragraphs, tables, horizontal rule separators, lists, and the like. Inline nodes specify the document content such as text and images. Several node types can also accept marks that decorate that node type with formatting information or text markup such as bold, italics, and links.

    A document is ordered; that is, there's a single sequential path through it: traversing a document in sequence and concatenating the nodes yields content in the correct order. Every independent ADF value must consist of a single well-formed doc node. The various top-level block nodes (which in this library are those marked with the DocContent interface) may be added to this doc to indicate the rich content that should be displayed for it.

    About This Library

    This library is a manually constructed representation of the JSON schema that has been published for ADF. It does not consult that schema when validating the content, so there is always some risk that it will disagree with some aspect of the schema. However, if any such discrepancies are found, please report this as a bug.

    Additionally, any new features that are added to the schema have very limited support in this library and may not be preserved across round trips if the library version is too far behind. See Schema.version() for information about which JSON schema version was consulted at the time this library was last checked against it.

    Most of the elements that are available in this library share the following features:

    • The various elements use static factories with appropriate names so that they can conveniently be used as static imports and combined intuitively like in the Java example below.
    • Most elements are mutable. The only cases where they aren't are those that have little or no state, such that making them mutable does not really make any sense. For example, strong marks don't have anything to mutate.
    • The only erroneous state that the library usually tolerates is failing to add content to a node that requires it. Required parameters are demanded and validated by the static factory methods used to construct the node and that construction is not complete until all of them have been set. These have names like Status.Partial.NeedsColor that try to help indicate why the element is not fully constructed.

    Example

    Java

     doc(
         p(
                 text("Hello "),
                 text("world").strong()
         )
 );

    ADF

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

    Result

    Hello world

    See Also:
    toMap(), parse(Map), Node - doc

    • Method Detail

      • doc

        public static Doc doc()
        Returns:
        a new, empty document

      • doc

        public static Doc doc​(DocContent content)
        Returns:
        a new document with the given content

      • doc

        public static Doc doc​(DocContent... content)
        Returns:
        a new document with the given content

      • doc

        public static Doc doc​(Iterable<? extends DocContent> content)
        Returns:
        a new document with the given content

      • doc

        public static Doc doc​(Stream<? extends DocContent> content)
        Returns:
        a new document with the given content

      • doc

        public static Doc doc​(Doc.Version version)
        Returns:
        a new document with the given version

      • doc

        public static Doc doc​(Doc.Version version,
                      DocContent content)
        Returns:
        a new document with the given version and content

      • doc

        public static Doc doc​(Doc.Version version,
                      DocContent... content)
        Returns:
        a new document with the given version and content

      • doc

        public static Doc doc​(Doc.Version version,
                      Stream<? extends DocContent> content)
        Returns:
        a new document with the given version and content

      • contentClass

        public Class<DocContent> contentClass()
        Description copied from interface: ContentNode
        Returns Class<N>, the class representing the type of items held by this node.

      • copy

        public Doc copy()
        Description copied from interface: Element
        Returns a deep copy of this element, including copies of any nodes or marks that it contains. The copy will not necessarily be in exactly the same state as the original in some cases. For example, a text node that is used inside a codeBlock will have the ability to use marks on it disabled, but a copy made of the text node using this method will not similarly disallow marks unless it is also added to a content node with those same restrictions.

        Implementations notes:

        • Implementations should narrow the return type.
        • Implementations should return this if the element is immutable. The @Immutable annotation should be used on the class to offer additional confirmation of this intent.
        • Implementations should return parse(toMap()) if they have state.
        • While there may be cases where it is worthwhile to do something more efficient than the conversion to a map and back, this is discouraged because it would add yet another fragile piece of code that breaks when new data is added to the node. The parse and toMap methods already have to be updated in these circumstances, so it makes sense to take advantage of that.
        Returns:
        a copy of this element, or this if the element is immutable anyway

      • version

        public Doc version​(Doc.Version version)
        Sets a new version for this document.
        Parameters:
        version - the new document version
        Returns:
        this

      • version

        public Doc.Version version()
        Returns the version of the ADF standard used for this document.
        Returns:
        the version of the ADF standard used for this document.

      • elementType

        public String elementType()
        Description copied from interface: Element
        The type value that identifies this element, such as "paragraph" or "strong".

      • toMap

        public Map<String,​?> toMap()
        Renders this document as a single map of string keys to their values, suitable for direct translation into JSON.
        Returns:
        this document, as a map

      • parse

        public static Doc parse​(Map<String,​?> map)
        Parses ADF from a single map of string keys to their values, suitable for direct interpretation from JSON.
        Parameters:
        map - the map of keys to values representing the ADF
        Returns:
        the parsed and validated document
        Throws:
        AdfException - if there is a problem parsing the document

      • appendPlainText

        public void appendPlainText​(StringBuilder sb)
        Description copied from interface: Node
        Renders this node as plain-text suitable for viewing by end users. This is equivalent to calling Node.toPlainText() and appending the result to the given buffer, except that it may be slightly more efficient, since it will write directly to the existing buffer instead of using a temporary buffer and having to make a copy of the result.
        Specified by:
        appendPlainText in interface Node
        Overrides:
        appendPlainText in class AbstractContentNode<Doc,​DocContent>
        Parameters:
        sb - where to write the result