Package com.tailf.navu

Class NavuLeaf

Object

com.tailf.navu.NavuNode

com.tailf.navu.NavuLeaf

Direct Known Subclasses:

NavuLeafList

public class NavuLeaf
extends NavuNode

The NavuLeaf class corresponds to the YANG leaf and leaf-list node types. A NavuLeaf is a node in the NAVU-Tree that that does not have any children and holds a value.

To retrieve a value the method value() should be called which on first invocation retrieves the value through the current context. Subsequent calls to the value method will return the "cached" value. It is important to understand that the first call to value method will cache the value in the instance which means that subsequent calls to the value will return the cached value. To clear the cache held by an instance of NavuLeaf, the method reset() should be called.

Method Summary

Modifier and Type	Method	Description
void	create()	Create an empty leaf node.
NavuLeaf	delete()	Deletes a leaf.
List<NavuNode>	deref()	Derefs a leafref and returns the referenced objects
List<ConfXMLParam>	encodeValues()	Encodes the sub-tree including the current NavuNode as the topmost NavuNode as a ConfXMLParam array.
List<ConfXMLParam>	encodeXML()	Encodes the sub-tree including the current NavuNode as the topmost NavuNode as a ConfXMLParam array.
boolean	equals(Object o)	Compares the specified object with this NavuLeaf for equality.
boolean	exists()	Tests for the existence of the leaf node.
DiffIterateOperFlag	getChangeFlag()	Returns the latest change that this NavuNode has been a subject to by a transaction.
ConfValue	getOldValue()
NavuNode	getParent()	Returns the parent of the node.
ConfNamespace	getRootNS()	Returns the root namespace of the topmost ancestor.
ConfXMLParam[]	getValues(String xml)	Read an arbitrary set of sub-elements of a container or list entry.
int	hashCode()	Return the hashCode of this NavuNode.
boolean	idrefDerivedOrSelf(ConfIdentityRef base)
boolean	isKey()	Returns true if this NavuLeaf is a key node.
void	reset()	When navigating through NAVU to a certain leaf and retrieving its value, this value will be cached.
void	safeCreate()	Create an empty leaf node, silently succeeding if the leaf already exists
Collection<NavuNode>	select(ConfObject[] query)
Collection<NavuNode>	select(String path)
Collection<NavuNode>	select(List<String> path)
void	set(ConfValue val)	Sets the value of the leaf node.
void	set(String val)	Sets the value and tries to perform an update.
NavuNode	setChange(List<ConfObject> kp, DiffIterateOperFlag op, ConfValue oldValue, NavuContext delContext)
void	setValues(String xml)	This method is almost identical to set(String) with the exception that the value should be wrapped inside XML tag.
void	sharedCreate()	Create an empty leaf node, silently succeeding if the leaf already exists and also maintain the FASTMAP reference counter on the leaf.
void	sharedSet(ConfValue val)	Sets the value of a leaf node with FastMap support, creating backpointers and reference counter similar to sharedCreate() All FastMap code shall (in principle) allways use this method instead of set()
void	sharedSet(String val)	SharedSet using string representation of value.
ConfKey	toKey()	Convert the leaf value to a ConfKey.
String	toString()
ConfValue	value()	Returns the effective value on the first call, or cached value in the subsequent calls of this leaf.
String	valueAsString()	Returns the Schema aware string representation of a leaf.
void	valueUpdateInd(NavuNode child)

Methods inherited from class com.tailf.navu.NavuNode

children, container, container, container, context, getChanges, getChanges, getChanges, getConfPath, getInfo, getKeyPath, getName, getNavuNode, getValues, leaf, leaf, leaf, leafList, leafList, leafList, list, list, list, namespace, prepareXMLCall, setValues, sharedSetValues, sharedSetValues, stopCdbSession, xPathSelect, xPathSelectIterate

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Details

isKey

public boolean isKey()

Returns true if this NavuLeaf is a key node.

Returns:

true whether this NavuLeaf is a key node false otherwise

delete

public NavuLeaf delete()
                throws NavuException

Deletes a leaf.

Returns:

a pointer to self.

Throws:

NavuException

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:

• ConfXMLParam
• ConfXMLParamValue

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:

• ConfXMLParam
• ConfXMLParamValue

reset

public void reset()

When navigating through NAVU to a certain leaf and retrieving its value, this value will be cached. This method will reset the cache and indicate that the value should be re-read next time the value is 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

getValues

public ConfXMLParam[] getValues(String xml)
                         throws NavuException

Description copied from class: NavuNode

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>");

 

Overrides:

getValues in class NavuNode

Parameters:

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

Throws:

NavuException

sharedSet

public void sharedSet(ConfValue val)
               throws NavuException

Sets the value of a leaf node with FastMap support, creating backpointers and reference counter similar to sharedCreate() All FastMap code shall (in principle) allways use this method instead of set()

Throws:

NavuException

sharedSet

public void sharedSet(String val)
               throws NavuException

SharedSet using string representation of value. Sets the value of a leaf node with FastMap support, creating backpointers and reference counter similar to sharedCreate() All FastMap code shall (in principle) always use this method instead of set()

Throws:

NavuException

set

public void set(ConfValue val)
         throws NavuException

Sets the value of the leaf node.

When setting a leaf node the cached value inside the instance is reflected. Subsequent calls to value retrieves the cached value.

Setting a leaf value is only valid when writing to a transaction or when writing to operational data store.

When writing to the operational data store the write is done with the CdbLockType.LOCK_REQUEST lock type set.

Parameters:

val - - the value to set

Throws:

NavuException - If an error occurred when setting the leaf value the underlying/caused exception is wrapped inside the NavuException and should be retrieved through getCause method of Throwable.

An IllegalArgumentException is wrapped inside a NavuException if writes is done to running with NavuContext created with CdbSession or Cdb.

setValues

public void setValues(String xml)
               throws NavuException

This method is almost identical to set(String) with the exception that the value should be wrapped inside XML tag.

For example to set the value "123" it needs to be wrapped with "<leaf-name>123 </leaf-name>.

Overrides:

setValues in class NavuNode

Parameters:

xml - A string value wrapped inside XML tag.

Throws:

NavuException

See Also:

• NavuNode.setValues(ConfXMLParam[])
• ConfXMLParam

set

public void set(String val)
         throws NavuException

Sets the value and tries to perform an update. For this to succeed, it must be possible to convert this string value into a value consistent with the type of the NavuLeaf. For example "123" if the YANG model has a leaf of, for example "int32".

Parameters:

val - The string representation of a new value. For this to succeed, it must be possible to convert this string value into a value consistent with the type of the NavuLeaf. For example "123" if the YANG model has a leaf of, for example "int32".

Throws:

NavuException

exists

public boolean exists()
               throws NavuException

Tests for the existence of the leaf node.

Specified by:

exists in class NavuNode

Returns:

boolean

Throws:

NavuException - on failure

create

public void create()
            throws NavuException

Create an empty leaf node.

Throws:

NavuException - on failure to create

safeCreate

public void safeCreate()
                throws NavuException

Create an empty leaf node, silently succeeding if the leaf already exists

Throws:

NavuException - on failure to create

sharedCreate

public void sharedCreate()
                  throws NavuException

Create an empty leaf node, silently succeeding if the leaf already exists and also maintain the FASTMAP reference counter on the leaf.

Throws:

NavuException - on failure to create

toKey

public ConfKey toKey()
              throws NavuException

Convert the leaf value to a ConfKey. This is convenient, but only works for lists that have singleton keys.

Returns:

the leaf value represented as a key.

Throws:

NavuException

toString

public String toString()

Overrides:

toString in class Object

value

public ConfValue value()
                throws NavuException

Returns the effective value on the first call, or cached value in the subsequent calls of this leaf.

After this method has been called the first time it stores the value in this object which means that subsequent calls to this method will return the cached value.

Returns:

the effective value (first call) or cached value in subsequent calls of this leaf.

Throws:

NavuException

valueAsString

public String valueAsString()
                     throws NavuException

Returns the Schema aware string representation of a leaf.

An example of the difference between this method and toString() is for ConfEnumerations where the schema aware representation is the label while toString() returns a representation of the ordinal value.

Returns:

String representation of the leaf

Throws:

NavuException

valueUpdateInd

public void valueUpdateInd(NavuNode child)

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:

• DiffIterateOperFlag

getOldValue

public ConfValue getOldValue()

Returns:

the old value. null if no old value exists.

setChange

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

Throws:

NavuException

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[] query)

Specified by:

select in class NavuNode

Returns:

a collection a nodes matching a Regular Expression query

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.

deref

public List<NavuNode> deref()
                     throws NavuException

Derefs a leafref and returns the referenced objects

Returns:

array of keypaths where each keypath is an array of ConfObject

Throws:

NavuException

idrefDerivedOrSelf

public boolean idrefDerivedOrSelf(ConfIdentityRef base)
                           throws NavuException

Throws:

NavuException

equals

public boolean equals(Object o)

Compares the specified object with this NavuLeaf for equality. Returns true if the given object is also a NavuLeaf and it has the same ConfPath as this NavuLeaf. Note that the actual values held by the leaves (if any) are ignored as they are not relevant to this comparison.

Overrides:

equals in class NavuNode

Parameters:

o - the object to be compared for equality with this NavuLeaf

Returns:

true if the specified object is equal to this NavuLeaf

hashCode

public int hashCode()

Description copied from class: NavuNode

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 NavuNode

Returns:

The hashCode