public class NavuList extends NavuNode implements Iterable<NavuListEntry>
NavuList is a representation of the yang list node.
A NavuList holds a map of list entries
NavuListEntry associated with a key ConfKey thus
each child is indexed by its key and individual entry is retrieved
by elem(ConfKey) method.
The elem method declare that it returns
a NavuContainer but its underlying entry subtype is actually a
NavuListEntry.
NavuList also supports keyless lists ( list without keys).
If the yang list is keyless individual child is retrieved
through its "pseudo-key" which must always be of type ConfInt64.
NavuList keyLessList = ...;
ConfKey pseudo = new ConfKey(new ConfInt64(10));
NavuContainer entry10 = keyLessList.elem(pseudo);
assert ( entry10.isListInstance() ) ;
assert ( entry10.getInfo().isListEntry( ) );
NavuListEntry navuListEntry10 = (NavuListEntry) entry10;
When accessing individual elements trough elem
NavuList will only make one single exists
call (over MAAPI or CDB depending on the context ) to check the
existence of the key thus making the operation cheap.
The set of children or its sub elements are retrieved through
children() , elements() or by retrieving
a iterator iterator().
NavuList serverList = ...;
for ( NavuNode childEntry : serverList.children() ) {
//Do something with each list instance
}
NavuList also implements the Iterable interface
which means that child elements could be retrieved implicitly.
NavuList serverList = ...;
for ( NavuNode childEntry : serverList ) {
//Do something with each list instance
}
NavuList loads its children on demand but
when invoking the methods children,
elements,encodeXML,entrySet,
isEmpty,keySet,select
it must trigger a load of all is keys from the
datastore. Use this methods with caution when the list is big.
Try using the iterator as much as possible.
| Modifier and Type | Class and Description |
|---|---|
static class |
NavuList.WhereTo |
| Modifier and Type | Method and Description |
|---|---|
Collection<NavuNode> |
children()
Returns elements contained by the list node.
|
boolean |
containsNode(ConfKey key)
Returns true if and only if this
NavuList
contains a NavuListEntry where
NavuListEntry.getKey() equals the specified
key. |
boolean |
containsNode(NavuContainer node)
Returns true if this NavuList maps a
ConfKey to the specified NavuContainer.
|
boolean |
containsNode(String keyStr)
Returns true if this NavuList contains a mapping
for the specified string representation of a key.
|
boolean |
containsNode(String[] keyArr)
Returns true if this NavuList contains a mapping
for the specified string representation of a key.
|
NavuContainer |
create(ConfKey key)
Creates list element.
|
NavuContainer |
create(ConfObject key)
Creates list element.
|
NavuContainer |
create(String keyStr)
Creates list element.
|
NavuContainer |
create(String[] keyArr)
Creates list element.
|
void |
delete(ConfKey key)
Deletes an element from the list.
|
void |
delete(String keyStr)
Deletes an element from the list.
|
void |
delete(String[] keyArr)
Deletes an element from the list.
|
void |
deleteAll()
Deletes all element from the list.
|
NavuListEntry |
elem(ConfKey key)
Returns a list element according to the given key.
|
NavuContainer |
elem(String keyStr)
Returns a list element according to the given key.
|
NavuContainer |
elem(String[] keyArr)
Returns a list element according to the given array of keys.
|
Collection<NavuContainer> |
elements()
Returns a shallow copy of elements contained by the list node.
|
List<ConfXMLParam> |
encodeValues()
Encoding the sub-tree including the current
NavuNode
as the topmost NavuNode to a ConfXMLParam array. |
List<ConfXMLParam> |
encodeXML()
Encoding the sub-tree including the current
NavuNode
as the topmost NavuNode to a ConfXMLParam array. |
Set<Map.Entry<ConfKey,NavuListEntry>> |
entrySet()
Returns a set of entries with element key and element.
|
boolean |
equals(Object o)
Check the equality of this NavuNode against the targeted
NavuNode.
|
boolean |
exists()
Tests for the existence of the List node in the instance tree.
|
DiffIterateOperFlag |
getChangeFlag()
Returns the latest change that this
NavuNode has
been a subject to by a transaction. |
NavuNode |
getParent()
Returns the parent of the node.
|
ConfXMLParam[] |
getXml(String xml)
Read an arbitrary set of sub-elements of a container element.
|
int |
hashCode()
Return the hashCode of this NavuNode.
|
NavuContainer |
insert(ConfKey key,
boolean createBackpointer)
Inserts an element into a list using Maapi.insert().
|
boolean |
isEmpty()
Checks if there are any elements in the list.
|
boolean |
isNodeNavuLocal() |
Iterator<NavuListEntry> |
iterator()
Retrieve a iterator over the elements in this
NavuList
(in proper sequence). |
Set<ConfKey> |
keySet()
Returns a set of keys.
|
void |
move(ConfKey key,
NavuList.WhereTo whereTo,
ConfKey to)
Move a list element to a new position in the list.
|
void |
move(String keyStr,
NavuList.WhereTo whereTo,
String toStr)
Move a list element to a new position in the list.
|
PreparedXMLStatement |
prepareXMLCall(String xml)
A Prepared xml set() that accepts parameterized values "?"
instead of a string representation of the value
when on invocation the value is not known.
|
void |
reset()
When navigating through NAVU to a certain list.
|
NavuContainer |
safeCreate(ConfKey key)
The variant of
create that succeeds even if the
object already exists |
NavuContainer |
safeCreate(ConfObject key)
The variant of
create that succeeds even if the
object already exists. |
NavuContainer |
safeCreate(String keyStr)
The variant of
create that succeeds even if the
object already exists. |
NavuContainer |
safeCreate(String[] keyArr)
The variant of
create that succeeds even if the
object already exists. |
Collection<NavuNode> |
select(ConfObject[] kp) |
Collection<NavuNode> |
select(List<String> path) |
Collection<NavuNode> |
select(String path) |
void |
set(String xml)
Deprecated.
|
NavuNode |
setChange(List<ConfObject> path,
DiffIterateOperFlag op,
ConfValue oldValue,
NavuContext delContext) |
void |
setMaxListSize(int maxSize)
Sets the maxSize of the internal HashMap of list elements.
|
NavuContainer |
sharedCreate(ConfKey key)
The variant of
create that succeeds even if the
object already exists, and also maintains a reference counter
on the object. |
NavuContainer |
sharedCreate(ConfObject key)
The variant of
create that succeeds even if the
object already exists, and also maintains a reference counter
on the object. |
NavuContainer |
sharedCreate(String keyStr)
The variant of
create that succeeds even if the
object already exists, and also maintains a reference counter
on the object. |
NavuContainer |
sharedCreate(String[] keyArr)
The variant of
create that succeeds even if the
object already exists, and also maintains a reference counter
on the object. |
int |
size()
Returns the number of list elements contained by the list node.
|
String |
toString() |
void |
valueUpdateInd(NavuNode child) |
container, container, container, context, getCdbSession, getChange, getChanges, getChanges, getChanges, getConfPath, getInfo, getKeyPath, getName, getNavuNode, getRootNS, getValues, getValues, leaf, leaf, leaf, list, list, list, setValues, setValues, sharedSetValues, sharedSetValues, startCdbSession, stopCdbSession, xPathSelect, xPathSelectIteratepublic Collection<NavuNode> children() throws NavuException
children in class NavuNodeNavuException - if the elements could not be retrieved.public boolean containsNode(ConfKey key) throws NavuException
NavuList
contains a NavuListEntry where
NavuListEntry.getKey() equals the specified
key.key - whose presence in this NavuList is to be
testedNavuExceptionpublic boolean containsNode(NavuContainer node)
node - NavuContainer whose presence in this
NavuList is to be testedpublic boolean containsNode(String keyStr) throws NavuException
keyStr - a string representation of a key whose presence in this
NavuList is to be testedNavuExceptionpublic boolean containsNode(String[] keyArr) throws NavuException
This is a convenience method for lists with multiple element key.
keyArr - elements of the specified key contains string
representation of a key whose presence in this
NavuList is to be testedNavuExceptionpublic NavuContainer create(ConfKey key) throws NavuException
We have 3 different variants of create.
create() This method creates the list entry
in the transaction. It will fail with a NavuException with the
error code set to ErrorCode.ERR_ALREADY_EXISTS.
safeCreate() similar to create()
with the sole difference that is silently succeeds even if the
list entry already exists.
sharedCreate() This method is useful when
creating structures from FASTMAP code, i.e code that implements
the com.tailf.nsmux.NcsResourceFacingService interface.
Such code must never create structures that are shared between
multiple RFS service instances. The sharedCreate()
method maintains a reference counter on the created object.
All the create() methods are overlaid with
convenience method for lists with single element
key. If the string is enclosed in curly braces like {test},
the curly braces are stripped. If this not desired another
overlaid method should be used.
key - the key with which the newly created list entry is to be
associated.NavuException - if any MAAPI operations fail during the
create or IOException if socket errors would occur.public NavuContainer create(ConfObject key) throws NavuException
We have 3 different variants of create.
create() This method creates the list entry
in the transaction. It will fail with a NavuException with the
error code set to ErrorCode.ERR_ALREADY_EXISTS.
safeCreate() similar to create()
with the sole difference that is silently succeeds even if the
list entry already exists.
sharedCreate() This method is useful when
creating structures from FASTMAP code, i.e code that implements
the com.tailf.nsmux.NcsResourceFacingService interface.
Such code must never create structures that are shared between
multiple RFS service instances. The sharedCreate()
method maintains a reference counter on the created object.
Furthermore, and attribute "Backpointer" will be created on the created
container indicating which "service" created the object
All the create() methods are overlaid with
convenience method for lists with single element
key. If the string is enclosed in curly braces like {test},
the curly braces are stripped. If this not desired another
overlaid method should be used.
key - the key with which the newly created list entry is to be
associated.NavuException - if any MAAPI operations fail during the
create or IOException if socket errors would occur.public NavuContainer create(String keyStr) throws NavuException
We have 3 different variants of create.
create() This method creates the list entry
in the transaction. It will fail with a NavuException with the
error code set to ErrorCode.ERR_ALREADY_EXISTS.
safeCreate() similar to create()
with the sole difference that is silently succeeds even if the
list entry already exists.
sharedCreate() This method is useful when
creating structures from FASTMAP code, i.e code that implements
the com.tailf.nsmux.NcsResourceFacingService interface.
Such code must never create structures that are shared between
multiple RFS service instances. The sharedCreate()
method maintains a reference counter on the created object.
All the create() methods are overlaid with
convenience method for lists with single element
key. If the string is enclosed in curly braces like {test},
the curly braces are stripped. If this not desired another
overlaid method should be used.
keyStr - the key with which the newly created list entry is to be
associated.NavuException - if any MAAPI operations fail during the
create or IOException if socket errors would occur.public NavuContainer create(String[] keyArr) throws NavuException
Convenience method for multiple keys.
We have 3 different variants of create.
create() This method creates the list entry
in the transaction. It will fail with a NavuException with the
error code set to ErrorCode.ERR_ALREADY_EXISTS.
safeCreate() similar to create()
with the sole difference that is silently succeeds even if the
list entry already exists.
sharedCreate() This method is useful when
creating structures from FASTMAP code, i.e code that implements
the com.tailf.nsmux.NcsResourceFacingService interface.
Such code must never create structures that are shared between
multiple RFS service instances. The sharedCreate()
method maintains a reference counter on the created object.
All the create() methods are overlaid with
convenience method for lists with single element
key. If the string is enclosed in curly braces like {test},
the curly braces are stripped. If this not desired another
overlaid method should be used.
keyArr - the string array with which the newly created list
entry is to be associated.NavuException - if any MAAPI operations fail during the
create or IOException if socket errors would occur.public void delete(ConfKey key) throws NavuException
key - the key of the element to delete.NavuException - If the method fails to delete the element.public void delete(String keyStr) throws NavuException
This is a convenience method for lists with single element key. If the string is enclosed in curly braces like {test}, the curly braces are stripped. If this not desired another overlaid method should be used.
keyStr - string representation on single element keyNavuException - If the method fails to delete the element.public void delete(String[] keyArr) throws NavuException
keyArr - string representation on single element keyNavuException - If the method fails to delete the element.public void deleteAll()
throws NavuException
NavuException - if the method fails.public NavuListEntry elem(ConfKey key) throws NavuException
key - a key identifying the list element.NavuExceptionpublic NavuContainer elem(String keyStr) throws NavuException
This is a convenience method for lists with single element key. If the string is enclosed in curly braces like {test}, the curly braces are stripped. If this not desired another overlaid method should be used
keyStr - string representation on single element keyNavuExceptionpublic NavuContainer elem(String[] keyArr) throws NavuException
This is a convenience method for lists with multiple element key.
keyArr - string representation on single element keyNavuExceptionpublic Collection<NavuContainer> elements() throws NavuException
The elements contained by this list node is not cloned
NavuException - if the elements could not be retrieved.public List<ConfXMLParam> encodeValues() throws NavuException
NavuNodeNavuNode
as the topmost NavuNode to a ConfXMLParam array.
As opposed to encodeXML, the returning ConfXMLParam array
does contain values in form of ConfXMLParamValue
encodeValues in class NavuNodeConfXMLParam of the sub-tree
including valuesNavuException - If the operation could not be performed for some reasonsConfXMLParam,
ConfXMLParamValuepublic List<ConfXMLParam> encodeXML() throws NavuException
NavuNodeNavuNode
as the topmost NavuNode to a ConfXMLParam array.
The returning ConfXMLParam array contains no values except
for list keys. The leaf elements are encoded as ConfXMLParamLeaf
therefore the returning array could be used as a input parameter
to NavuNode.getValues(ConfXMLParam[]) on the current elements parent.
NavuNode node = ...; //cxa contains structure that does not contains values except for //keys in list elements ConfXMLParam[] cxa = node.encodeXML().toArray(new ConfXMLParam[0]); NavuNode parent = node.getParent(); //contains sub-tree with all the values ConfXMLParam[] cxb = parent.getValues(cxa);
encodeXML in class NavuNodeConfXMLParam of the sub-tree
(including key values) with key values.NavuException - If the operation could not be performed for some reasonsConfXMLParam,
ConfXMLParamValuepublic Set<Map.Entry<ConfKey,NavuListEntry>> entrySet() throws NavuException
NavuExceptionpublic boolean equals(Object o)
NavuNodepublic boolean exists()
throws NavuException
A list node can be contained inside a presence container.
If the container is not created the
exists will return false. Similary if a
list node is contained within a case in choice that is
not selected exists should return false.
exists in class NavuNodeNavuList
instance in the instance treeNavuException - on failurepublic DiffIterateOperFlag getChangeFlag()
NavuNodeNavuNode has
been a subject to by a transaction.getChangeFlag in class NavuNodeDiffIterateOperFlagpublic NavuNode getParent()
NavuNodepublic ConfXMLParam[] getXml(String xml) throws NavuException
The xml string must be pre-populated with tags and parameterized with values ("?") which indicates that the operation will read value of the corresponding tag.
NOTE: The specified xml string should not contain the version tag (<?xml version="1.0" encoding="UTF-8"?>)
Example - Get tree:
module mtest {
namespace "http://tail-f.com/test/mtest/1.0";
prefix mtest;
tailf:id "";
import ietf-yang-types {
prefix yang;
}
import ietf-inet-types {
prefix inet;
}
import tailf-common {
prefix tailf;
}
import tailf-xsd-types {
prefix xs;
}
container mtest {
container servers {
list server {
key name;
max-elements 64;
leaf name {
type string;
}
leaf ip {
type inet:host;
mandatory true;
}
leaf port {
type inet:port-number;
default 80;
}
list interface {
key name;
max-elements 8;
leaf name {
type string;
}
leaf mtu {
type int64;
default 1500;
}
}
}
}
}
}
mtest ns = new mtest();
NavuContainer mtestRoot = root.container(ns.hash());
NavuContainer mtest = mtestRoot.container(ns.mtest_mtest);
NavuContainer servers = mtest.container(ns.mtest_servers);
ConfXMLParam[] param = servers.getXml(
"<server>" +
"<name>www</name>" +
"<ip>?</ip> " +
"</server>" +
"<server>" +
"<name>x100</name>" +
"<ip>?</ip>" +
"</server>");
getXml in class NavuNodexml - -
XML structure corresponding values that will be fetched.ConfXMLParamNavuExceptionpublic int hashCode()
NavuNodepublic NavuContainer insert(ConfKey key, boolean createBackpointer) throws NavuException
NavuExceptionpublic boolean isEmpty()
throws NavuException
NavuExceptionpublic boolean isNodeNavuLocal()
public Iterator<NavuListEntry> iterator()
NavuList
(in proper sequence).iterator in interface Iterable<NavuListEntry>public Set<ConfKey> keySet() throws NavuException
NavuExceptionpublic void move(ConfKey key, NavuList.WhereTo whereTo, ConfKey to) throws NavuException
The destination
can be at the beginning, the end or in a relation to another element.
See: move(String keyStr, WhereTo whereTo, String toStr)
key - Move key according to whereTowhereTo - How the move should be performed. Move key
WhereTo.FIRST or WhereTo.LAST or move key
WhereTo.BEFORE or WhereTo.AFTER the element to.to - If the value of whereTo is WhereTo.FIRST or WhereTo.LAST
this argument ignoredNavuExceptionpublic void move(String keyStr, NavuList.WhereTo whereTo, String toStr) throws NavuException
The destination
can be at the beginning, the end or in a relation to another element.
Elements are referenced by their string representation.
See: move(ConfKey key, WhereTo whereTo, ConfKey to)
This is a convenience method for lists with single element
key. If the string is enclosed in curly braces like {test},
the curly braces are stripped. If this not desired another
overlaid method should be used
keyStr - Move keyStr according to whereTowhereTo - How the move should be performed. Move keyStr
WhereTo.FIRST or WhereTo.LAST or move keyStr
WhereTo.BEFORE or WhereTo.AFTER the element toStr.toStr - If the value of whereTo is WhereTo.FIRST or WhereTo.LAST
this argument ignoredNavuExceptionpublic PreparedXMLStatement prepareXMLCall(String xml) throws NavuException
When values that corresponds to "?" are known setXXX methods should be used.
PreparedXMLStatement xmlst =
serversNavuNode.prepareXMLCall(
"<server>" +
"<name>?</name>" +
"<ip>?</ip>" +
" <port>?</port>"+
"</server>");
xmlst.setBuf(0, "www1");
xmlst.setIPv4(1,new ConfIPv4("192.168.10.12"));
xmlst.setUInt16(2,new ConfUInt16(80));
xmlst.set();
If no setXXX method is called before a final set() then the "?"
is treated as ConfDefault.prepareXMLCall in class NavuNodexml - -
Parameterized xml string.NavuExceptionpublic void reset()
public NavuContainer safeCreate(ConfKey key) throws NavuException
create that succeeds even if the
object already existskey - the key with which the newly created list entry is to be
associated.NavuException - if any MAAPI operations fail during the
create or IOException if socket errors would occur.public NavuContainer safeCreate(ConfObject key) throws NavuException
create that succeeds even if the
object already exists.key - the key with which the newly created list entry is to be
associated.NavuException - if any MAAPI operations fail during the
create or IOException if socket errors would occur.public NavuContainer safeCreate(String keyStr) throws NavuException
create that succeeds even if the
object already exists.keyStr - the key string representation of a key value
with which the newly created list entry is to be
associated.NavuException - if any MAAPI operations fail during the
create or IOException if socket errors would occur.public NavuContainer safeCreate(String[] keyArr) throws NavuException
create that succeeds even if the
object already exists.
Convenience method for multiple keys.
keyArr - the key string representation of a key value
with which the newly created list entry is to be
associated.NavuException - if any MAAPI operations fail during the
create or IOException if socket errors would occur.public Collection<NavuNode> select(ConfObject[] kp) throws NavuException
select in class NavuNodeNavuExceptionpublic Collection<NavuNode> select(List<String> path) throws NavuException
select in class NavuNodepath - a list of regular expression.NavuExceptionpublic Collection<NavuNode> select(String path) throws NavuException
select in class NavuNodepath - a "/" separated regular expression.NavuException@Deprecated public void set(String xml) throws NavuException
NavuNode.setValues(String) method instead.xml - -
XML structure corresponding values that will be set.NavuExceptionpublic NavuNode setChange(List<ConfObject> path, DiffIterateOperFlag op, ConfValue oldValue, NavuContext delContext) throws NavuException
setChange in class NavuNodeNavuExceptionpublic void setMaxListSize(int maxSize)
maxSize - max size of the list (default 0 unlimited)public NavuContainer sharedCreate(ConfKey key) throws NavuException
create that succeeds even if the
object already exists, and also maintains a reference counter
on the object. When The FASTMAP algorithm applies to objects
created with sharedCreate the object is not
removed, but rather the reference counter is decremented.key - the key with which the newly created list entry is to be
associated.NavuException - if any MAAPI operations fail during the
create or IOException if socket errors would occur.public NavuContainer sharedCreate(ConfObject key) throws NavuException
create that succeeds even if the
object already exists, and also maintains a reference counter
on the object. When The FASTMAP algorithm applies to objects
created with sharedCreate the object is not
removed, but rather the reference counter is decremented.key - the key with which the newly created list entry is to be
associated.NavuException - if any MAAPI operations fail during the
create or IOException if socket errors would occur.public NavuContainer sharedCreate(String keyStr) throws NavuException
create that succeeds even if the
object already exists, and also maintains a reference counter
on the object. When The FASTMAP algorithm applies to objects
created with sharedCreate the object is not
removed, but rather the reference counter is decremented.keyStr - the string representation of the key value with which
the newly created list entry is to be
associated.NavuException - if any MAAPI operations fail during the
create or IOException if socket errors would occur.public NavuContainer sharedCreate(String[] keyArr) throws NavuException
create that succeeds even if the
object already exists, and also maintains a reference counter
on the object. When The FASTMAP algorithm applies to objects
created with sharedCreate the object is not
removed, but rather the reference counter is decremented.
Convenience method for multiple keys.
keyArr - the string array representation of the key value with which
the newly created list entry is to be associated.NavuException - if any MAAPI operations fail during the
create or IOException if socket errors would occur.public int size()
throws NavuException
NavuExceptionpublic void valueUpdateInd(NavuNode child) throws NavuException
valueUpdateInd in class NavuNodeNavuException