Package com.tailf.conf

Class ConfXMLParam

Object
com.tailf.conf.ConfObject
com.tailf.conf.ConfXMLParam
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
ConfXMLParamLeaf, ConfXMLParamStart, ConfXMLParamStartDel, ConfXMLParamStop, ConfXMLParamValue
public abstract class ConfXMLParam extends ConfObject implements Cloneable
Represents the base class of a flat XML structure.

This class is used to represent arbitrary XML trees, typically used as input/output parameters to YANG rpc/action statements. It is also used in methods that set/get multiple values in one call.

Subclasses to this class represents node elements or entries in a ConfXMLParam array. An array of this type form a flat XML structure.

The array is populated, normally through a "depth first" traversal of the data tree, as follows:

  • Optional leafs or presence containers that do not exist are omitted entirely from the array.

  • List and container nodes use one array element where the value has type ConfXMLParamStart, and tag and ns set according to the node name followed by array elements for the sub-nodes according to this list, followed by one array element where the value has type ConfXMLParamStop, and tag and ns set according to the node name. 

     ConfXMLParam[] params =
     new ConfXMLParam[] {
         new ConfXMLParamStart(...),
         .
         .
         new ConfXMLParamStop(...),
         new ConfXMLParamStart(...),
         .
         .
         new ConfXMLParamStop(...),
         new ConfXMLParamStart(...),
         .
         .
         new ConfXMLParamStop(...),
         };

    Each start and stop corresponds to a opening and closing tag in XML.

  • Leafs with a type other than empty uses the instance ConfXMLParamValue for value element and tag and ns according to the node name and additional value set according to the leaf name.

  • Leafs of type empty use an array element where the value has type ConfXMLParamLeaf, and tag and ns set according to the leaf name.

Note that the list or container node corresponding to the complete array is not included in the array. In some usages, non-optional nodes may also be omitted from the array.

Consider the following model: 

  module foo {
   namespace "http://foo.org/yang/servers
   prefix fo;
   import ietf-inet-types {
     prefix inet;
   }
   import tailf-common {
     prefix tailf;
   }

  container servers {
    list server {
        key name;
        max-elements 64;

         leaf name {
           type string;
         }
         leaf ip {
           type inet:host;
           mandatory true;
         }
         leaf port {
          type inet:port-number;
        }
      }
    }
 }
A instance the XML-document of the above could look like: 
  <servers xmlns="http://foo.org/yang/servers">
    <fo:server>
       <fo:name>www0</fo:name>
       <fo:ip>192.168.0.2</fo:ip>
       <fo:port>80</fo:port>
   </fo:server>
   <fo:server>
       <fo:name>www1</fo:name>
       <fo:ip>192.168.0.3</fo:ip>
       <fo:port>8080</fo:port>
   </fo:server>
   <fo:server>
       <fo:name>www2</fo:name>
       <fo:ip>192.168.0.3</fo:ip>
       <fo:port>8081<fo:port>
   </fo:server>
  </fo:servers>

To be able to encode the above XML instance document to a ConfXMLParam[] structure we need to populate a ConfXMLParam array with opening XML tags with instances of ConfXMLParamStart, closing tags with ConfXMLParamStop which represent start and end tag for a container and list entry, as stated above. To express the values we need instances of ConfXMLParamValue.

The above XML snippet would be populated as follow: 

 int i = 0;
 foo ns = new foo(); //instance of the generated namespace
 final int hash = ns.hash;
 ConfXMLParam[] xml = new ConfXMLParam[17];
  xml[i++] = new ConfXMLParamStart(hash,ns._servers);

  xml[i++] = new ConfXMLParamStart(hash,ns._server);
  xml[i++] = new ConfXMLParamValue(hash,ns._name, new ConfBuf("www0"));
  xml[i++] = new ConfXMLParamValue(hash,ns._ip, new ConfBuf("192.168.0.2"));
  xml[i++] = new ConfXMLParamValue(hash,ns._port,new ConfUInt16(80));
  xml[i++] = new ConfXMLParamStop(hash,ns._server);

  xml[i++] = new ConfXMLParamStart(hash,ns._server);
  xml[i++] = new ConfXMLParamValue(hash,ns._name, new ConfBuf("www1"));
  xml[i++] = new ConfXMLParamValue(hash,ns._ip, new ConfBuf("192.168.0.3"));
  xml[i++] = new ConfXMLParamValue(hash,ns._port,new ConfUInt16(8080));
  xml[i++] = new ConfXMLParamStop(hash,ns._server);

  xml[i++] = new ConfXMLParamStart(hash,ns._server);
  xml[i++] = new ConfXMLParamValue(hash,ns._name, new ConfBuf("www2"));
  xml[i++] = new ConfXMLParamValue(hash,ns._ip, new ConfBuf("192.168.0.4"));
  xml[i++] = new ConfXMLParamValue(hash,ns._port,new ConfUInt16(8081));
  xml[i++] = new ConfXMLParamStop(hash,ns._server);

  xml[i++] = new ConfXMLParamStop(hash,ns._servers);
Each ConfXMLParamStart (opening tag) must end with a ConfXMLParamStop (end tag).

As stated above the correct populated ConfXMLParam is used for populate a subtree within one method call, for example Maapi.setValues(int,ConfXMLParam[],ConfPath) or we could extract multiple values in one call, for example Maapi.getValues(int, ConfXMLParam[],String,Object...) or with MAAPI.

And with CDB CdbSession.setValues(ConfXMLParam[],ConfPath).

The ConfXMLParam array is also used in CdbSession.getValues(ConfXMLParam[],ConfPath) to retrieve multiple values in one call.

When we need to extract or retrieve multiple values the ConfXMLParamValue is not known before hand thus we replace the ConfXMLParamValue with instances of ConfXMLParamLeaf before we issue a get request.

For Example: 

 int i = 0;
 foo ns = new foo(); //instance of the generated namespace
 final int hash = ns.hash;
 ConfXMLParam[] xml = new ConfXMLParam[17];
  xml[i++] = new ConfXMLParamStart(hash,ns._servers);

  xml[i++] = new ConfXMLParamStart(hash,ns._server);
  xml[i++] = new ConfXMLParamValue(hash,ns._name, new ConfBuf("www0"));
  xml[i++] = new ConfXMLParamLeaf(hash,ns._ip);
  xml[i++] = new ConfXMLParamLeaf(hash,ns._port);
  xml[i++] = new ConfXMLParamStop(hash,ns._server);

  xml[i++] = new ConfXMLParamStart(hash,ns._server);
  xml[i++] = new ConfXMLParamValue(hash,ns._name, new ConfBuf("www1"));
  xml[i++] = new ConfXMLParamLeaf(hash,ns._ip);
  xml[i++] = new ConfXMLParamLeaf(hash,ns._port);
  xml[i++] = new ConfXMLParamStop(hash,ns._server);

  xml[i++] = new ConfXMLParamStart(hash,ns._server);
  xml[i++] = new ConfXMLParamValue(hash,ns._name, new ConfBuf("www2"));
  xml[i++] = new ConfXMLParamLeaf(hash,ns._ip);
  xml[i++] = new ConfXMLParamLeaf(hash,ns._port);
  xml[i++] = new ConfXMLParamStop(hash,ns._server);

  xml[i++] = new ConfXMLParamStop(hash,ns._servers);

  ConfXMLParam[] returnValues =
      maapi.getValues(th,xml,new ConfPath(thepath));
Note in the above example the list key must be known before hand.

Another usage of the (Conf)XML-Structure is to invoke an action for example Maapi.requestAction(ConfXMLParam[],String,Object...) of a Identifies a model element as a parameter. This is the base class for representing modeled parameters. Consider the following yang model: 

 module cs {
     namespace "http://example.com/test/cs/1.0";
     prefix cs;
     import tailf-common {
         prefix tailf;
     }

     typedef math_op {
         type enumeration {
             enum add;
             enum sub;
             enum mul;
             enum div;
             enum square;
         }
     }

     container system {
         list computer {
             key name;
             leaf name {
                 type string;
             }
             tailf:action math {
                 tailf:actionpoint math_cs;
                 input {
                     list operation {
                         min-elements 1;
                         max-elements 3;
                         leaf number {
                             type int32;
                             mandatory true;
                         }
                         leaf type {
                             type math_op;
                             mandatory true;
                         }
                         leaf-list operands {
                             type int16;
                         }
                     }
                 }
                 output {
                     container result {
                         presence "";
                         leaf number {
                             type int32;
                             mandatory true;
                         }
                         leaf type {
                             type math_op;
                             mandatory true;
                         }
                         leaf value {
                             type int16;
                             mandatory true;
                         }
                     }
                 }
             }
         }
     }
 }
The following is a example of how to assemble the action parameters into and array of ConfXMLParam and its subclasses. The example shows how to populate two list entries: 
 ConfNamespace n = new cs();
 ConfXMLParam[] params =
     new ConfXMLParam[] {
         new ConfXMLParamStart(n, cs.cs_operation_),
         new ConfXMLParamValue(n, cs.cs_number_,  new ConfInt32(13)),
         new ConfXMLParamValue(n, cs.cs_type_,    new ConfEnumeration(0)),
         new ConfXMLParamValue(n, cs.cs_operands_,
                               new ConfList(new ConfObject[] {
                                            new ConfInt16(13),
                                            new ConfInt16(25) })),
         new ConfXMLParamStop(n, cs.cs_operation_),

         new ConfXMLParamStart(n, cs.cs_operation_),
         new ConfXMLParamValue(n, cs.cs_number_,  new ConfInt32(14)),
         new ConfXMLParamValue(n, cs.cs_type_,    new ConfEnumeration(0)),
         new ConfXMLParamValue(n, cs.cs_operands_,
                               new ConfList(new ConfObject[] {
                                            new ConfInt16(15),
                                            new ConfInt16(28) })),
         new ConfXMLParamStop(n, cs.cs_operation_)};
It is also possible to delete leafs and presence containers by setting the value of the corresponding ConfXMLParamValue to ConfNoExist(). However to delete an list element a different approach is necessary. The key value of the list element that is about to be deleted is surrounded by a ConfXMLParamStartDel() and a ConfParamStop as in: 
 int i = 0;
 foo ns = new foo(); //instance of the generated namespace
 final int hash = ns.hash;
 ConfXMLParam[] xml = new ConfXMLParam[] {
        new ConfXMLParamStartDel(hash,ns._servers),
        new ConfXMLParamValue(hash,ns._name, new ConfBuf("www1")),
        new ConfXMLParamStop(hash,ns._server)
    };
  maapi.setValues(th,xml,new ConfPath(thepath));
See Also:

  • Method Details

    • getTagHash

      public Integer getTagHash()
      Returns the hash tag for this parameter.
      Returns:
      The tag hash for this parameter

    • getNSHash

      public Integer getNSHash()
      Returns the namespce hash for this parameter.
      Returns:
      The namespace hash for this parameter

    • getTag

      public String getTag()
      Returns the tag for this parameter.
      Returns:
      The tag for this parameter

    • getConfNamespace

      public ConfNamespace getConfNamespace()
      Returns the namespace for this parameter.
      Returns:
      The namespace for this parameter

    • getValue

      public ConfObject getValue()
      Returns the value for this parameter.
      Returns:
      The value for this parameter

    • decodeParam

      public static ConfXMLParam decodeParam(ConfEObject o) throws ConfException
      Decode the internal representation to a ConfXMLParam Used internally.
      Returns:
      The paramter from the internal representation
      Throws:
      ConfException

    • equals

      public boolean equals(Object o)
      Description copied from class: ConfObject
      Determine if two Conf objects are equal. In general, Conf objects are equal if the components they consist of are equal.
      Specified by:
      equals in class ConfObject
      Parameters:
      o - the object to compare to.
      Returns:
      true if the objects are identical.

    • hashCode

      public int hashCode()
      Specified by:
      hashCode in class ConfObject

    • toXML

      public static String toXML(ConfXMLParam[] params) throws ConfException
      Return String XML representation of a (Conf)XML-structure. A array of ConfXMLParam could represent a frament of a document (e.g does not have a root node) a root node will be created.
      Parameters:
      params - - A array of populated ConfXMLParam or null if null is given or empty string is the length 0
      Returns:
      A XML string representation of this fragment document
      Throws:
      ConfException - If the the populated array is not well structured

    • toXML

      public static String toXML(ConfXMLParam[] params, String parentNode, String parentURI) throws ConfException
      Return String XML representation of a (Conf)XML-structure. A array of ConfXMLParam could represent a frament of a document (e.g does not have a root node) a root node will be created with the specified parameter parentNode with the uri parentURI.
      Parameters:
      params - A array of populated ConfXMLParam or null if null is given or empty string is the length 0
      parentNode - A parent tag that represent the root node.
      parentURI - The ur of the parent node
      Throws:
      ConfException - If the the populated array is not well structured

    • toDOM

      public static Document toDOM(ConfXMLParam[] params) throws ConfException
      Return String DOM document representation of a (Conf)XML-structure. A array of ConfXMLParam could represent a frament of a document (e.g does not have a root node) a root node will be created.
      Parameters:
      params - - A array of populated ConfXMLParam or null if null is given or empty string is the length 0
      Returns:
      A XML string representation of the supplied ConfXMLParam document
      Throws:
      ConfException - If the the populated array is not well structured

    • toDOM

      public static Document toDOM(ConfXMLParam[] params, String parentNode, String parentURI) throws ConfException
      Return String DOM representation of a (Conf)XML-structure. A array of ConfXMLParam could represent a frament of a document (e.g does not have a root node) a root node will be created with the specified parameter parentNode with the uri parentURI.
      Parameters:
      params - A array of populated ConfXMLParam or null if null is given or empty string is the length 0
      parentNode - A parent tag that represent the root node.
      parentURI - The ur of the parent node
      Returns:
      A DOM document representation of the supplied ConfXMLParam array paramter
      Throws:
      ConfException - If the the populated array is not well structured

    • toXMLParams

      public static ConfXMLParam[] toXMLParams(String xml, ConfPath path) throws ConfException
      Converts an xml snippet to a corresponding ConfXMLParam[]. The resulting ConfXMLParam[] is prepared for a getValues() call.
      Parameters:
      xml - well formed XML string that represent a instance document rooted by the path
      path - Start node (or root path) of the XML document
      Returns:
      The resulting ConfXMLParam[]
      Throws:
      ConfException

    • toXMLParams

      public static ConfXMLParam[] toXMLParams(String xml, ConfPath path, int mode) throws ConfException
      Converts an xml snippet to a corresponding ConfXMLParam[]. The mode parameter controls whether this ConfXMLParam[] should be prepared for a getValues() call or for a setValues() call using using XMLtoConfXMLParam.MODE_GET or XMLtoConfXMLParam.MODE_SET respectively.
      Parameters:
      xml - well formed XML string that represent a instance document rooted by the path
      path - Start node (or root path) of the XML document
      mode - one of XMLtoConfXMLParam.MODE_GET or XMLtoConfXMLParam.MODE_SET
      Returns:
      The resulting ConfXMLParam[]
      Throws:
      ConfException

    • toString

      public String toString()
      Specified by:
      toString in class ConfObject
      Returns:
      the printable representation of the object.

    • encode

      public static ConfEObject encode(ConfXMLParam[] params)

    • encode

      public static ConfEObject encode(List<String> mountId, ConfXMLParam[] params)

    • encode

      public ConfEObject encode()
      Specified by:
      encode in class ConfObject

    • encode

      public ConfEObject encode(List<String> mountId)

    • encodeIKP

      public static ConfEObject encodeIKP(ConfXMLParam[] params)

    • encodeIKP

      public static ConfEObject encodeIKP(List<String> mountId, ConfXMLParam[] params)

    • encodeHKP

      public static ConfEObject encodeHKP(ConfXMLParam[] params)

    • encodeHKP

      public static ConfEObject encodeHKP(List<String> mountId, ConfXMLParam[] params)

    • encodeIKP

      public ConfEObject encodeIKP()

    • encodeIKP

      public ConfEObject encodeIKP(List<String> mountId)

    • encodeHKP

      public ConfEObject encodeHKP()
      Encode this ConfXMLParam to HKP representation (i.e hashbased [ns | tag] where where ns and tag are both in long). This does not rely on ConfNamespace.

    • encodeHKP

      public ConfEObject encodeHKP(List<String> mountId)

    • decodeParams

      public static ConfXMLParam[] decodeParams(ConfEObject o) throws ConfException
      Throws:
      ConfException