NavuContainer (CONF API Version 6.4)

Object
- com.tailf.navu.NavuNode
- - com.tailf.navu.NavuContainer

All Implemented Interfaces:

ConfIterate, MaapiDiffIterate

Direct Known Subclasses:

NavuListEntry
```
public class NavuContainer
extends NavuNode
implements MaapiDiffIterate
```
NavuContainer is a representation of the yang construct container,module and list-entry.
A NavuContainer is usually supplied or returned from a method call. It could also be created through its constructor that takes a NavuContext as its parameter. NavuContainer(NavuContext). NavuContainer is created with NavuContext initialized with a Maapi socket:
```
    NavuContext context = new NavuContext(maapi);
    context.startRunningTrans(Conf.MODE_READ_WRITE);
    NavuContainer root = new NavuContainer(context);
 
```
From the above snippet it follows that a transaction need to be started before navigating using the context.
A Transaction can alternatively be started for operational data instead. NavuContainer could also be created with a
```
    NavuContext context = new NavuContext(maapi);
    context.startOperationalTrans(Conf.MODE_READ_WRITE);
    NavuContainer root = new NavuContainer(context);
 
```
In either way when a NavuContainer is created using the above mentioned context it represents, the object pointed by root is the "root" of the NAVU-Tree.
The "root"s children represents all the loaded modules. To choose a particular module the container(Integer) should be called which returns a new NavuContainer pointed to the top of the "chosen" module. The parameter is the hash value of the corresponding module ConfNamespace.hash().
```
     NavuContainer module = root.container(new Ncs().hash());
 
```
To continue further down to the next child use container(Integer), container(String), list(Integer),container(String) or leaf(Integer), leaf(String) depending on the type of yang construct. The string version is the corresponding MaapiSchemas.hashToString(long) of the Integer parameter which is the hash value of the tag name.
Usually the generated namespace classes static method is used for convenience. The absence of underscore (_) at the end of the static method indicates the integer version.
Then continuing with a devices node:
```
     NavuContainer devicesNode = schema.container(Ncs._devices);
```

Constructor Summary

Constructors
Constructor and Description
`NavuContainer()` This constructor creates a root container.
`NavuContainer(Cdb cdb, int hash)` Deprecated.
`NavuContainer(Maapi m, int handle, int rootHash)` Constructor for a single namespace.
`NavuContainer(Maapi readWrite, int readWriteTid, Maapi readOnly, int readOnlyTid, int rootHash)` Deprecated.
`NavuContainer(NavuContext context)` Creates an root `NavuContainer` a starting point of which further navigation is performed.

Method Summary

Methods
Modifier and Type	Method and Description
`NavuAction`	`action(Integer key)` Returns a subordinate reference to action according to the given hash value `key`.
`NavuAction`	`action(String key)` Returns a subordinate reference to action according to the given string `key`.
`Collection<NavuNode>`	`children()` Returns a collection of child nodes contained by the container.
`NavuChoice`	`choice(String name)`
`NavuContainer`	`container(Integer key)` Returns a subordinate reference to a container according to the given hash value.
`NavuContainer`	`container(String key)` Returns a subordinate reference to container according to the given string `key`.
`NavuContainer`	`container(String prefix, String key)` Returns a subordinate reference to container according to the given `key` and `prefix`.
`boolean`	`containsNode(NavuNode node)` Checks if the given node is contained in the schema in this container.
`boolean`	`containsNode(String nodeName)` Checks if there is a child node in the schema with given name.
`NavuContainer`	`create()` Creates an optional container.
`NavuContainer`	`delete()` Deletes an optional container.
`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<String,NavuNode>>`	`entrySet()` Returns a set of value-pairs.
`boolean`	`equals(Object o)` Compares the specified object with this `NavuContainer` for equality.
`boolean`	`exists()` Verifies the existence of container.
`Map<ConfKey,NavuChange>`	`findChanges(Integer[] criteria)` Analyzes what changes has been done within this transaction.
`NavuNode`	`get(String nodeName)` Returns a subordinate node with the name `nodeName`.
`ConfKey`	`getKey()` If this container is a list instance this method can be used to get the list entry key.
`ConfNamespace`	`getRootNS()` Returns the root namespace of the topmost ancestor.
`List<NavuChoice>`	`getSelectCaseAsNavuChoice(String choice)` Returns a collection of the "toplevel" choice elements of the a current selected case.
`List<NavuNode>`	`getSelectCaseAsNavuNode(String choice)` Returns a collection of the "toplevel" node elements of the a current selected case.
`MaapiSchemas.CSCase`	`getSelectedCase(String choice)` Returns the selected cases of a given choice.
`int`	`getUserSession()` Get the current Maapi user session if this container context uses Maapi.
`int`	`hashCode()` Returns the hash code value for this `NavuContainer`.
`boolean`	`isEmpty()` Checks if the container has any members.
`boolean`	`isListInstance()` Returns `true` if this `NavuContainer` represents a list-entry
`DiffIterateResultFlag`	`iterate(ConfObject[] kp, DiffIterateOperFlag op, ConfObject oldValue, ConfObject newValue, Object state)`
`Set<String>`	`keySet()` Returns a set of nodeNames.
`NavuLeaf`	`leaf(Integer key)` Returns a subordinate reference to a leaf node according to the given hash value `key`.
`NavuLeaf`	`leaf(String key)` Returns a subordinate reference to a leaf node according to the given string `key`.
`NavuLeaf`	`leaf(String prefix, String key)` Returns a subordinate reference to leaf according to the given `key` and `prefix`.
`NavuList`	`list(Integer key)` Returns a subordinate reference to list according to the given hash value `key`.
`NavuList`	`list(String key)` Returns a subordinate reference to list according to the given string `key`.
`NavuList`	`list(String prefix, String key)` Returns a subordinate reference to list according to the given `key` and `prefix`.
`void`	`reset()` Resets the contained nodes
`NavuContainer`	`safeCreate()` Creates an optional container.
`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)`
`NavuContainer`	`setOperationalDataCase(String choiceStr, String caseStr)` Deprecated. Use the method `setOperDataCase(String , String)`
`void`	`setOperDataCase(String choiceStr, String caseStr)` Set a case with the name `caseStr` for a choice `choiceStr` for Cdb when writing operational data.
`NavuContainer`	`sharedCreate()` Creates an optional container.
`int`	`size()` Returns the number of nodes contained by the container.
`String`	`toString()`
`void`	`valueUpdateInd(NavuNode child)` An indication received from a child node.

Methods inherited from class com.tailf.navu.NavuNode
context, getCdbSession, getChange, getChangeFlag, getChanges, getChanges, getChanges, getConfPath, getInfo, getKeyPath, getName, getNavuNode, getParent, getValues, getValues, getXml, prepareXMLCall, setValues, setValues, sharedSetValues, sharedSetValues, startCdbSession, stopCdbSession, xPathSelect, xPathSelectIterate

Methods inherited from class Object
getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - NavuContainer
```
public NavuContainer()
```
    This constructor creates a root container. This container holds all loaded schemas as its children.
  - NavuContainer
```
@Deprecated
public NavuContainer(Cdb cdb,
                        int hash)
```
    Deprecated.
    
    Constructor for a NavuContainer that will be able to connect to the Cdb database to retrieve config and operational data.
    
    Parameters:
    cdb - The CDB instance to use for read/write operations
    hash - Namespace hash integer value representation of the module
  - NavuContainer
```
public NavuContainer(Maapi m,
             int handle,
             int rootHash)
```
    Constructor for a single namespace. Bypasses the root node.
    
    Parameters:
    m - READ or READ_WRITE MAAPI socket
    handle - a valid transaction handle
    rootHash - the root hash of the module
  - NavuContainer
```
@Deprecated
public NavuContainer(Maapi readWrite,
                        int readWriteTid,
                        Maapi readOnly,
                        int readOnlyTid,
                        int rootHash)
```
    Deprecated.
    
    This constructor is deprecated. The readOnly Maapi and readOnly transaction is not used and therefore obsolete. This constructor shall be used if you want the container to be aware of the changes that have been applied within this transaction.
    
    Parameters:
    readWrite - MAAPI socket to perform changes on
    readWriteTid - READ/WRITE transaction handle to use for READ/WRITE operations
    readOnly - MAAPI socket to the RUNNING datastore
    readOnlyTid - READ transaction handle to use when reading
    rootHash - root hash of the module
  - NavuContainer
```
public NavuContainer(NavuContext context)
```
    Creates an root NavuContainer a starting point of which further navigation is performed.
    
    Parameters:
    context - determines the Navigation restriction and constraints
- Method Detail
  - action
```
public NavuAction action(Integer key)
                  throws NavuException
```
    Returns a subordinate reference to action according to the given hash value key.
    
    Parameters:
    key - the name of the subordinate action
    
    Returns:
    reference to a subordinate action node
    
    Throws:
    
    NavuException - if the corresponding subordinate node is not a action node or if subordinate node has no matching action with the hash value key
  - action
```
public NavuAction action(String key)
                  throws NavuException
```
    Returns a subordinate reference to action according to the given string key.
    
    Parameters:
    key - the name of the subordinate action
    
    Returns:
    reference to a subordinate action node
    
    Throws:
    
    NavuException - if the corresponding subordinate node is not a action node or if subordinate node has no matching action with the string key
  - children
```
public Collection<NavuNode> children()
                              throws NavuException
```
    Returns a collection of child nodes contained by the container.
    
    Overrides:
    
    children in class NavuNode
    
    Returns:
    child nodes of this container.
    
    Throws:
    
    NavuException
  - choice
```
public NavuChoice choice(String name)
                  throws NavuException
```
    Parameters:
    name - - the name of the choice to return.
    
    Returns:
    a matching choice.
    
    Throws:
    
    NavuException
  - container
```
public NavuContainer container(Integer key)
                        throws NavuException
```
    Returns a subordinate reference to a container according to the given hash value. The container hashvalue could be obtained through ConfNamespace.stringToHash(String), MaapiSchemas.stringToHash(String) or use the overloaded method container(String)
    
    Overrides:
    
    container in class NavuNode
    
    Parameters:
    key - hashed value of the container to return
    
    Returns:
    subordinate reference to a container
    
    Throws:
    
    NavuException - if the corresponding subordinate node is not a container or if subordinate node has no matching container with the hash value key
  - container
```
public NavuContainer container(String key)
                        throws NavuException
```
    Returns a subordinate reference to container according to the given string key.
    
    Overrides:
    
    container in class NavuNode
    
    Parameters:
    key - the name of the subordinate container
    
    Returns:
    reference to a subordinate container node
    
    Throws:
    
    NavuException - if the corresponding subordinate node is not a container node or if subordinate node has no matching container with the name key
  - container
```
public NavuContainer container(String prefix,
                      String key)
                        throws NavuException
```
    Returns a subordinate reference to container according to the given key and prefix.
    
    Overrides:
    
    container in class NavuNode
    
    Parameters:
    prefix - the prefix for the namespace
    key - the name of the subordinate container
    
    Returns:
    reference to a subordinate container node
    
    Throws:
    
    NavuException - if the corresponding subordinate node is not a container node or if subordinate node has no matching container with the name key and prefix
  - containsNode
```
public boolean containsNode(NavuNode node)
                     throws NavuException
```
    Checks if the given node is contained in the schema in this container.
    
    Parameters:
    node -
    
    Returns:
    true if is contained.
    
    Throws:
    
    NavuException
  - containsNode
```
public boolean containsNode(String nodeName)
                     throws NavuException
```
    Checks if there is a child node in the schema with given name.
    
    Parameters:
    nodeName - the name of a node to look for.
    
    Returns:
    true there is a match.
    
    Throws:
    
    NavuException
  - create
```
public NavuContainer create()
                     throws NavuException
```
    Creates an optional container.
    
    Returns:
    a pointer to self.
    
    Throws:
    
    NavuException
  - delete
```
public NavuContainer delete()
                     throws NavuException
```
    Deletes an optional container.
    
    Returns:
    a pointer to self.
    
    Throws:
    
    NavuException
  - encodeValues
```
public List<ConfXMLParam> encodeValues()
                                throws NavuException
```
    Description copied from class: NavuNode
    
    Encoding the sub-tree including the current NavuNode as the topmost NavuNode to a ConfXMLParam array.
    As opposed to encodeXML, the returning ConfXMLParam array does contain values in form of ConfXMLParamValue
    
    Specified by:
    
    encodeValues in class NavuNode
    
    Returns:
    A list of ConfXMLParam of the sub-tree including values
    
    Throws:
    
    NavuException - If the operation could not be performed for some reasons
    See Also:
    ConfXMLParam, ConfXMLParamValue
  - encodeXML
```
public List<ConfXMLParam> encodeXML()
                             throws NavuException
```
    Description copied from class: NavuNode
    Encoding the sub-tree including the current NavuNode 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);
    Specified by:
    
    encodeXML in class NavuNode
    
    Returns:
    An array of ConfXMLParam of the sub-tree (including key values) with key values.
    
    Throws:
    
    NavuException - If the operation could not be performed for some reasons
    See Also:
    ConfXMLParam, ConfXMLParamValue
  - entrySet
```
public Set<Map.Entry<String,NavuNode>> entrySet()
                                         throws NavuException
```
    Returns a set of value-pairs.
    
    Returns:
    a set of nodeName-node pairs according to the schema
    
    Throws:
    
    NavuException
  - equals
```
public boolean equals(Object o)
```
    Compares the specified object with this NavuContainer for equality. Returns true if and only if the specified object is also a NavuContainer and returns true/false depending on the following: NavuNodeInfo.isModule(): check the equality of getInfo().getCSSchema().equals to ((NavuContainer)o).getInfo().getCSSchema() NavuNodeInfo.isChildNode(): check the equality of getInfo().getCSNode().equals to ((NavuContainer)o).getInfo().getCSNode()
    Specified by: equals in class NavuNode Parameters: o - the object to be compared for equality with this list Returns: true if the specified object is equal to this list
  exists public boolean exists() throws NavuException Verifies the existence of container. Specified by: exists in class NavuNode Returns: boolean Throws: NavuException findChanges public Map<ConfKey,NavuChange> findChanges(Integer[] criteria) throws NavuException Analyzes what changes has been done within this transaction. The prerequisites are: This is the container of a module. That this container has been created using two MAAPI sockets. Parameters: criteria - a list hash values representing a search path. The first element is the module name hash. The analysis will be started at the end of the list. List elements are represented by 0. Returns: a map between key and NavuChange Throws: IOException ConfException NavuException get public NavuNode get(String nodeName) throws NavuException Returns a subordinate node with the name nodeName. Parameters: nodeName - a name of a node contained within this container. Returns: a matching node Throws: NavuException - if subordinate node has no matching container with the name nodeName getKey public ConfKey getKey() If this container is a list instance this method can be used to get the list entry key. Otherwise this method returns null. Returns: the key as a ConfKey object getRootNS public ConfNamespace getRootNS() Description copied from class: NavuNode Returns the root namespace of the topmost ancestor. Overrides: getRootNS in class NavuNode Returns: topmost namespace. getSelectCaseAsNavuChoice public List<NavuChoice> getSelectCaseAsNavuChoice(String choice) throws NavuException Returns a collection of the "toplevel" choice elements of the a current selected case. Returns null if no case is selected for the specified choice or if the selected case contains no choices. Parameters: choice - the choice name to get selected case for Returns: toplevel NavuChoices's for the selected case or null if no selected case is selected. Throws: NavuException - if this container does not contains the choice with the specified name choice getSelectCaseAsNavuNode public List<NavuNode> getSelectCaseAsNavuNode(String choice) throws NavuException Returns a collection of the "toplevel" node elements of the a current selected case. Returns null if no case is selected for the specified choice or if the selected case contains no nodes. Which of the subclasses NavuContainer, NavuList or NavuLeaf that actually constitutes this case is defined by the model or has to be tested. Parameters: choice - the choice name to get selected case for Returns: toplevel NavuNode's for the selected case or null if no selected case is selected. Throws: NavuException - if this container does not contains the choice with the specified name choice getSelectedCase public MaapiSchemas.CSCase getSelectedCase(String choice) throws NavuException Returns the selected cases of a given choice. Parameters: choice - of the choice to get selected case for. Returns: - the selected case Throws: NavuException getUserSession public int getUserSession() throws NavuException Get the current Maapi user session if this container context uses Maapi. Throws exception if the context is not Maapi. Returns: user session id Throws: NavuException hashCode public int hashCode() Returns the hash code value for this NavuContainer. This implementation uses exactly the code that is used to define the hash code for a String. Specified by: hashCode in class NavuNode Returns: the hash code value for this NavuContainer isEmpty public boolean isEmpty() throws NavuException Checks if the container has any members. Returns: true if it has 1 or more members. Throws: NavuException isListInstance public boolean isListInstance() Returns true if this NavuContainer represents a list-entry Returns: true if this NavuContainer is a list-entry false otherwise iterate public DiffIterateResultFlag iterate(ConfObject[] kp, DiffIterateOperFlag op, ConfObject oldValue, ConfObject newValue, Object state) Specified by: iterate in interface MaapiDiffIterate keySet public Set<String> keySet() throws NavuException Returns a set of nodeNames. Returns: a set of nodeNames Throws: NavuException leaf public NavuLeaf leaf(Integer key) throws NavuException Returns a subordinate reference to a leaf node according to the given hash value key. Overrides: leaf in class NavuNode Parameters: key - hashed value of the subordinate leaf Returns: reference to a subordinate container node Throws: NavuException - if the corresponding subordinate node is not a leaf node or if subordinate node has no matching leaf with the hash value key leaf public NavuLeaf leaf(String key) throws NavuException Returns a subordinate reference to a leaf node according to the given string key. Overrides: leaf in class NavuNode Parameters: key - the name of the subordinate leaf Returns: reference to a subordinate leaf node Throws: NavuException - if the corresponding subordinate node is not a leaf node or if subordinate node has no matching leaf with the name key leaf public NavuLeaf leaf(String prefix, String key) throws NavuException Returns a subordinate reference to leaf according to the given key and prefix. Overrides: leaf in class NavuNode Parameters: prefix - the prefix for the namespace key - the name of the subordinate leaf Returns: reference to a subordinate leaf node Throws: NavuException - if the corresponding subordinate node is not a leaf node or if subordinate node has no matching leaf with the name key and prefix list public NavuList list(Integer key) throws NavuException Returns a subordinate reference to list according to the given hash value key. Overrides: list in class NavuNode Parameters: key - the name of the subordinate list Returns: reference to a subordinate list node Throws: NavuException - if the corresponding subordinate node is not a list node or if subordinate node has no matching list with the hash value key list public NavuList list(String key) throws NavuException Returns a subordinate reference to list according to the given string key. Overrides: list in class NavuNode Parameters: key - the name of the subordinate list Returns: reference to a subordinate list node Throws: NavuException - if the corresponding subordinate node is not a list node or if subordinate node has no matching list with the name key list public NavuList list(String prefix, String key) throws NavuException Returns a subordinate reference to list according to the given key and prefix. Overrides: list in class NavuNode Parameters: prefix - the prefix for the namespace key - the name of the subordinate list Returns: reference to a subordinate list node Throws: NavuException - if the corresponding subordinate node is not a list node or if subordinate node has no matching list with the name key and prefix reset public void reset() Resets the contained nodes Specified by: reset in class NavuNode safeCreate public NavuContainer safeCreate() throws NavuException Creates an optional container. Will silently ignore the error when the container already exists Returns: a pointer to self. Throws: NavuException 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 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 set @Deprecated public void set(String xml) throws NavuException Deprecated. This method is deprecated. Use NavuNode.setValues(String) instead. Parameters: xml - - XML structure corresponding values that will be set. Throws: NavuException setChange public NavuNode setChange(List<ConfObject> path, DiffIterateOperFlag op, ConfValue oldValue, NavuContext delContext) throws NavuException Specified by: setChange in class NavuNode Throws: NavuException setOperationalDataCase @Deprecated public NavuContainer setOperationalDataCase(String choiceStr, String caseStr) throws NavuException Deprecated. Use the method setOperDataCase(String , String) There is a difference in how cases for a choice is set in a Maapi context and a Cdb context. In Maapi, when writing configuration data, the cases are set implicitly as any leaf are set below a choice in the model tree. For Cdb, when writing operational data, this case has to be set explicitly. This is done using this method. The method returns a NavuContainer representing the selected case which can be used to navigate down the model tree. Parameters: choiceStr - name of the choice caseStr - name of the case to set as selected case Returns: NavuContainer representing the selected case Throws: NavuException setOperDataCase public void setOperDataCase(String choiceStr, String caseStr) throws NavuException Set a case with the name caseStr for a choice choiceStr for Cdb when writing operational data. There is a difference in how cases for a choice is set in a Maapi context and a Cdb context. In Maapi, when writing configuration data, the cases are set implicitly as any leaf are set below a choice in the model tree. For Cdb, when writing operational data, this case has to be set explicitly. This is done using this method. The method returns a NavuContainer representing the selected case which can be used to navigate down the model tree. Parameters: choiceStr - name of the choice caseStr - name of the case to set as selected case Throws: NavuException - If the caseStr could not be set sharedCreate public NavuContainer sharedCreate() throws NavuException Creates an optional container. Will silently ignore the error when the container is not a presence container. It will also maintain a counter (as an attribute) counting how many times the same containers has been created. This makes this method very useful for NCS fastmap users where sometimes we wish to create services where multiple service instances share the seam structure. Furthermore, and attribute "Backpointer" will be created on the created container indicating which "service" created the object Returns: a pointer to self. Throws: NavuException size public int size() throws NavuException Returns the number of nodes contained by the container. Returns: the number contained nodes. Throws: NavuException toString public String toString() Overrides: toString in class Object valueUpdateInd public void valueUpdateInd(NavuNode child) throws NavuException An indication received from a child node. The update indicates that a leaf node has been read/set or list node has been read/created for the first time. The main purpose of this indication is to trigger updates of choice related nodes. Specified by: valueUpdateInd in class NavuNode Parameters: child - the child node doing the update. Throws: NavuException

Class NavuContainer

Constructor Summary

Method Summary

Methods inherited from class com.tailf.navu.NavuNode

Methods inherited from class Object

Constructor Detail

NavuContainer

NavuContainer

NavuContainer

NavuContainer

NavuContainer

Method Detail

action

action

children

choice

container

container

container

containsNode

containsNode

create

delete

encodeValues

encodeXML

entrySet

equals

exists

findChanges

get

getKey

getRootNS

getSelectCaseAsNavuChoice

getSelectCaseAsNavuNode

getSelectedCase

getUserSession

hashCode

isEmpty

isListInstance

iterate

keySet

leaf

leaf

leaf

list

list

list

reset

safeCreate

select

select

select

set

setChange

setOperationalDataCase

setOperDataCase

sharedCreate

size

toString

valueUpdateInd