ConfXMLParam (NSO Java API Version 5.8.4)

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:: Serialized Form

Field Summary
- Fields inherited from class com.tailf.conf.ConfObject
  J_BINARY, J_BIT32, J_BIT64, J_BITBIG, J_BOOL, J_BUF, J_CDBBEGIN, J_DATE, J_DATETIME, J_DECIMAL64, J_DEFAULT, J_DOUBLE, J_DQUAD, J_DURATION, J_ENUMERATION, J_HEXSTR, J_IDENTITYREF, J_INSTANCE_IDENTIFIER, J_INT16, J_INT32, J_INT64, J_INT8, J_IPV4, J_IPV4_AND_PLEN, J_IPV4PREFIX, J_IPV6, J_IPV6_AND_PLEN, J_IPV6PREFIX, J_LIST, J_NOEXISTS, J_OBJECTREF, J_OID, J_PTR, J_QNAME, J_STR, J_SYMBOL, J_TIME, J_UINT16, J_UINT32, J_UINT64, J_UINT8, J_UNION, J_XMLBEGIN, J_XMLBEGINDEL, J_XMLEND, J_XMLMOVEAFTER, J_XMLMOVEFIRST, J_XMLTAG

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static ConfXMLParam`	`decodeParam(ConfEObject o)` Decode the internal representation to a `ConfXMLParam` Used internally.
`static ConfXMLParam[]`	`decodeParams(ConfEObject o)`
`ConfEObject`	`encode()`
`static ConfEObject`	`encode(ConfXMLParam[] params)`
`ConfEObject`	`encode(List<String> mountId)`
`static ConfEObject`	`encode(List<String> mountId, ConfXMLParam[] params)`
`ConfEObject`	`encodeHKP()` Encode this ConfXMLParam to HKP representation (i.e hashbased [ns \| tag] where where ns and tag are both in long).
`static ConfEObject`	`encodeHKP(ConfXMLParam[] params)`
`ConfEObject`	`encodeHKP(List<String> mountId)`
`static ConfEObject`	`encodeHKP(List<String> mountId, ConfXMLParam[] params)`
`ConfEObject`	`encodeIKP()`
`static ConfEObject`	`encodeIKP(ConfXMLParam[] params)`
`ConfEObject`	`encodeIKP(List<String> mountId)`
`static ConfEObject`	`encodeIKP(List<String> mountId, ConfXMLParam[] params)`
`boolean`	`equals(Object o)` Determine if two Conf objects are equal.
`ConfNamespace`	`getConfNamespace()` Returns the namespace for this parameter.
`Integer`	`getNSHash()` Returns the namespce hash for this parameter.
`String`	`getTag()` Returns the tag for this parameter.
`Integer`	`getTagHash()` Returns the hash tag for this parameter.
`ConfObject`	`getValue()` Returns the value for this parameter.
`int`	`hashCode()`
`static Document`	`toDOM(ConfXMLParam[] params)` Return String `DOM` document representation of a (Conf)XML-structure.
`static Document`	`toDOM(ConfXMLParam[] params, String parentNode, String parentURI)` Return String `DOM` representation of a (Conf)XML-structure.
`String`	`toString()`
`static String`	`toXML(ConfXMLParam[] params)` Return String XML representation of a (Conf)XML-structure.
`static String`	`toXML(ConfXMLParam[] params, String parentNode, String parentURI)` Return String XML representation of a (Conf)XML-structure.
`static ConfXMLParam[]`	`toXMLParams(String xml, ConfPath path)` Converts an xml snippet to a corresponding ConfXMLParam[].
`static ConfXMLParam[]`	`toXMLParams(String xml, ConfPath path, int mode)` Converts an xml snippet to a corresponding ConfXMLParam[].

Methods inherited from class com.tailf.conf.ConfObject
clone, decode

Methods inherited from class Object
getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - 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

Class ConfXMLParam

Field Summary

Fields inherited from class com.tailf.conf.ConfObject

Method Summary

Methods inherited from class com.tailf.conf.ConfObject

Methods inherited from class Object

Method Detail

getTagHash

getNSHash

getTag

getConfNamespace

getValue

decodeParam

equals

hashCode

toXML

toXML

toDOM

toDOM

toXMLParams

toXMLParams

toString

encode

encode

encode

encode

encodeIKP

encodeIKP

encodeHKP

encodeHKP

encodeIKP

encodeIKP

encodeHKP

encodeHKP

decodeParams