org.onosproject.store.service

Interface DocumentTree<V>

Type Parameters:

V - document tree value type

All Superinterfaces:

DistributedPrimitive

All Known Implementing Classes:

DefaultDocumentTree

@NotThreadSafe
public interface DocumentTree<V>
extends DistributedPrimitive

A hierarchical document tree data structure.

Nested Class Summary

Nested classes/interfaces inherited from interface org.onosproject.store.service.DistributedPrimitive

DistributedPrimitive.Status, DistributedPrimitive.Type

Field Summary

Fields inherited from interface org.onosproject.store.service.DistributedPrimitive

DEFAULT_OPERATION_TIMEOUT_MILLIS

Method Summary

Modifier and Type	Method and Description
void	addListener(DocumentPath path, DocumentTreeListener<V> listener) Registers a listener to be notified when a subtree rooted at the specified path is modified.
default void	addListener(DocumentTreeListener<V> listener) Registers a listener to be notified when the tree is modified.
boolean	create(DocumentPath path, V value) Creates a document tree node if one does not exist already.
boolean	createRecursive(DocumentPath path, V value) Creates a document tree node by first creating any missing intermediate nodes in the path.
Versioned<V>	get(DocumentPath path) Returns a document tree node.
Map<String,Versioned<V>>	getChildren(DocumentPath path) Returns the child values for this node.
default DistributedPrimitive.Type	primitiveType() Returns the type of primitive.
void	removeListener(DocumentTreeListener<V> listener) Unregisters a previously added listener.
Versioned<V>	removeNode(DocumentPath path) Removes the node with the specified path.
boolean	replace(DocumentPath path, V newValue, long version) Conditionally updates a tree node if the current version matches a specified version.
boolean	replace(DocumentPath path, V newValue, V currentValue) Conditionally updates a tree node if the current value matches a specified value.
DocumentPath	root() Returns the path to root of the tree.
Versioned<V>	set(DocumentPath path, V value) Creates or updates a document tree node.

Methods inherited from interface org.onosproject.store.service.DistributedPrimitive

addStatusChangeListener, applicationId, destroy, name, removeStatusChangeListener, statusChangeListeners

Method Detail

primitiveType

default DistributedPrimitive.Type primitiveType()

Description copied from interface: DistributedPrimitive

Returns the type of primitive.

Specified by:

primitiveType in interface DistributedPrimitive

Returns:

primitive type

root

DocumentPath root()

Returns the path to root of the tree.

Returns:

path to root of the tree

getChildren

Map<String,Versioned<V>> getChildren(DocumentPath path)

Returns the child values for this node.

Parameters:

path - path to the node

Returns:

mapping from a child name to its value

Throws:

NoSuchDocumentPathException - if the path does not point to a valid node

get

Versioned<V> get(DocumentPath path)

Returns a document tree node.

Parameters:

path - path to node

Returns:

node value or null if path does not point to a valid node

set

Versioned<V> set(DocumentPath path,
                 V value)

Creates or updates a document tree node.

Parameters:

path - path for the node to create or update

value - the non-null value to be associated with the key

Returns:

the previous mapping or null if there was no previous mapping

Throws:

NoSuchDocumentPathException - if the parent node (for the node to create/update) does not exist

create

boolean create(DocumentPath path,
               V value)

Creates a document tree node if one does not exist already.

Parameters:

path - path for the node to create

value - the non-null value to be associated with the key

Returns:

returns true if the mapping could be added successfully, false otherwise

Throws:

NoSuchDocumentPathException - if the parent node (for the node to create) does not exist

createRecursive

boolean createRecursive(DocumentPath path,
                        V value)

Creates a document tree node by first creating any missing intermediate nodes in the path.

Parameters:

path - path for the node to create

value - the non-null value to be associated with the key

Returns:

returns true if the mapping could be added successfully, false if a node already exists at that path

Throws:

IllegalDocumentModificationException - if path points to root

replace

boolean replace(DocumentPath path,
                V newValue,
                long version)

Conditionally updates a tree node if the current version matches a specified version.

Parameters:

path - path for the node to create

newValue - the non-null value to be associated with the key

version - current version of the value for update to occur

Returns:

returns true if the update was made and the tree was modified, false otherwise

Throws:

NoSuchDocumentPathException - if the parent node (for the node to create) does not exist

replace

boolean replace(DocumentPath path,
                V newValue,
                V currentValue)

Conditionally updates a tree node if the current value matches a specified value.

Parameters:

path - path for the node to create

newValue - the non-null value to be associated with the key

currentValue - current value for update to occur

Returns:

returns true if the update was made and the tree was modified, false otherwise. This method returns false if the newValue and currentValue are same.

Throws:

NoSuchDocumentPathException - if the parent node (for the node to create) does not exist

removeNode

Versioned<V> removeNode(DocumentPath path)

Removes the node with the specified path.

Parameters:

path - path for the node to remove

Returns:

the previous value of the node or null if it did not exist

Throws:

IllegalDocumentModificationException - if the remove to be removed

addListener

void addListener(DocumentPath path,
                 DocumentTreeListener<V> listener)

Registers a listener to be notified when a subtree rooted at the specified path is modified.

Parameters:

path - path to root of subtree to monitor for updates

listener - listener to be notified

removeListener

void removeListener(DocumentTreeListener<V> listener)

Unregisters a previously added listener.

Parameters:

listener - listener to unregister

addListener

default void addListener(DocumentTreeListener<V> listener)

Registers a listener to be notified when the tree is modified.

Parameters:

listener - listener to be notified