com.tailf.navu

Class NavuNode

Object

com.tailf.navu.NavuNode

Direct Known Subclasses:

NavuAction, NavuContainer, NavuLeaf, NavuList

public abstract class NavuNode
extends Object

NavuNode is the base class for all navigation classes like NavuContainer, NavuList, NavuLeaf etc.

A NavuNode can be explicitly retrieved through NavuNode.getNavuNode(ConfPath).

 //attach to MAAPI context
 NavuContainer root = new NavuContainer(new NavuContext(maapi, th));
 NavuNode node =
     root.getNavuNode(new ConfPath("/ncs:devices/device{device0}/config"));
 

a subclass of NanvuNode represents a YANG constructs that is either a containment element, (i.e., container, list), a leaf that holds a value, or tailf:action which represents an action in the data model.

The interface specifies the minimum requirement that a NavuNode should implement. To extend the functionality of the NavuNode an explicit cast must be performed.

 NavuNode node = ...;
 if(node.getInfo().isAction()) {
     NavuAction theAction = (NavuAction)node;
     theAction.call();
 }

 // or
 if(node instanceof NavuAction) {
     NavuAction theAction = (NavuAction)node;
     theAction.call();
 }
 

The methods in this interface can be divided into four different categories.

• Navigational methods. Basic navigational methods NavuNode.container(String), NavuNode.leaf(String), NavuNode.list(String) each retrieves a NavuNode on the next level.

  NavuNode.getParent() retrieves the NavuNode for the previous level (parent node). To retrieve all the child elements on the next level for a given NavuNode, NavuNode.children() returns a Collection of NavuNodes.

  To retrieve descendants of a NavuNode based on a regular expression, NavuNode.select(String) (or an overloaded variant) can be used.

• Informational methods. Provide information for a NavuNode. NavuNode.getInfo(), NavuNode.getKeyPath(), NavuNode.getName(), NavuNode.getRootNS().
• Context specific methods. Certain methods are only useful depending on the currently attached context. The current context is retrieved through context() method. Note that CDB context is deprecated.

   if (node.context().isMaapi())
       // node is in MAAPI context
   else if(node.context().isCdbSession())
       // CDB context (deprecated)
   

  Some MAAPI-specific methods are NavuNode.getChangeFlag(), NavuNode.getChanges() and NavuNode.xPathSelect(String).
• Data reading/writing methods. Methods such as NavuNode.getValues(String) and NavuNode.setValues(String).

There are also methods that does not fall into the above categories, such as NavuNode.encodeXML() which is a helpful method in conjunction with getValues() to extract a sub-tree.

Constructor Summary

Constructors

Constructor and Description
NavuNode()

Method Summary

Modifier and Type	Method and Description
Collection<NavuNode>	children() Returns a collection containing the children of this node.
NavuContainer	container(ConfNamespace ns, String containerName) Returns a reference to a subordinate container with the name containerName, belonging to the namespace ns.
NavuContainer	container(Integer key) Returns a reference to a subordinate container with the hash value key.
NavuContainer	container(String key) Returns a reference to a subordinate container with the name key.
NavuContainer	container(String prefix, String key) Deprecated.
NavuContext	context() Returns the current NavuContext that this node is attached to.
abstract List<ConfXMLParam>	encodeValues() Encodes the sub-tree including the current NavuNode as the topmost NavuNode as a ConfXMLParam array.
abstract List<ConfXMLParam>	encodeXML() Encodes the sub-tree including the current NavuNode as the topmost NavuNode as a ConfXMLParam array.
abstract boolean	equals(Object o) Check the equality of this NavuNode against the targeted NavuNode.
abstract boolean	exists() Generic exists test for Navu navigational elements
CdbSession	getCdbSession(CdbDBType dbType) Deprecated.
DiffIterateOperFlag	getChange() Deprecated.
DiffIterateOperFlag	getChangeFlag() Returns the latest change that this NavuNode has been a subject to by a transaction.
List<NavuNode>	getChanges() Deprecated.
List<NavuNode>	getChanges(boolean emitSubTree) Deprecated.
List<NavuNode>	getChanges(boolean emitSubTree, DiffIterateOperFlag... forOps) Deprecated.
List<NavuNode>	getChanges(NavuContext delContext) Return the descendant NavuNode's (including this element) that has been affected by changes to the MAAPI transaction.
List<NavuNode>	getChanges(NavuContext delContext, boolean emitSubTree) Return the descendant NavuNode including this NavuNode that has been affected by the current MAAPI transaction.
List<NavuNode>	getChanges(NavuContext delContext, boolean emitSubTree, DiffIterateOperFlag... forOps) Return the descendant NavuNode including this NavuNode that has been affected by the current MAAPI transaction.
ConfPath	getConfPath() Returns the corresponding ConfPath for the corresponding NavuNode.
NavuNodeInfo	getInfo() Returns the NaveNodeInfo regarding this node.
String	getKeyPath() Returns the absolute keypath of this node.
String	getName() Returns the name of this NavuNode.
NavuNode	getNavuNode(ConfPath path) Retrieve a NavuNode based on the given absolute or relative path.
NavuNode	getParent() Returns the parent of the node.
ConfNamespace	getRootNS() Returns the root namespace of the topmost ancestor.
ConfXMLParam[]	getValues(ConfXMLParam[] params) Read an arbitrary set of sub-elements from this NavuNode.
ConfXMLParam[]	getValues(String xml) Read an arbitrary set of sub-elements of a container or list entry.
ConfXMLParam[]	getXml(String xml) Deprecated.
int	hashCode() Return the hashCode of this NavuNode.
NavuLeaf	leaf(ConfNamespace ns, String leafName) Returns a reference to a subordinate leaf with the name leafName, belonging to the namespace ns.
NavuLeaf	leaf(Integer key) Returns a reference to a subordinate leaf with the hash value key.
NavuLeaf	leaf(String key) Returns a reference to a subordinate leaf with the name key.
NavuLeaf	leaf(String prefix, String key) Deprecated.
NavuLeafList	leafList(ConfNamespace ns, String leafListName) Returns a reference to a subordinate leaf-list with the name leafListName, belonging to the namespace ns.
NavuLeafList	leafList(Integer key) Returns a reference to a subordinate leaf-list with the hash value key.
NavuLeafList	leafList(String key) Returns a reference to a subordinate leaf-list with the name key.
NavuLeafList	leafList(String prefix, String key) Deprecated.
NavuList	list(ConfNamespace ns, String listName) Returns a reference to a subordinate list with the name listName, belonging to the namespace ns.
NavuList	list(Integer key) Returns a reference to a subordinate list with the hash value key.
NavuList	list(String key) Returns a reference to a subordinate list with the name key.
NavuList	list(String prefix, String key) Deprecated.
NavuContainer	namespace(String ns) The namespace specified here will be used when selecting a child to this NavuContainer and returns a reference to this NavuContainer object according to the given namespace id ns.
PreparedXMLStatement	prepareXMLCall(String xml) Creates a parameterized configuration xml in the style of a NavuNode.setValues(String) argument.
abstract void	reset() When navigating through NAVU to a certain location.
abstract Collection<NavuNode>	select(ConfObject[] query)
abstract Collection<NavuNode>	select(List<String> query)
abstract Collection<NavuNode>	select(String query)
void	setValues(ConfXMLParam[] params) Set arbitrary sub-elements of a container or list entry.
void	setValues(String xml) Set arbitrary sub-elements of a container or list entry.
void	sharedSetValues(ConfXMLParam[] params) Set arbitrary sub-elements of a container or list entry with FastMap support, creating backpointers and reference counter.
void	sharedSetValues(String xml) Set arbitrary sub-elements of a container or list entry with FastMap support, creating backpointers and reference counter.
void	startCdbSession(CdbDBType dbtype, EnumSet<CdbLockType> lockflags) Deprecated.
void	stopCdbSession() Closes all CdbSessions for the NavuContainer.
List<NavuNode>	xPathSelect(String query) Evaluates the XPath path expression query and returns the resulting node set as list of NavuNode's.
void	xPathSelectIterate(String query, NavuNodeSetIterate iterate) Iterate through a NodeSet based on a supplied XPath query.

Methods inherited from class Object

getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NavuNode

public NavuNode()

Method Detail

context

public NavuContext context()

Returns the current NavuContext that this node is attached to.

Returns:

The current NavuContext.

getNavuNode

public NavuNode getNavuNode(ConfPath path)
                     throws NavuException

Retrieve a NavuNode based on the given absolute or relative path.

If the path is relative it is relative this NavuNode .

Returns:

NavuNode pointed by path if it is absolute or if relative the NavuNode pointed by path relative this NavuNode

Throws:

NavuException - if the path is invalid according the schema or does not lead to a instance node.

getInfo

public NavuNodeInfo getInfo()

Returns the NaveNodeInfo regarding this node.

A NavuNodeInfo is an object which further information could be retrieved from the current node.

Returns:

A informational instance about this NavuNode

getRootNS

public ConfNamespace getRootNS()

Returns the root namespace of the topmost ancestor.

Returns:

topmost namespace.

getConfPath

public ConfPath getConfPath()

Returns the corresponding ConfPath for the corresponding NavuNode. If the NavuNode is the root schema NavuNode i.e the root NavuContainer constructed from the schema hash, this node has no corresponding ConfPath and null is returned.

Returns:

ConfPath

getKeyPath

public String getKeyPath()

Returns the absolute keypath of this node.

Returns:

A String representing the absolute keypath that this NavuNode

Throws:

NavuException - If the keypath could not be determine

getName

public String getName()

Returns the name of this NavuNode.

Returns:

- the node name.

getParent

public NavuNode getParent()

Returns the parent of the node.

Returns:

- this node parent or null if this NavuNode represents the root node.

children

public Collection<NavuNode> children()
                              throws NavuException

Returns a collection containing the children of this node. For container nodes, the returned collection can contain nodes of any type. For list nodes, the children are the elements of the list. Leaf nodes have no children and will return an empty collection.

Returns:

the children of this node

Throws:

NavuException

getValues

public ConfXMLParam[] getValues(ConfXMLParam[] params)
                         throws NavuException

Read an arbitrary set of sub-elements from this NavuNode.

Input array of ConfXMLParam where desired values to be extracted should be replaced with ConfXMLParamLeaf in the ConfXMLParam array.

The return value is a copy of the input ConfXMLParam where instances of ConfXMLParamLeaf have been replaced with ConfXMLParamValue.

Parameters:

params - pre-populated array of ConfXMLParam

Returns:

Array of ConfXMLParam where ConfXMLParamLeaf is replaced with ConfXMLParamValue

Throws:

NavuException - If the input parameter does not conform to the current data model or an error occurs during the read.

getValues

public ConfXMLParam[] getValues(String xml)
                         throws NavuException

Read an arbitrary set of sub-elements of a container or list entry.

The xml string must be pre-populated with tags and parameterized values ("?") which indicate that the operation should read the values of the corresponding tags.

NOTE: The specified xml string should not contain the version tag (<?xml version="1.0" encoding="UTF-8"?>) and do not wrap xml string with current node tag.

Example - Get tree in a service model:

 list buzz-service {
   key name;
   leaf name {
     type string;
   }
   uses ncs:service-data;
   ncs:servicepoint buzz-service-servicepoint;
   container buzz {
     container servers {
       list server {
         key "srv-name";
         max-elements "64";
         leaf srv-name {
           type string;
         }
         leaf ip {
           type inet:host;
           mandatory true;
         }
         leaf port {
           type inet:port-number;
           default "80";
         }
         container foo {
           leaf bar {
             type int64;
             default "42";
           }
           leaf baz {
             type int64;
             default "7";
           }
         }
         list interface {
           key "if-name";
           max-elements "8";
           leaf if-name {
             type string;
           }
           leaf mtu {
             type int64;
             default "1500";
           }
         }
       }
     }
   }
 }

 NavuContainer buzz =
     ncsRoot.container(buzzService.hash)
            .list(buzzService._buzz_service)
            .elem("service1")
            .container(buzzService._buzz);

 ConfXMLParam[] param =
     buzz.getValues("<buzz xmlns=\"http://com/example/buzzservice\">"
                    + "<servers><server><srv-name>www1</srv-name>"
                    + "<ip>?</ip></server><server>"
                    + "<srv-name>www2</srv-name><ip>?</ip>"
                    + "</server></servers></buzz>");

 

Parameters:

xml - XML structure corresponding to the part of the configuration tree that is to be fetched.

Throws:

NavuException

getXml

@Deprecated
public ConfXMLParam[] getXml(String xml)
                                  throws NavuException

Deprecated.

Same functionality as {link NavuNode.getValues(String) which should be used instead.

Parameters:

xml - Array which specifies what data should be retrieved

Returns:

Resulting data as array of ConfXMLParam

Throws:

NavuException - If the input parameters does not confirm to the current data model or external error have occurred

setValues

public void setValues(String xml)
               throws NavuException

Set arbitrary sub-elements of a container or list entry.

This method shares the same behavior as NavuNode.setValues(ConfXMLParam[]) but the input parameter is an XML string.

The XML string passed as the input parameter should reflect the equivalent ConfXMLParam array structure.

Example ConfXMLParam array:

 
 ConfXMLParam[] p = new ConfXMLParam[12];
 final int hash = new Ncs().hash();
 p[0] = new ConfXMLParamStart(hash, Ncs._config);
 final int hash2 = new Foo().hash();
 p[1] = new ConfXMLParamStart(hash2, Foo._interface);
 p[2] = new ConfXMLParamStart(hash2, Foo._buzz);
 p[3] = new ConfXMLParamStart(hash2, Foo._servers);
 p[4] = new ConfXMLParamStart(hash2, Foo._server);
 p[5] = new ConfXMLParamValue(hash2, Foo._srv_name, new ConfBuf("www"));
 p[6] = new ConfXMLParamValue(hash2, Foo._port, new ConfUInt16(80));
 p[7] = new ConfXMLParamStop(hash2, Foo._server);
 p[8] = new ConfXMLParamStop(hash2, Foo._servers);
 p[9] = new ConfXMLParamStop(hash2, Foo._buzz);
 p[10] = new ConfXMLParamStop(hash2, Foo._interface);
 p[11] = new ConfXMLParamStop(hash, Ncs._config);
 

And its XML string representation:

 
 <ncs:config xmlns:ncs="http://tail-f.com/ns/ncs">
   <foo:interface xmlns:foo="http://acme.com/foo">
     <foo:buzz>
       <foo:servers>
         <foo:server>
           <foo:srv-name>www</foo:srv-name>
           <foo:port>80</foo:port>
         </foo:server>
       </foo:servers>
     </foo:buzz>
   </foo:interface>
 </ncs:config>
 

The specified XML string should not contain the "version" tag (<?xml version="1.0" encoding="UTF-8"?>), the method will append it.

The values that are to be set must be legal string representations according to their respective types. The value strings will be validated against the current the schema and the operation will fail if the string representations are incorrect.

Example - Populate tree in a service model:

 list buzz-service {
   key name;
   leaf name {
     type string;
   }
   uses ncs:service-data;
   ncs:servicepoint buzz-service-servicepoint;
   container buzz {
     container servers {
       list server {
         key "srv-name";
         max-elements "64";
         leaf srv-name {
           type string;
         }
         leaf ip {
           type inet:host;
           mandatory true;
         }
         leaf port {
           type inet:port-number;
           default "80";
         }
         container foo {
           leaf bar {
             type int64;
             default "42";
           }
           leaf baz {
             type int64;
             default "7";
           }
         }
         list interface {
           key "if-name";
           max-elements "8";
           leaf if-name {
             type string;
           }
           leaf mtu {
             type int64;
             default "1500";
           }
         }
       }
     }
   }
 }

 NavuContainer buzz =
     ncsRoot.container(buzzService.hash)
            .list(buzzService._buzz_service)
            .create("service1")
            .container(buzzService._buzz);


 buzz.setValues("<servers><server><srv-name>www1</srv-name>"
                + "<ip>192.178.0.1</ip>"
                + "<port>80</port>"
                + "<foo><bar>55</bar>"
                + "<baz>44</baz></foo>"
                + "<interface><if-name>eth0</if-name>"
                + "<mtu>1500</mtu></interface>"
                + "<interface><if-name>eth1</if-name>"
                + "<mtu>1600</mtu></interface></server>"
                + "<server><srv-name>www2</srv-name>"
                + "<ip>192.178.0.2</ip>"
                + "<port>8080</port>"
                + "<foo><bar>66</bar>"
                + "<baz>55</baz></foo>"
                + "<interface><if-name>eth0</if-name>"
                + "<mtu>1500</mtu></interface>"
                + "<interface><if-name>eth1</if-name>"
                + "<mtu>1600</mtu>"
                + "</interface></server></servers>");

 

For operational data with lists without keys, list instances cannot be created without passing a pseudo-key. This pseudo-key is used to identify which item in the list to set or update. The pseudo-key has to be specified in the supplied xml-string and is identified by the "<tailf-navu-pseudo-key>1</tailf-navu-pseudo-key>" tag. Internally the pseudo-key value is represented as a ConfInt64 type.

Parameters:

xml - XML structure corresponding values that will be set.

Throws:

NavuException

See Also:

NavuNode.setValues(ConfXMLParam[]), ConfXMLParam

setValues

public void setValues(ConfXMLParam[] params)
               throws NavuException

Set arbitrary sub-elements of a container or list entry.

The ConfXMLParam array must be populated with values according to the specification of the ConfXMLParam array structure.

If the container or list entry itself, or any sub-elements that are specified as existing, do not exist before this call, they will be created, otherwise the existing values will be updated.

Both mandatory and optional elements may be omitted from the array, and all omitted elements are left unchanged.

To actually delete a non-mandatory leaf or presence container, ConfNoExists should be used in the corresponding ConfXMLParamValue.

For a list entry, the key values can be specified either in the path or via key elements in ConfXMLParamValue - if the values are in the path, the key elements can be omitted from the array. For sub-lists present in the array, the key elements must of course always also be present though, immediately following the ConfXMLParamStart element and in the order defined by the data model.

For a list without keys the "pseudo" key may (or in some cases must) be present in the array, but of course there is no tag value for it, since it isn't present in the data model. In this case we must use a tag value of 0, i.e., it can be set with code like:

 ConfXMLParam[] p = new ConfXMLParam[7];

 p[1] = new ConfXMLParam(hash, 0, new ConfInt64(42));
 

Parameters:

params - ConfXMLParam array containing configuration to be set.

Throws:

IOException

ConfException

NavuException

sharedSetValues

public void sharedSetValues(String xml)
                     throws NavuException

Set arbitrary sub-elements of a container or list entry with FastMap support, creating backpointers and reference counter. All FastMap code shall (in principle) always use this method instead of setValues().

This method shares the same behavior as NavuNode.sharedSetValues(ConfXMLParam[]) but the input parameter is an XML string.

Throws:

NavuException

sharedSetValues

public void sharedSetValues(ConfXMLParam[] params)
                     throws NavuException

Set arbitrary sub-elements of a container or list entry with FastMap support, creating backpointers and reference counter. All FastMap code shall (in principle) always use this method instead of setValues().

Throws:

NavuException

prepareXMLCall

public PreparedXMLStatement prepareXMLCall(String xml)
                                    throws NavuException

Creates a parameterized configuration xml in the style of a NavuNode.setValues(String) argument. The string "?" denotes a parameterized value.

When the values that correspond to ? are known, they can be set using PreparedXMLStatement.put(int, String) or PreparedXMLStatement.put(int, ConfObject).

Once all parameters have been set, the entire xml can be written using PreparedXMLStatement.setValues().

Any parameterized value that is not populated by put before setValues is called, is treated as a ConfDefault.

 
 PreparedXMLStatement xmlst =
     node.prepareXMLCall("<server><srv-name>?</srv-name>"
                         + "<ip>?</ip>"
                         + "<port>?</port>"
                         + "</server>");

 xmlst.put(0, new ConfBuf("www1"));
 xmlst.put(1, new ConfIPv4(new int[] { 192, 168, 10, 12 });
 xmlst.put(2, new ConfUInt16(80));
 xmlst.setValues();
 
 

Parameters:

xml - Parameterized xml string.

Throws:

NavuException

See Also:

PreparedXMLStatement

xPathSelect

public List<NavuNode> xPathSelect(String query)
                           throws NavuException

Evaluates the XPath path expression query and returns the resulting node set as list of NavuNode's.

The expression query will be evaluated using this node as the context node.

Example:

 NavuContainer =
 root.container(myns._somecontainer1)
     .container(myns._somecontainer2).container(myns._servers);

 // Retrieve all the entries of the server list "server"
 servers.xPathSelect("server");

 // Retrieve all child nodes of servers with srv-name = www1
 servers.xPathSelect("server[srv-name='www1']/*");

 // Retrieve all leaf ip nodes of servers with srv-name = www1
 servers.xPathSelect("server[srv-name='www1']/ip");
 

Parameters:

query - XPath 1.0 query

Returns:

a collection a nodes marching the query

Throws:

NavuException

xPathSelectIterate

public void xPathSelectIterate(String query,
                               NavuNodeSetIterate iterate)
                        throws NavuException

Iterate through a NodeSet based on a supplied XPath query. Instead of retrieving a list of nodes as with NavuNode.xPathSelect(String) in this method a supplied callback is called for each node in the result set. See NavuNodeSetIterate.

Parameters:

query - XPath 1.0 query

iterate - supplied user code

Throws:

NavuException

namespace

public NavuContainer namespace(String ns)
                        throws ConfException,
                               IOException

The namespace specified here will be used when selecting a child to this NavuContainer and returns a reference to this NavuContainer object according to the given namespace id ns.

Parameters:

ns - the namespace id

Returns:

reference to this NavuContainer object

Throws:

ConfException

IOException

container

public NavuContainer container(Integer key)
                        throws NavuException

Returns a reference to a subordinate container with the hash value key. The container hash value can be obtained as a constant from a namespace file generated by confdc or ncsc, or retrieved with one of the methods ConfNamespace.stringToHash(String) or MaapiSchemas.stringToHash(String). It is also possible to access a container based on its name only, using the overloaded method NavuNode.container(String).

Parameters:

key - hashed name of the container to return

Returns:

reference to a subordinate container node

Throws:

NavuException - if the corresponding subordinate node is not a container or if there is no subordinate node with the hash value key

container

public NavuContainer container(String key)
                        throws NavuException

Returns a reference to a subordinate container with the name key.

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 there is no subordinate node with the name key

container

public NavuContainer container(ConfNamespace ns,
                               String containerName)
                        throws NavuException

Returns a reference to a subordinate container with the name containerName, belonging to the namespace ns.

Note that if containerName by itself uniquely identifies a subordinate container, that container will still have to belong to the namespace ns contrary to the functionality of the previous method using prefix and containerName.

Parameters:

ns - the namespace object

containerName - 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 there is no subordinate node with the name containerName in the namespace ns

container

@Deprecated
public NavuContainer container(String prefix,
                                           String key)
                                    throws NavuException

Deprecated.

Use NavuNode.container(ConfNamespace, String) or #namespace(String).container(String) instead.

Throws:

NavuException

leaf

public NavuLeaf leaf(Integer key)
              throws NavuException

Returns a reference to a subordinate leaf with the hash value key.

Parameters:

key - hashed name 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 there is no subordinate node with the hash value key

leaf

public NavuLeaf leaf(String key)
              throws NavuException

Returns a reference to a subordinate leaf with the name key.

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 there is no subordinate node with the name key

leaf

public NavuLeaf leaf(ConfNamespace ns,
                     String leafName)
              throws NavuException

Returns a reference to a subordinate leaf with the name leafName, belonging to the namespace ns.

Note that if leafName by itself uniquely identifies a subordinate leaf, that leaf will still have to belong to the namespace ns contrary to the functionality of the previous method using prefix and leafName.

Parameters:

ns - the namespace object

leafName - 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 there is no subordinate node with the name leafName in the namespace ns

leaf

@Deprecated
public NavuLeaf leaf(String prefix,
                                 String key)
                          throws NavuException

Deprecated.

Use NavuNode.leaf(ConfNamespace, String) or #namespace(String).leaf(String) instead.

Throws:

NavuException

leafList

public NavuLeafList leafList(Integer key)
                      throws NavuException

Returns a reference to a subordinate leaf-list with the hash value key.

Parameters:

key - hashed name of the subordinate leaf-list

Returns:

reference to a subordinate leaf-list node

Throws:

NavuException - if the corresponding subordinate node is not a leaf-list node or if there is no subordinate node with the hash value key

leafList

public NavuLeafList leafList(String key)
                      throws NavuException

Returns a reference to a subordinate leaf-list with the name key.

Parameters:

key - the name of the subordinate leaf-list

Returns:

reference to a subordinate leaf-list node

Throws:

NavuException - if the corresponding subordinate node is not a leaf-list node or if there is no subordinate node with the name key

leafList

public NavuLeafList leafList(ConfNamespace ns,
                             String leafListName)
                      throws NavuException

Returns a reference to a subordinate leaf-list with the name leafListName, belonging to the namespace ns.

Note that if leafListName by itself uniquely identifies a subordinate leaf-list, that leaf-list will still have to belong to the namespace ns contrary to the functionality of the previous method using prefix and leafListName.

Parameters:

ns - the namespace object

leafListName - the name of the subordinate leaf-list

Returns:

reference to a subordinate leaf-list node

Throws:

NavuException - if the corresponding subordinate node is not a leaf-list node or if there is no subordinate node with the name leafListName and ns

leafList

@Deprecated
public NavuLeafList leafList(String prefix,
                                         String key)
                                  throws NavuException

Deprecated.

Use NavuNode.leafList(ConfNamespace, String) or #namespace(String).leafList(String) instead.

Throws:

NavuException

list

public NavuList list(Integer key)
              throws NavuException

Returns a reference to a subordinate list with the hash value key.

Parameters:

key - the hashed 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 there is no subordinate node with the hash value key

list

public NavuList list(String key)
              throws NavuException

Returns a reference to a subordinate list with the name key.

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 there is no subordinate node with the name key

list

public NavuList list(ConfNamespace ns,
                     String listName)
              throws NavuException

Returns a reference to a subordinate list with the name listName, belonging to the namespace ns.

Note that if listName by itself uniquely identifies a subordinate list, that list will still have to belong to the namespace ns contrary to the functionality of the previous method using prefix and listName.

Parameters:

ns - the namespace object

listName - 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 there is no subordinate node with the name listName in the namespace ns

list

@Deprecated
public NavuList list(String prefix,
                                 String key)
                          throws NavuException

Deprecated.

Use NavuNode.list(ConfNamespace, String) or #namespace(String).list(String) instead.

Throws:

NavuException

getChange

@Deprecated
public DiffIterateOperFlag getChange()

Deprecated.

This method is deprecated, use NavuNode.getChangeFlag() instead.

getChangeFlag

public DiffIterateOperFlag getChangeFlag()

Returns the latest change that this NavuNode has been a subject to by a transaction.

Returns:

Flag for the latest change

See Also:

DiffIterateOperFlag

getChanges

public List<NavuNode> getChanges(NavuContext delContext)
                          throws NavuException

Return the descendant NavuNode's (including this element) that has been affected by changes to the MAAPI transaction. Since deletes are already removed in current transactions a delete context is necessary to retrieve information about delete changes.

The delContext is a NavuContext with a read transaction on the running database to read deletes. If null delete changes will not be able to be retrieved.

The default behavior is to emit the affected descendant and include all the affected NavuNode's regardless of type of change.

To filter out specific type of change use the methods NavuNode.getChanges(boolean, DiffIterateOperFlag...)

Parameters:

delContext - NavuContext to retrieve deleted values with.

Returns:

A list of NavuNode's that has been affected by the changes to the current MAAPI transaction.

Throws:

NavuException - Is returned if we try to iterate on a transaction which is in the wrong state and not attached.

getChanges

public List<NavuNode> getChanges(NavuContext delContext,
                                 boolean emitSubTree)
                          throws NavuException

Return the descendant NavuNode including this NavuNode that has been affected by the current MAAPI transaction. Since deletes are already removed in current transactions a delete context is necessary to retrieve information about delete changes.

The delContext is a NavuContext with a read transaction on the running database to read deletes. If null delete changes will not be able to be retrieved.

The emitSubtree flag specified if the desired sub-tree should be included in the return set. If set to true then the behavior is to include the whole sub-tree of affected NavuNode's.

If set to false the sibling changes to the current transaction is to only included.

Parameters:

delContext - NavuContext to retrieve deleted values with.

emitSubTree - boolean to control subtree changes

Returns:

A list of NavuNode that has been affected by changes to the current MAAPI transaction.

Throws:

NavuException - Is returned if we try to iterate on changes on a transaction which is in the wrong state and not attached.

getChanges

public List<NavuNode> getChanges(NavuContext delContext,
                                 boolean emitSubTree,
                                 DiffIterateOperFlag... forOps)
                          throws NavuException

Return the descendant NavuNode including this NavuNode that has been affected by the current MAAPI transaction. Since deletes are already removed in current transactions a delete context is necessary to retrieve information about delete changes.

The delContext is a NavuContext with a read transaction on the running database to read deletes. If null delete changes will not be able to be retrieved.

The emitSubtree flag specified if the desired sub-tree should be included in the return set. If set to true then the behavior is to include the whole sub-tree of affected NavuNode's.

If set to false the sibling NavuNode that has been affected by changes to the current transaction is to be included.

The forOps argument specifies those specific changes that the NavuNode previously NavuNode's to be included filter out the set that does not match the specified arguments.

Parameters:

delContext - NavuContext to retrieve deleted values with.

emitSubTree - boolean to control subtree changes

forOps - operations for which changes are of interest.

Returns:

A list of NavuNode that has been affected by changes to the current MAAPI transaction.

Throws:

NavuException - Is returned if we try to iterate on a transaction which is in the wrong state and not attached.

getChanges

@Deprecated
public List<NavuNode> getChanges()
                                      throws NavuException

Deprecated.

Since this method cannot return delete changes in a reliable way this method is deprecated. Use instead NavuNode.getChanges(NavuContext)

Throws:

NavuException

getChanges

@Deprecated
public List<NavuNode> getChanges(boolean emitSubTree)
                                      throws NavuException

Deprecated.

Since this method cannot return delete changes in a reliable way this method is deprecated. Use instead NavuNode.getChanges(NavuContext, boolean)

Throws:

NavuException

getChanges

@Deprecated
public List<NavuNode> getChanges(boolean emitSubTree,
                                             DiffIterateOperFlag... forOps)
                                      throws NavuException

Deprecated.

Since this method cannot return delete changes in a reliable way this method is deprecated. Use instead NavuNode.getChanges(NavuContext, boolean, DiffIterateOperFlag...)

Throws:

NavuException

getCdbSession

@Deprecated
public CdbSession getCdbSession(CdbDBType dbType)

Deprecated.

This method is deprecated. Use one of NavuContextBase.getReadConfSession(), NavuContextBase.getReadConfSession() or NavuContextBase.getWriteOperSession() instead. Returns the current CdbSession.

Returns:

The current CdbSession or null if this node is attached to a Maapi context

startCdbSession

@Deprecated
public void startCdbSession(CdbDBType dbtype,
                                        EnumSet<CdbLockType> lockflags)

Deprecated.

This method is deprecated This method is a no op the internal session pool handles the session start

Parameters:

dbtype -

lockflags -

stopCdbSession

public void stopCdbSession()

Closes all CdbSessions for the NavuContainer. This is only necessary the case if the the NavuContainer was created with a constructor for CDB access. In such cases it is important to call this method as soon as the NavuContainer has been used. The reason for this is to release any locks on the CDB database as soon as possible. Calling this method several times under the life-cycle of the NavuContainer object is supported.

reset

public abstract void reset()

When navigating through NAVU to a certain location. The sub-tree from a NavuNode start to finish is populated in a lazy fashion. It does that only once and caches the data as available paths. To clear this cache and indicating NAVU that the underlying store has been altered by a second transaction the reset method is used to result in further invocation of the NavuNode operations re-read the values or possible paths to the cache.

exists

public abstract boolean exists()
                        throws NavuException

Generic exists test for Navu navigational elements

Returns:

boolean

Throws:

NavuException

equals

public abstract boolean equals(Object o)

Check the equality of this NavuNode against the targeted NavuNode.

Overrides:

equals in class Object

Returns:

true if this NavuNode represents the same node as the targeted NavuNode

hashCode

public int hashCode()

Return the hashCode of this NavuNode. For most nodes, the hash code is based on the ConfPath of the node. For module root containers there is no ConfPath and instead the hash code is based on the hash code of the module schema.

Overrides:

hashCode in class Object

Returns:

The hashCode

encodeXML

public abstract List<ConfXMLParam> encodeXML()
                                      throws NavuException

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
 

Returns:

A list of ConfXMLParam objects corresponding to the sub-tree of this node, with no values except list keys.

Throws:

NavuException

See Also:

ConfXMLParam, ConfXMLParamValue

encodeValues

public abstract List<ConfXMLParam> encodeValues()
                                         throws NavuException

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

Returns:

A list of ConfXMLParam objects corresponding to the sub-tree of this node, including all values.

Throws:

NavuException

See Also:

ConfXMLParam, ConfXMLParamValue

select

public abstract Collection<NavuNode> select(List<String> query)
                                     throws NavuException

Parameters:

query - a list of regular expression.

Returns:

a collection a nodes marching the query

Throws:

NavuException

select

public abstract Collection<NavuNode> select(String query)
                                     throws NavuException

Parameters:

query - a "/" separated regular expression.

Returns:

a collection a nodes marching the query

Throws:

NavuException

select

public abstract Collection<NavuNode> select(ConfObject[] query)
                                     throws NavuException

Parameters:

query -

Returns:

a collection a nodes matching a Regular Expression query

Throws:

NavuException