com.tailf.jnc

Class YangElement

java.lang.Object

com.tailf.jnc.Element

com.tailf.jnc.YangElement

All Implemented Interfaces:

java.io.Serializable

public abstract class YangElement
extends Element

The YangElement is a configuration sub-tree like the Element. It is an extension of the Element class to make the configuration sub-tree data model aware. Classes generated from the JNC pyang plugin are either YangElements or derived data types. Thus the YangElement which is an abstract class is never used directly.

Fundamental methods for comparing, syncing, and inspecting sets of configuration data, is provided by this class. The following two methods highlights the fundamental purpose of this library:

• checkSync - checks if two configurations are equal, or if a sync is needed. This is a typical operation a manager would like to do when one configuration is stored on the device and the other is stored in a database.
• sync - will calculate the difference between two configuration sub trees and build up a resulting subtree which is basically a tree with NETCONF operations needed to turn the source tree into the target tree. The purpose of this is to find a minimal set of operations to sync two configurations so that they become equal.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	COLON_UNEXPECTED_ELEMENT
static java.lang.String	DUMMY
static java.lang.String	DUMMY_LC

Fields inherited from class com.tailf.jnc.Element

children, CREATE_MERGE, CREATE_MERGE_MULTI, CREATE_NEW, defaultPrefixes, name, namespace, NETCONF_NAMESPACE, OP_CREATE, OP_DELETE, OP_MERGE, OP_REPLACE, OPERATION, parent, prefixes, value

Constructor Summary

Constructors

Constructor and Description
YangElement(java.lang.String ns, java.lang.String name) Constructor with namespace and name

Method Summary

Modifier and Type	Method and Description
protected static java.lang.String	camelize(java.lang.String s)
static boolean	checkSync(NodeSet a, NodeSet b) Checks if two configurations are equal, or if a sync is needed.
boolean	checkSync(YangElement b) Checks if two configurations are equal, or if a sync is needed.
static boolean	checkSync(YangElement a, YangElement b) Checks if two configurations are equal, or if a sync is needed.
protected abstract java.lang.String[]	childrenNames() Structure information.
protected YangElement	cloneContent(YangElement copy) Clones the content of this YangElement into a target copy.
protected abstract Element	cloneShallow() Clones a YangElement.
protected YangElement	cloneShallowContent(YangElement copy) Clones the contents of this YangElement into a target copy.
int	compare(Element b) Compares children values of this YangElement with those of another Element.
int	compare(YangElement b) Compares children values of this YangElement with those of another YangElement.
protected static Element	createInstance(com.tailf.jnc.ElementHandler parser, Element parent, java.lang.String ns, java.lang.String name) Creates an instance of a child using class generated by the JNC pyang plugin.
protected void	encode(Transport out, boolean newline_at_end, Capabilities capas) Encode to XML and send it to the provided stream.
static void	getDiff(YangElement a, YangElement b, NodeSet uniqueA, NodeSet uniqueB, NodeSet changedA, NodeSet changedB) Produces the 'diff' between two trees.
static java.lang.String	getPackage(java.lang.String ns) Locate package from Namespace.
boolean	isChild(java.lang.String childName) Checks if this YangElement has a child with specified name.
protected boolean	isLeafDefault(java.lang.String path)
boolean	keyCompare(YangElement b) Given two (YANG) list entries - compare the keys and return true if both YANG objects are the same
protected abstract java.lang.String[]	keyNames() Structure information.
protected void	markLeafCreate(java.lang.String path)
protected void	markLeafDelete(java.lang.String path)
protected void	markLeafMerge(java.lang.String path)
protected void	markLeafReplace(java.lang.String path)
protected static java.lang.String	normalize(java.lang.String s)
static YangElement	readFile(java.lang.String filename) Read file with XML text and parse it into a data model aware configuration tree.
static void	removePackage(java.lang.String ns) Remove a package from the list of Packages
protected YangElement	searchOne(java.lang.String path)
protected void	setLeafListValue(java.lang.String ns, java.lang.String path, java.lang.Object value, java.lang.String[] childrenNames)
protected void	setLeafValue(java.lang.String ns, java.lang.String path, java.lang.Object value, java.lang.String[] childrenNames)
void	setLeafValue(java.lang.String ns, java.lang.String name, java.lang.String value) Sets the leaf value of the specified leaf of this YangElement.
static void	setPackage(java.lang.String ns, java.lang.String pkg) Assiciate a JAVA package with a namespace.
static NodeSet	sync(NodeSet a, NodeSet b) Will return a list of subtrees for syncing a subtree A with all the necessary operations to make it look like the target tree B.
YangElement	sync(YangElement b) Will return a subtree for syncing a subtree A with all the necessary operations to make it look like the target tree B.
static YangElement	sync(YangElement a, YangElement b) Will return a subtree for syncing a subtree A with all the necessary operations to make it look like the target tree B.
static NodeSet	syncMerge(NodeSet a, NodeSet b) Returns a list of subtrees for syncing a subtree A with all the necessary operations to make it look like the target tree B.
static YangElement	syncMerge(YangElement a, YangElement b) Will return a subtree for syncing a subtree A with all the necessary operations to make it look like the target tree B.

Methods inherited from class com.tailf.jnc.Element

addAttr, addChild, clone, cloneAttrs, cloneValue, create, create, create, createChild, createChild, createChild, createPath, createPath, createPath, createPath, createPath, createPath, delete, delete, deleteChild, deleteValue, deleteValue, encode, encode, encode, equals, exists, get, getAttr, getAttrs, getAttrValue, getChild, getChild, getChildren, getChildren, getContextPrefixMap, getElementPath, getElementPath, getFirst, getLast, getParent, getRootElement, getValue, getValue, getValueOfChild, getValues, getValuesAsSet, hasChildren, hashCode, insertChild, insertChild, insertChild, insertFirst, insertLast, iterator, iterator, lookupContextPrefix, markCreate, markCreate, markDelete, markDelete, markMerge, markMerge, markReplace, markReplace, merge, nsToPrefix, position, prefix, qualifiedName, removeAttr, removeAttr, removeDefaultPrefix, removeMark, removeMarks, removePrefix, setAttr, setAttr, setDebugLevel, setDefaultPrefix, setPrefix, setPrefix, setPrefix, setValue, setValue, tagpath, toString, toXMLString, writeFile

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

COLON_UNEXPECTED_ELEMENT

public static final java.lang.String COLON_UNEXPECTED_ELEMENT

See Also:

Constant Field Values

DUMMY

public static final java.lang.String DUMMY

See Also:

Constant Field Values

DUMMY_LC

public static final java.lang.String DUMMY_LC

See Also:

Constant Field Values

Constructor Detail

YangElement

public YangElement(java.lang.String ns,
                   java.lang.String name)

Constructor with namespace and name

Method Detail

childrenNames

protected abstract java.lang.String[] childrenNames()

Structure information. An array of the children names.

keyNames

protected abstract java.lang.String[] keyNames()

Structure information. An array of the names of the key children.

createInstance

protected static Element createInstance(com.tailf.jnc.ElementHandler parser,
                                        Element parent,
                                        java.lang.String ns,
                                        java.lang.String name)
                                 throws YangException

Creates an instance of a child using class generated by the JNC pyang plugin.

Parameters:

parser - ElementHandler to set unknownLevel in, in case incoming data uses a newer revision

parent - The parent element of the child to be instantiated, null if root.

ns - Namespace of the child to be instantiated

name - Name of the child to be instantiated

Returns:

The created element or null if no element was created.

Throws:

YangException - if unable to instantiate the child

setLeafValue

public void setLeafValue(java.lang.String ns,
                         java.lang.String name,
                         java.lang.String value)
                  throws YangException,
                         JNCException

Sets the leaf value of the specified leaf of this YangElement.

Parameters:

ns -

name -

value -

Throws:

YangException

JNCException

getPackage

public static java.lang.String getPackage(java.lang.String ns)

Locate package from Namespace.

Returns:

Package name, if namespace is data model aware

setPackage

public static void setPackage(java.lang.String ns,
                              java.lang.String pkg)

Assiciate a JAVA package with a namespace.

removePackage

public static void removePackage(java.lang.String ns)

Remove a package from the list of Packages

camelize

protected static java.lang.String camelize(java.lang.String s)

normalize

protected static java.lang.String normalize(java.lang.String s)

setLeafValue

protected void setLeafValue(java.lang.String ns,
                            java.lang.String path,
                            java.lang.Object value,
                            java.lang.String[] childrenNames)
                     throws JNCException

Throws:

JNCException

setLeafListValue

protected void setLeafListValue(java.lang.String ns,
                                java.lang.String path,
                                java.lang.Object value,
                                java.lang.String[] childrenNames)
                         throws JNCException

Throws:

JNCException

isLeafDefault

protected boolean isLeafDefault(java.lang.String path)
                         throws JNCException

Throws:

JNCException

markLeafReplace

protected void markLeafReplace(java.lang.String path)
                        throws JNCException

Throws:

JNCException

markLeafMerge

protected void markLeafMerge(java.lang.String path)
                      throws JNCException

Throws:

JNCException

markLeafCreate

protected void markLeafCreate(java.lang.String path)
                       throws JNCException

Throws:

JNCException

markLeafDelete

protected void markLeafDelete(java.lang.String path)
                       throws JNCException

Throws:

JNCException

searchOne

protected YangElement searchOne(java.lang.String path)
                         throws JNCException

Throws:

JNCException

keyCompare

public boolean keyCompare(YangElement b)

Given two (YANG) list entries - compare the keys and return true if both YANG objects are the same

compare

public int compare(YangElement b)

Compares children values of this YangElement with those of another YangElement. Returns:

• 0 - if the name, namespace, value and children of this YangElement are equal to the name, namespace, value and children of b.
• -1 - if name, namespace, value or the key children are not equal.
• 1 - if the key children of this YangElement are equal to those of b, but non-key children are different.

Parameters:

b - YangElement to compare against.

Returns:

-1 if not equal, 0 if completely equal, 1 if same except for non-key children

compare

public int compare(Element b)

Compares children values of this YangElement with those of another Element. Returns:

• 0 - if the name, namespace, value and children of this YangElement are equal to the name, namespace, value and children of b.
• -1 - if name, namespace, value or the key children are not equal.
• 1 - if the key children of this YangElement are equal to those of b, but non-key children are different.

Overrides:

compare in class Element

Parameters:

b - Element to compare against.

Returns:

-1 if not equal, 0 if completely equal, 1 if same except for non-key children

getDiff

public static void getDiff(YangElement a,
                           YangElement b,
                           NodeSet uniqueA,
                           NodeSet uniqueB,
                           NodeSet changedA,
                           NodeSet changedB)

Produces the 'diff' between two trees. Nodes that differ in the compare method are added to one of the four provided node sets.

• Elements unique to node tree A are put in uniqueA.
• Elements unique to node tree B are put in uniqueB.
• Dynamic elements that differ, but have the same keys, are put in the respective node sets changedA and changedB.

If the two trees are identical the three returned nodesets will be empty.

Attributes are not included in the inspection. Only YangElement structures and leaf-values are checked.

Note that both subtrees must have a common starting point YangElement in order to compare them.

Parameters:

a - Subtree A (YangElement)

b - Subtree B (YangElement)

uniqueA - Place for elements that are unique to A.

uniqueB - Place for elements that are unique to B.

changedA - Place for elements changed in A.

changedB - Place for elements changed in B.

checkSync

public boolean checkSync(YangElement b)

Checks if two configurations are equal, or if a sync is needed.

Parameters:

b -

Returns:

'true' if both trees are equal. 'false' otherwise.

checkSync

public static boolean checkSync(NodeSet a,
                                NodeSet b)

Checks if two configurations are equal, or if a sync is needed.

Returns:

'true' if both trees are equal. 'false' otherwise.

checkSync

public static boolean checkSync(YangElement a,
                                YangElement b)

Checks if two configurations are equal, or if a sync is needed.

Returns:

'true' if both trees are equal. 'false' otherwise.

sync

public YangElement sync(YangElement b)
                 throws JNCException

Will return a subtree for syncing a subtree A with all the necessary operations to make it look like the target tree B.

Returns:

Return subtree with operations to transmute subtree A into subtree B.

Throws:

JNCException

sync

public static YangElement sync(YangElement a,
                               YangElement b)
                        throws JNCException

Will return a subtree for syncing a subtree A with all the necessary operations to make it look like the target tree B. This verion of sync will produce a NETCONF tree with NETCONF replace operations where all list entries that differ are replaced with a new list entry using "nc:operation="replace". An alternative (and better) method is "merge". The method syncMerge(com.tailf.jnc.NodeSet, com.tailf.jnc.NodeSet) produces a NETCONF tree with the merge operation instead.

Returns:

Return subtree with operations to transmute subtree A into subtree B.

Throws:

JNCException

syncMerge

public static NodeSet syncMerge(NodeSet a,
                                NodeSet b)
                         throws JNCException

Returns a list of subtrees for syncing a subtree A with all the necessary operations to make it look like the target tree B. This variant uses the NETCONF merge operation.

Returns:

Subtrees with operations to transmute subtree A into subtree B.

Throws:

JNCException

syncMerge

public static YangElement syncMerge(YangElement a,
                                    YangElement b)

Will return a subtree for syncing a subtree A with all the necessary operations to make it look like the target tree B. This version of sync will produce a NETCONF tree with NETCONF merge operations.

Returns:

Subtree with operations to transmute subtree A into subtree B.

sync

public static NodeSet sync(NodeSet a,
                           NodeSet b)
                    throws JNCException

Will return a list of subtrees for syncing a subtree A with all the necessary operations to make it look like the target tree B.

Returns:

Return subtrees with operations to transmute subtree A into subtree B.

Throws:

JNCException

cloneShallow

protected abstract Element cloneShallow()

Clones a YangElement. Only key children are cloned, the other children are skipped. Attributes and values are cloned.

Overrides:

cloneShallow in class Element

Returns:

A clone of this YangElement with the same key children, attributes and values.

cloneShallowContent

protected YangElement cloneShallowContent(YangElement copy)

Clones the contents of this YangElement into a target copy. All content is copied except children (shallow).

Note: Used by the generated JNC classes The key children are already cloned.

Parameters:

copy - The target copy to clone the contents to

Returns:

copy with attributes and prefix of this YangElement added.

cloneContent

protected YangElement cloneContent(YangElement copy)

Clones the content of this YangElement into a target copy. Key children are not copied.

Note: Used by the generated JNC classes. The key children should already be cloned into copy.

Parameters:

copy - The target copy to clone the contents into

Returns:

copy with non-key children, attributes and values of this YangElement added.

readFile

public static YangElement readFile(java.lang.String filename)
                            throws JNCException

Read file with XML text and parse it into a data model aware configuration tree.

Parameters:

filename - File name.

Throws:

JNCException

See Also:

Element.writeFile(String)

encode

protected void encode(Transport out,
                      boolean newline_at_end,
                      Capabilities capas)
               throws JNCException

Description copied from class: Element

Encode to XML and send it to the provided stream. Similar to the toXMLString(), but without the pretty printing.

The newline_at_end argument controls whether a newline char is permitted at the end or not.

Overrides:

encode in class Element

Parameters:

out - Stream to send the encoded version of this element to.

newline_at_end - If 'true' a newline is printed at the end.

Throws:

JNCException - If a YangElement encode implementation fails.

isChild

public boolean isChild(java.lang.String childName)

Checks if this YangElement has a child with specified name.

Parameters:

childName - The name to check for

Returns:

true if the child exists, false otherwise.