Package com.tailf.navu

Class NavuContainer

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 can also be created using one of its constructors, typically NavuContainer(NavuContext). A NavuContainer is created with a NavuContext initialized with a Maapi socket: 

   NavuContext context = new NavuContext(maapi);
   context.startRunningTrans(Conf.MODE_READ_WRITE);
   NavuContainer root = new NavuContainer(context);

As shown above, a transaction must be started before the context can be used for navigating.

A transaction can alternatively be started for operational data instead: 

   NavuContext context = new NavuContext(maapi);
   context.startOperationalTrans(Conf.MODE_READ_WRITE);
   NavuContainer root = new NavuContainer(context);

Either way, when a NavuContainer is created using the above mentioned context, the object pointed to by root is the "root" of the NAVU-Tree.

The root's children represent all of the loaded modules. To choose a particular module, the method container(Integer) must be called with the hash value of the corresponding module (ConfNamespace.hash()). This will return a new NavuContainer pointing to the root of the chosen module. 

   NavuContainer module = root.container(new Ncs().hash());

To continue further down to the next child, use container(Integer), container(String), list(Integer), list(String) or leaf(Integer), leaf(String) as dictated by the YANG model. 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 are used for convenience. The absence of underscore (_) at the end of the static field name indicates the integer version.

Then continuing with the devices node: 

   NavuContainer devicesNode = module.container(Ncs._devices);

  • Constructor Details

    • NavuContainer

      public NavuContainer()
      This constructor creates a root container. This container holds all loaded schemas as its children.

    • 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

    • 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

      @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

  • Method Details

    • 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.
      Overrides:
      namespace in class NavuNode
      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 container(String).
      Overrides:
      container in class NavuNode
      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.
      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 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.

      Overrides:
      container in class NavuNode
      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 container(ConfNamespace, String) or namespace(String) .container(String) instead.
      Overrides:
      container in class NavuNode
      Throws:
      NavuException

    • leaf

      public NavuLeaf leaf(Integer key) throws NavuException
      Returns a reference to a subordinate leaf with the hash value key.
      Overrides:
      leaf in class NavuNode
      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.
      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 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.

      Overrides:
      leaf in class NavuNode
      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 key in the namespace ns

    • leaf

      @Deprecated public NavuLeaf leaf(String prefix, String key) throws NavuException
      Deprecated.
      Use leaf(ConfNamespace, String) or namespace(String) .leaf(String) instead.
      Overrides:
      leaf in class NavuNode
      Throws:
      NavuException

    • leafList

      public NavuLeafList leafList(Integer key) throws NavuException
      Returns a reference to a subordinate leaf-list with the hash value key.
      Overrides:
      leafList in class NavuNode
      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.
      Overrides:
      leafList in class NavuNode
      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.

      Overrides:
      leafList in class NavuNode
      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 in the namespace ns

    • leafList

      @Deprecated public NavuLeafList leafList(String prefix, String key) throws NavuException
      Deprecated.
      Use leafList(ConfNamespace, String) or namespace(String) .leafList(String) instead.
      Overrides:
      leafList in class NavuNode
      Throws:
      NavuException

    • list

      public NavuList list(Integer key) throws NavuException
      Returns a reference to a subordinate list with the hash value key.
      Overrides:
      list in class NavuNode
      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.
      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 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.

      Overrides:
      list in class NavuNode
      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 list(ConfNamespace, String) or namespace(String) .list(String) instead.
      Overrides:
      list in class NavuNode
      Throws:
      NavuException

    • action

      public NavuAction action(Integer key) throws NavuException
      Returns a reference to a subordinate action with the 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 an action node or if there is no subordinate node with the hash value key

    • action

      public NavuAction action(String key) throws NavuException
      Returns a reference to a subordinate action with the name 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 there is no subordinate node with the name key

    • isListInstance

      public boolean isListInstance()
      Returns true if this NavuContainer represents a list-entry
      Returns:
      true if this NavuContainer is a list-entry false otherwise

    • 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

    • children

      public Collection<NavuNode> children() throws NavuException
      Returns a collection containing the children of this container.
      Overrides:
      children in class NavuNode
      Returns:
      the children of this container
      Throws:
      NavuException

    • choice

      public NavuChoice choice(String name) throws NavuException
      Returns a reference to a subordinate choice with the name name.
      Parameters:
      name - the name of the choice to return
      Returns:
      a matching choice
      Throws:
      NavuException

    • containsNode

      public boolean containsNode(NavuNode node) throws NavuException
      Checks if the given node is a direct child of this container according to the schema.
      Parameters:
      node -
      Returns:
      true if node is a child of this container
      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 if there is a match
      Throws:
      NavuException

    • create

      public NavuContainer create() throws NavuException
      Creates an optional container.
      Returns:
      a pointer to self.
      Throws:
      NavuException

    • 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

    • 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

    • exists

      public boolean exists() throws NavuException
      Verifies the existence of container.
      Specified by:
      exists in class NavuNode
      Returns:
      boolean
      Throws:
      NavuException

    • delete

      public NavuContainer delete() throws NavuException
      Deletes an optional container.
      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:

    • encodeValues

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

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

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

    • entrySet

      public Set<Map.Entry<String,NavuNode>> entrySet() throws NavuException
      Returns a set of value-pairs.
      Returns:
      a set of nodeName-node pairs according to the schema
      Throws:
      NavuException

    • findChanges

      public Map<ConfKey,NavuChange> findChanges(NavuContext delContext, 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.
      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.

      Parameters:
      delContext - NavuContext to retrieve deleted values with.
      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:
      NavuException

    • findChanges

      @Deprecated public Map<ConfKey,NavuChange> findChanges(Integer[] criteria) throws NavuException
      Deprecated.
      Since this method cannot return delete changes in a reliable way this method is deprecated. Use instead findChanges(NavuContext, Integer[])
      Throws:
      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

    • 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

    • getSelectCaseAsNavuNode

      public List<NavuNode> getSelectCaseAsNavuNode(String choice) throws NavuException
      Returns a collection of the top-level node elements of the currently selected case of the specified choice. 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 constitute this case is defined by the model or has to be tested.

      Parameters:
      choice - the choice name to get selected case for
      Returns:
      top-level NavuNodes for the selected case or null if no case is selected.
      Throws:
      NavuException - if this container does not contains the choice with the specified name choice

    • 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

    • isEmpty

      public boolean isEmpty() throws NavuException
      Checks if the container has any members.
      Returns:
      true if it has 1 or more members.
      Throws:
      NavuException

    • 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

    • 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

    • reset

      public void reset()
      Resets the contained nodes
      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

    • setChange

      public NavuNode setChange(List<ConfObject> path, DiffIterateOperFlag op, ConfValue oldValue, NavuContext delContext) throws NavuException
      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.
      Parameters:
      child - the child node doing the update.
      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

    • 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.

    • 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

    • 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

    • equals

      public boolean equals(Object o)
      Compares the specified object with this NavuContainer for equality. Returns true if the specified object is also a NavuContainer and either of the following is true:
      • Both nodes are modules according to NavuNodeInfo.isModule()) and they have the same namespace URI.
      • The nodes are not modules, and have identical ConfPath instances.
      Specified by:
      equals in class NavuNode
      Parameters:
      o - the object to be compared for equality with this NavuContainer
      Returns:
      true if the specified object is equal to this NavuContainer