Package com.atlassian.adf.model.node.type

Interface ContentNode<C extends ContentNode<C,N>,N extends Node>

Type Parameters:

C - this content node's type

N - the node type that it holds

All Superinterfaces:

Element, Node

All Known Subinterfaces:

ListNode<L>, TableCellNode<N>

All Known Implementing Classes:

AbstractContentNode, AbstractListNode, AbstractMarkedContentNode, AbstractTableCellNode, Blockquote, BodiedExtension, BulletList, Caption, CodeBlock, DecisionItem, DecisionList, Doc, Expand, Heading, LayoutColumn, LayoutSection, ListItem, MediaGroup, NestedExpand, OrderedList, Panel, Paragraph, Table, TableCell, TableHeader, TableRow, TaskItem, TaskList

public interface ContentNode<C extends ContentNode<C,N>,N extends Node>
extends Node

Describes the behaviour common to all nodes that act as holders of other content.

For the most part, this interface is implemented by all node types that have a "content" section, with the mediaSingle node type as the notable exception.

Nested Class Summary

Nested classes/interfaces inherited from interface com.atlassian.adf.model.node.Node

Node.Attr, Node.Key, Node.Type

Method Summary

Modifier and Type	Method	Description
Stream<Node>	allNodes()	Produces a stream consisting of the in-order traversal of this node and all of its contents, where any nested ContentNodes are also expanded.
default <T extends Node> Stream<T>	allNodesOfType(Class<T> nodeClass)	Returns a stream of all descendant nodes of the given type.
default <T extends Node> List<T>	allNodesOfTypeAsList(Class<T> nodeClass)	Returns a list of all decendant nodes of the given type.
C	clear()	Discards all existing content in this node.
List<N>	content()	Returns the existing contents of this content node.
C	content(Iterable<? extends N> content)	Adds the given nodes as content within this containing node.
C	content(Stream<? extends N> content)	Adds the given nodes as content within this containing node.
C	content(N content)	Adds the given node as content within this containing node.
C	content(N... content)	Adds the given nodes as content within this containing node.
Class<N>	contentClass()	Returns Class<N>, the class representing the type of items held by this node.
C	copy()	Returns a deep copy of this element, including copies of any nodes or marks that it contains.
boolean	isEmpty()
void	removeIf(Predicate<? super N> predicate)	Discards all content that matches the given predicate.
void	replaceContent(List<? extends N> content)	Completely replace this content node's existing content items with the new ones provided.
void	transformContent(Function<? super N,? extends N> transformer)	Applies a transformation to the immediate children of this content node.
<T extends Node> void	transformDescendants(Class<T> targetNodeClass, Function<? super T,? extends T> transformer)	Applies a transformation to all descendants of this node that match the given type.

Methods inherited from interface com.atlassian.adf.model.Element

elementType, isSupported, toMap, validate

Methods inherited from interface com.atlassian.adf.model.node.Node

appendPlainText, toPlainText

Method Detail

copy

C 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.

Specified by:

copy in interface Element

Specified by:

copy in interface Node

Returns:

a copy of this element, or this if the element is immutable anyway

contentClass

Class<N> contentClass()

Returns Class<N>, the class representing the type of items held by this node.

isEmpty

boolean isEmpty()

Returns:

true if this content node is completely empty, which for many such nodes is not valid

content

List<N> content()

Returns the existing contents of this content node.

Notes:

• The returned list cannot be modified directly.
• Whether it is a live view of the node's contents or a copy is left unspecified. Callers are advised to make an explicit copy of the list if this matters, such as when the node's contents will be modified while iterating over this list.
• The nodes within the list will generally be mutable. The caller should make an explicit copy of the node before modifying it if the original is not meant to be affected.

Returns:

the existing contents of this content node.

content

C content(N content)

Adds the given node as content within this containing node.

The content is processed in the same way as if it were the single value provided to content(Node[]).

Parameters:

content - the content to add

Returns:

this

See Also:

content(Node[])

content

C content(N... content)

Adds the given nodes as content within this containing node.

Each content item is validated as acceptable content before it is added. If validation is successful, then it is added to this node's content before the next node is validated, so the validation method is permitted to rely on the content() value being up-to-date at all times.

If validation fails for a particular content item, then those particular content items are discarded, but any content nodes that follow will still be attempted.

Parameters:

content - the content to add

Returns:

this

Throws:

AdfException - for the first content item to fail validation, with additional failures included as suppressed exceptions. Note that the reported index is that of the array index on this method, not its position in the node's content.

content

C content(Iterable<? extends N> content)

Adds the given nodes as content within this containing node.

The content is processed just as if its elements were passed to content(Node[]).

Parameters:

content - the content to add

Returns:

this

See Also:

content(Node[])

content

C content(Stream<? extends N> content)

Adds the given nodes as content within this containing node.

Each content item is validated as acceptable content before it is added. If validation is successful, then it is added to this node's content before the next node is validated, so the validation method is permitted to rely on the content() value being up-to-date at all times.

If validation fails for a particular content item, then those particular content items are discarded, but any content nodes that follow will still be attempted.

Parameters:

content - the content to add

Returns:

this

Throws:

AdfException - for the first content item to fail validation, with additional failures included as suppressed exceptions. Note that the reported index is that of the stream provided to this method.

allNodes

Stream<Node> allNodes()

Produces a stream consisting of the in-order traversal of this node and all of its contents, where any nested ContentNodes are also expanded.

Example

If a Doc is constructed from this input:

   {
     "type": "paragraph",
     "content": [
       {
         "type": "text",
         "text": "Hello "
       },
       {
         "type": "text",
         "text": "world",
         "marks": [
           {
             "type": "textColor",
             "attrs": {
               "color": "#00ff00"
             }
           }
         ]
       },
       {
         "type": "text",
         "text": "!"
       }
     ]
   }
 

then calling doc.allNodes() would produce the following stream of nodes:

• The doc node itself

• The paragraph node

• The text node containing "Hello "

• The text node containing "world"

• The text node containing "!"

Note that marks are not considered separate nodes; they are part of the containing text node.

Returns:

a stream of this node and the deep expansion of its contents

clear

C clear()

Discards all existing content in this node.

Note that for some node types, it is not valid for the node to be left empty and new content must be added to replace it.

Returns:

this

removeIf

void removeIf(Predicate<? super N> predicate)

Discards all content that matches the given predicate.

WARNING: This uses replaceContent(List) in an attempt to ensure that the node is left in a valid state. All the same caveats apply.

Parameters:

predicate - test for which content nodes should be removed

replaceContent

void replaceContent(List<? extends N> content)

Completely replace this content node's existing content items with the new ones provided. If this results in an exception being thrown (such as rejecting the new first content item in a node like ListItem that has restrictions for it), then the old content is restored before the exception is propagated to the caller.

WARNING: Although this method tries very hard to ensure that the content node is left in a valid state, it does still allow content to be removed, possibly leaving it entirely empty. Just as with clear(), it is up to the caller to follow this up by adding new content as required to establish a valid state for the content node, or the problem may not be detected until the node is validated during some future use. Proceed with caution.

Parameters:

content - the new content list for this node

allNodesOfType

default <T extends Node> Stream<T> allNodesOfType(Class<T> nodeClass)

Returns a stream of all descendant nodes of the given type.

The search is an in-order traversal of all child nodes.

Type Parameters:

T - nodeClass, as a type inference

Parameters:

nodeClass - the node type to include in the stream

Returns:

a stream of all descendant nodes of the given type

allNodesOfTypeAsList

default <T extends Node> List<T> allNodesOfTypeAsList(Class<T> nodeClass)

Returns a list of all decendant nodes of the given type.

The list is the result of an in-order traversal of all child nodes.

Type Parameters:

T - nodeClass, as a type inference

Parameters:

nodeClass - the node type to include in the list

Returns:

a list of all descendant nodes of the given type

transformContent

void transformContent(Function<? super N,? extends N> transformer)

Applies a transformation to the immediate children of this content node.

The transformer has the following characteristics:

1. It will be called once for each piece of content currently held by this parent content node.
2. It may return that same object to keep that piece of content.
3. It may return same other object that is suitable for the parent content node, and that node will replace the original value.
4. It may return null, in which case that content item will be removed, instead.

WARNING: Once all content items have been processed by the transformer, this method uses replaceContent(List) to perform the update if the structure of the list has changed (that is, if any content items are removed or replaced). In addition to the warnings on that method, note that since the transformer has already been called on the content items, they may have been modified in ways that impact the validity of the content node even if its content item list is left unchanged. If so, this may not be detected until some time later when the node's validity is rechecked for some other reason. Proceed with caution.

Parameters:

transformer - the transforming function

transformDescendants

<T extends Node> void transformDescendants(Class<T> targetNodeClass,
                                           Function<? super T,? extends T> transformer)

Applies a transformation to all descendants of this node that match the given type.

The transformer has the following characteristics:

1. It will be called once for each piece of content currently held by this content node or any of its descendants that matches the given targetNodeClass.
2. It may return that same object to keep that node within the content node that contains it.
3. It may return same other object that is suitable for the parent content node that contained it, and that new node will replace the original value.
4. It may return null, in which case that content item will be removed, instead.

WARNING: Once all content items have been processed by the transformer, this method uses replaceContent(List) to perform the update if the structure of the list has changed (that is, if any content items are removed or replaced). In addition to the warnings on that method, note that since the transformer has already been called on the content items, they may have been modified in ways that impact the validity of the content node even if its content item list is left unchanged. If so, this may not be detected until some time later when the node's validity is rechecked for some other reason. Proceed with caution.

IMPLEMENTATION NOTE

This method has special support for MediaSingle nodes, which do not implement the ContentNode interface even though they contain child nodes. In particular:

1. The media and (if present) caption nodes are included in the traversal
2. If the transformer removes a media node that is inside of a mediaSingle, then that mediaSingle is also removed without visiting its caption.

Parameters:

transformer - the transforming function