Package com.tailf.navu

Class NavuList

Object
com.tailf.navu.NavuNode
com.tailf.navu.NavuList
All Implemented Interfaces:
Iterable<NavuListEntry>
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, each associated with a key, ConfKey, thus each child is indexed by its key and the individual entry is retrieved by the elem(ConfKey) method.

The elem method declares that it returns a NavuContainer but its underlying subtype is actually a NavuListEntry.

NavuList also supports keyless lists (lists without keys). If the YANG list is keyless, an individual child is retrieved through its "pseudo-key" which must always be of the 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 through 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 the list elements, are retrieved through children(), elements() or by retrieving an iterator iterator(). 

  NavuList serverList = ...;

  for (NavuNode childEntry : serverList.children()) {
      // Do something with each child instance
  }
NavuList also implements the Iterable interface which means that the child elements can be retrieved implicitly. 
  NavuList serverList = ...;

  for (NavuNode childEntry : serverList) {
      // Do something with each child 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 its keys from the datastore. Use these methods with caution when the list is big.

Consider using the iterator instead wherever possible.

  • Method Details

    • containsNode

      public boolean containsNode(ConfKey key) throws NavuException
      Returns true if and only if this NavuList contains a NavuListEntry where NavuListEntry.getKey() equals the specified key.
      Parameters:
      key - whose presence in this NavuList is to be tested
      Returns:
      true if this NavuList contains a entry with the specified key
      Throws:
      NavuException

    • containsNode

      public boolean containsNode(NavuContainer node)
      Returns true if this NavuList maps a ConfKey to the specified NavuContainer. specified value. More formally, returns true if and only if this NavuList contains a mapping to a NavuContainer n such that (node==null ? n==null : node.equals(n)).
      Parameters:
      node - NavuContainer whose presence in this NavuList is to be tested
      Returns:
      true if this NavuList maps a keys to the specified node

    • containsNode

      public boolean containsNode(String keyStr) throws NavuException
      Returns true if this NavuList contains a mapping for the specified string representation of a key.
      Parameters:
      keyStr - a string representation of a key whose presence in this NavuList is to be tested
      Returns:
      true if this NavuList maps a keys to the specified node
      Throws:
      NavuException

    • containsNode

      public boolean containsNode(String[] keyArr) throws NavuException
      Returns true if this NavuList contains a mapping for the specified string representation of a key.

      This is a convenience method for lists with multiple element key.

      Parameters:
      keyArr - elements of the specified key contains string representation of a key whose presence in this NavuList is to be tested
      Returns:
      true if this NavuList maps a the specified keys in the array
      Throws:
      NavuException

    • create

      public NavuContainer create(ConfKey key) throws NavuException
      Create and return a new list element in this NavuList.

      We have 3 different variants of create.

      1. create() This method will fail with a NavuException with the error code set to ErrorCode.ERR_ALREADY_EXISTS if the key already exists.

      2. safeCreate() Similar to create() with the sole difference that is silently succeeds even if the key already exists.

      3. sharedCreate() This method is useful when creating structures from FASTMAP code, i.e., code that implements the com.tailf.nsmux.NcsResourceFacingService interface. The sharedCreate() method maintains a reference counter on the created object. Furthermore, a backpointer attribute will be created on the created object indicating which service(s) created the object.

      All of the create() methods are overloaded with convenience methods accepting keys of different types.

      Parameters:
      key - the key with which the newly created list entry is to be associated
      Returns:
      the created list entry
      Throws:
      NavuException

    • create

      public NavuContainer create(ConfObject key) throws NavuException
      Convenience variant of create(ConfKey) accepting a ConfObject as the (single element) key.
      Parameters:
      key - the key with which the newly created list entry is to be associated
      Returns:
      the created list entry
      Throws:
      NavuException

    • create

      public NavuContainer create(String keyStr) throws NavuException

      Convenience variant of create(ConfKey) accepting a string as the (single element) key.

      If the string is surrounded by curly braces, e.g. "{test}", they will be removed. If this is not desired, another variant of create() should be used.

      The YANG type of the list key does not necessarily have to be a string. The key string will be encoded as the proper YANG type according to the schema.

      Parameters:
      keyStr - the key with which the newly created list entry is to be associated
      Returns:
      the created list entry
      Throws:
      NavuException

    • create

      public NavuContainer create(String[] keyArr) throws NavuException
      Convenience variant of create(ConfKey) accepting a string array as the key. Typically useful for multiple element keys.
      Parameters:
      keyArr - the string array from which to create the key that the newly created list entry is to be associated with
      Returns:
      the created list entry
      Throws:
      NavuException

    • safeCreate

      public NavuContainer safeCreate(ConfKey key) throws NavuException
      Variant of create(ConfKey) that succeeds even if the key already exists.
      Parameters:
      key - the key with which the newly created list entry is to be associated
      Returns:
      the created list entry or, if it already exists, the list entry corresponding to the given key, key
      Throws:
      NavuException

    • safeCreate

      public NavuContainer safeCreate(ConfObject key) throws NavuException
      Variant of create(ConfObject) that succeeds even if the key already exists.
      Parameters:
      key - the key with which the newly created list entry is to be associated
      Returns:
      the created list entry or, if it already exists, the list entry corresponding to the given key, key
      Throws:
      NavuException

    • safeCreate

      public NavuContainer safeCreate(String keyStr) throws NavuException
      Variant of create(String) that succeeds even if the key already exists.
      Parameters:
      keyStr - the string representation of the key value with which the newly created list entry is to be associated
      Returns:
      the created list entry or, if it already exists, the list entry corresponding to the given key, key
      Throws:
      NavuException

    • safeCreate

      public NavuContainer safeCreate(String[] keyArr) throws NavuException
      Variant of create(String[]) that succeeds even if the key already exists.
      Parameters:
      keyArr - the string array from which to create the key that the newly created list entry is to be associated with
      Returns:
      the created list entry or, if it already exists, the list entry corresponding to the given key, keyArr
      Throws:
      NavuException

    • sharedCreate

      public NavuContainer sharedCreate(ConfKey key) throws NavuException
      Variant of create(ConfKey) that succeeds even if the key already exists, and also maintains a reference counter on the object.
      Parameters:
      key - the key with which the newly created list entry is to be associated
      Returns:
      the created list entry or, if it already exists, the list entry corresponding to the given key, key
      Throws:
      NavuException

    • sharedCreate

      public NavuContainer sharedCreate(ConfObject key) throws NavuException
      Variant of create(ConfObject) that succeeds even if the key already exists, and also maintains a reference counter on the object.
      Parameters:
      key - the key with which the newly created list entry is to be associated
      Returns:
      the created list entry or, if it already exists, the list entry corresponding to the given key, key
      Throws:
      NavuException

    • sharedCreate

      public NavuContainer sharedCreate(String keyStr) throws NavuException
      Variant of create(String) that succeeds even if the key already exists, and also maintains a reference counter on the object.
      Parameters:
      keyStr - the string representation of the key value with which the newly created list entry is to be associated
      Returns:
      the created list entry or, if it already exists, the list entry corresponding to the given key, key
      Throws:
      NavuException

    • sharedCreate

      public NavuContainer sharedCreate(String[] keyArr) throws NavuException
      Variant of create(String[]) that succeeds even if the key already exists, and also maintains a reference counter on the object.
      Parameters:
      keyArr - the string array from which to create the key that the newly created list entry is to be associated with
      Returns:
      the created list entry or, if it already exists, the list entry corresponding to the given key, keyArr
      Throws:
      NavuException

    • delete

      public void delete(ConfKey key) throws NavuException
      Deletes an element from the list.
      Parameters:
      key - the key of the element to delete
      Throws:
      NavuException

    • deleteAll

      public void deleteAll() throws NavuException
      Deletes all element from the list.
      Throws:
      NavuException

    • delete

      public void delete(String keyStr) throws NavuException
      Deletes an element from the list.

      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 overloaded method should be used.

      Parameters:
      keyStr - string representation of a single element key
      Throws:
      NavuException

    • delete

      public void delete(String[] keyArr) throws NavuException
      Deletes an element from the list. This is a convenience method for lists with multiple element keys.
      Parameters:
      keyArr - string array representation of a multiple element key
      Throws:
      NavuException

    • insert

      public NavuContainer insert(ConfKey key, boolean createBackpointer) throws NavuException
      Inserts an element into a list using Maapi.insert(). This is only applicable for lists that have the annotation tailf:indexed-view An interesting special case is when a list has also the annotation tailf:auto-compact. The createBackpointer variable should then be set to true. When we insert an entry into an auto compact list, the createBackpointer makes NCS follow all backpointers in the list and update the corresponding diffsets so that FastMap continues to work. The Key must be an integer key. In NCS this construct is sometimes used in NEDs, modelling devices that have lists that 'auto compact' sometimes ACLs can be like that, if we remove an entry in the middle, the following entries are moved up. It is only allowed to create new entries at the end of lists that are auto-compact. The first entry of the list has key one (1).
      Throws:
      NavuException

    • elem

      public NavuListEntry elem(ConfKey key) throws NavuException
      Returns a list element according to the given key.
      Parameters:
      key - a key identifying the list element
      Returns:
      a matching element, or null if no matching element is found
      Throws:
      NavuException

    • elem

      public NavuContainer elem(String keyStr) throws NavuException
      Returns a list element according to the given key.

      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 overloaded method should be used.

      Parameters:
      keyStr - string representation on single element key
      Returns:
      a matching list element or null, if no matching element is found.
      Throws:
      NavuException

    • elem

      public NavuContainer elem(String[] keyArr) throws NavuException
      Returns a list element according to the given array of keys.

      This is a convenience method for lists with multiple element keys.

      Parameters:
      keyArr - string array representation of a multiple element key
      Returns:
      a matching list element, or null if no matching element is found
      Throws:
      NavuException

    • elements

      public Collection<NavuContainer> elements() throws NavuException
      Returns a shallow copy of all elements contained by the list node.

      The elements contained by this list node are not cloned

      Returns:
      a copy of the collection of list elements
      Throws:
      NavuException

    • children

      public Collection<NavuNode> children() throws NavuException
      Returns all elements contained by the list node.
      Overrides:
      children in class NavuNode
      Returns:
      a collection of list elements
      Throws:
      NavuException - if the elements could not be retrieved

    • encodeXML

      public List<ConfXMLParam> encodeXML() throws NavuException
      Description copied from class: NavuNode
      Encodes the sub-tree including the current NavuNode as the topmost NavuNode as a ConfXMLParam array.

      The returned ConfXMLParam array contains no values except for list keys. The leaf elements are encoded as ConfXMLParamLeaf. Therefore, the returning array can be used as a the input parameter to NavuNode.getValues(ConfXMLParam[]) on the current node's parent. 

       NavuNode node = ...;
 ConfXMLParam[] cxa = node.encodeXML().toArray(new ConfXMLParam[0]);
 // cxa contains a structure that does not contain values except for
 // keys in list elements

 NavuNode parent = node.getParent();
 ConfXMLParam[] cxb = parent.getValues(cxa);
 // cxb contains the same sub-tree with all the values
      Specified by:
      encodeXML in class NavuNode
      Returns:
      A list of ConfXMLParam objects corresponding to the sub-tree of this node, with no values except list keys.
      Throws:
      NavuException
      See Also:

    • encodeValues

      public List<ConfXMLParam> encodeValues() throws NavuException
      Description copied from class: NavuNode
      Encodes the sub-tree including the current NavuNode as the topmost NavuNode as a ConfXMLParam array.

      As opposed to NavuNode.encodeXML(), the returned ConfXMLParam array does contain values in the form of ConfXMLParamValue

      Specified by:
      encodeValues in class NavuNode
      Returns:
      A list of ConfXMLParam objects corresponding to the sub-tree of this node, including all values.
      Throws:
      NavuException
      See Also:

    • entrySet

      public Set<Map.Entry<ConfKey,NavuListEntry>> entrySet() throws NavuException
      Returns a set of entries with element key and element.
      Returns:
      a set of entries
      Throws:
      NavuException

    • isEmpty

      public boolean isEmpty() throws NavuException
      Checks if there are any elements in the list.
      Returns:
      true if there are no list entries, false otherwise,
      Throws:
      NavuException

    • keySet

      public Set<ConfKey> keySet() throws NavuException
      Returns a Set containing all of the keys for this list.
      Returns:
      the full set of keys for this list
      Throws:
      NavuException

    • reset

      public void reset()
      When navigating through NAVU to a certain list, the list values are cached as they are read. This method clears this cache and and indicates to Navu that the list elements should be re-read as they are retrieved.
      Specified by:
      reset in class NavuNode

    • select

      public Collection<NavuNode> select(List<String> path) throws NavuException
      Specified by:
      select in class NavuNode
      Parameters:
      path - a list of regular expression.
      Returns:
      a collection a nodes marching the query
      Throws:
      NavuException

    • select

      public Collection<NavuNode> select(String path) throws NavuException
      Specified by:
      select in class NavuNode
      Parameters:
      path - a "/" separated regular expression.
      Returns:
      a collection a nodes marching the query
      Throws:
      NavuException

    • size

      public int size() throws NavuException
      Returns the number of list elements contained by the list node.
      Returns:
      the number of elements in this list
      Throws:
      NavuException

    • setMaxListSize

      public void setMaxListSize(int maxSize)
      Sets the maxSize of the internal HashMap of list elements. If the maxSize is reached new elements will imply that the oldest element is silently removed. If set to 0 the list is unlimited. Note, this function should NOT be used if the implications are unknown or not understood.
      Parameters:
      maxSize - max size of the list (default 0 unlimited)

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • valueUpdateInd

      public void valueUpdateInd(NavuNode child) throws NavuException
      Throws:
      NavuException

    • setChange

      public NavuNode setChange(List<ConfObject> path, DiffIterateOperFlag op, ConfValue oldValue, NavuContext delContext) throws NavuException
      Throws:
      NavuException

    • getChangeFlag

      public DiffIterateOperFlag getChangeFlag()
      Returns the latest change that this NavuNode has been a subject to by a transaction.
      Overrides:
      getChangeFlag in class NavuNode
      Returns:
      Flag for the latest change
      See Also:

    • getParent

      public NavuNode getParent()
      Description copied from class: NavuNode
      Returns the parent of the node.
      Overrides:
      getParent in class NavuNode
      Returns:
      - this node parent or null if this NavuNode represents the root node.

    • select

      public Collection<NavuNode> select(ConfObject[] kp) throws NavuException
      Specified by:
      select in class NavuNode
      Returns:
      a collection a nodes matching a Regular Expression query
      Throws:
      NavuException

    • isNodeNavuLocal

      public boolean isNodeNavuLocal()

    • set

      @Deprecated public void set(String xml) throws NavuException
      Deprecated.
      This method is deprecated use the NavuNode.setValues(String) method instead.
      Parameters:
      xml - XML structure corresponding values that will be set
      Throws:
      NavuException

    • move

      public void move(String keyStr, NavuList.WhereTo whereTo, String toStr) throws NavuException
      Move a list element to a new position in the list.

      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

      Parameters:
      keyStr - Move keyStr according to whereTo
      whereTo - 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 ignored
      Throws:
      NavuException

    • move

      public void move(ConfKey key, NavuList.WhereTo whereTo, ConfKey to) throws NavuException
      Move a list element to a new position in the list.

      The destination can be at the beginning, the end or in a relation to another element. See: move(String keyStr, WhereTo whereTo, String toStr)

      Parameters:
      key - Move key according to whereTo
      whereTo - 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 ignored
      Throws:
      NavuException

    • iterator

      public Iterator<NavuListEntry> iterator()
      Retrieve a iterator over the elements in this NavuList (in proper sequence).
      Specified by:
      iterator in interface Iterable<NavuListEntry>

    • exists

      public boolean exists() throws NavuException
      Tests for the existence of the List node in the instance tree.

      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.

      Specified by:
      exists in class NavuNode
      Returns:
      true/false on existence of this NavuList instance in the instance tree
      Throws:
      NavuException - on failure

    • equals

      public boolean equals(Object o)
      Compares the specified object with this NavuList for equality. Returns true if the given object is also a NavuList and it has the same ConfPath as this NavuList.
      Specified by:
      equals in class NavuNode
      Parameters:
      o - the object to be compared for equality with this NavuList
      Returns:
      true if the specified object is equal to this NavuList