XML2Object

Kind of class:	class
Inherits from:	XML
Author:	Arthur Clemens, Alessandro Crugnola
Classpath:	org.asapframework.util.xml.XML2Object
File last modified:	Thursday, 12 October 2006, 11:19:40

► View source

▼ Hide source

/*
Copyright 2005-2006 by the authors of asapframework, http://asapframework.org

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/


/**
Returns a value object from an XML instance, that can be queried using dot syntax.
If a node has more than 1 child with the same name, an array is created with the children contents
The object created will have this structure:
<code>
obj {
nodeName :
    attributes : an object containing the node attributes
    data : an object containing the node contents
}
</code>
@author Arthur Clemens, Alessandro Crugnola
@use With the following xml file:
<code>
<?xml version="1.0" encoding="utf-8" ?>
<days>
    <subscription num="3">8-8-2004</subscription>
</days>
</code>
<code>
var xmlData:Object = XML2Object.parseXML( anXML );
var subscriptionText = xmlData.days.subscription.data;
// returns 8-8-2004
var num = xmlData.days.subscription.attributes.num;
// returns the string '3'
</code>

When you pass true as convertNumbers argument, the string will be converted to number:
<code>
var xmlData:Object = XML2Object.parseXML( anXML, true );
var num = xmlData.days.subscription.attributes.num;
// returns the number 3
</code>

Multiple child nodes of the same parent with the same name will be put into an array. However, there is no way of knowing at parse time whether a single node was meant to be an array. For that purpose, the function makeArray() can be used. 
@example
XML:
<code>
<L1>
    <L2>item 1</L2>
    <L2>item 2</L2>
</L1>
<L3>
    <L4>item 3</L4>
<L3>
</code>
After parsing, {@code L1.L2} will be an array with two items. {@code L3.L4} will be a single Object. With {@code XML2Object.makeArray(L3.L4)} {@code L3.L4} becomes a single item array.
*/

class org.asapframework.util.xml.XML2Object extends XML {
    private static var oResult:Object = new Object ();
    private static var oXML:XML;

    /**
    The xml passed in the parseXML method.
    */
    public static function get xml () : XML {
        return oXML;
    }

    /**
    Creates an value object from an XML instance.
    @param xmlData XML instance to parse
    @param convertNumbers Set to true to automatically convert number strings to numbers (all text in xml is treated as text otherwise)
    @returns an Object with the contents of the passed XML
    @use <code>XML2Object.parseXML( theXMLtoParse );</code>
    */
    public static function parseXML (inXmlData:XML, convertNumbers:Boolean) : Object

    {
        XML2Object.oResult = new Object ();
        XML2Object.oXML = inXmlData;
        XML2Object.oResult = XML2Object.translateXML(convertNumbers);
        return XML2Object.oResult;
    }

    /**
    Core translation engine.
    */
    private static function translateXML (convertNumbers, from, path, name, position) : Object {
        var nodes, node, old_path, a;
        if (path == undefined) {
            path = XML2Object;
            name = "oResult";
        }
        path = path[name];
        if (from == undefined) {
            from = new XML (XML2Object.xml.toString());
            from.ignoreWhite = true;
        }
        if (from.hasChildNodes ()) {
            nodes = from.childNodes;
            if (position != undefined) {
                old_path = path;
                path = path[position];
            }
            while (nodes.length > 0) {
                node = nodes.shift ();
                if (node.nodeName != undefined) {
                    var __obj__ = new Object ();
                    if (convertNumbers) {
                        for (a in node.attributes) {
                            if(__obj__.attributes == undefined) {
                                __obj__.attributes = new Object();
                            }
                            var att = node.attributes[a];
                            __obj__.attributes[a] = isNaN(Number(att)) ? att : Number(att);
                        }
                    } else {
                        __obj__.attributes = node.attributes;
                    }
                    var d = node.firstChild.nodeValue;
                    if( convertNumbers) {
                        // just take the value and find possible number
                        __obj__.data = isNaN(Number(d)) ? d : Number (d);
                    } else {
                        __obj__.data = d;
                    }
                    if (position != undefined) {
                        old_path = path;
                    }
                    if (path[node.nodeName] != undefined) {
                        if (path[node.nodeName] instanceof Array) {
                            path[node.nodeName].push (__obj__);
                            name = node.nodeName;
                            position = path[node.nodeName].length - 1;
                        } else {
                            var copyObj = path[node.nodeName];
                            path[node.nodeName] = new Array ();
                            path[node.nodeName].push (copyObj);
                            path[node.nodeName].push (__obj__);
                            name = node.nodeName;
                            position = path[node.nodeName].length - 1;
                        }
                    } else {
                        path[node.nodeName] = __obj__;
                        name = node.nodeName;
                        position = undefined;
                    }
                }
                if (node.hasChildNodes ()) {
                    XML2Object.translateXML (convertNumbers, node, path, name, position);
                }
            }
        }
        return XML2Object.oResult;
    }

    /**
    Check whether the input item is an array, if not, make an array with the input item as single value.
    @param inObj:Object
    @return Array
    */
    public static function makeArray (inObj) : Array {
        if (inObj != undefined) {
            return (inObj instanceof Array) ? inObj : [inObj];
        } else {
            return new Array();
        }
    }
}

Returns a value object from an XML instance, that can be queried using dot syntax.
If a node has more than 1 child with the same name, an array is created with the children contents
The object created will have this structure:

obj {
nodeName :
    attributes : an object containing the node attributes
    data : an object containing the node contents
}

Usage:

With the following xml file:

<?xml version="1.0" encoding="utf-8" ?>
<days>
    <subscription num="3">8-8-2004</subscription>
</days>

var xmlData:Object = XML2Object.parseXML( anXML );
var subscriptionText = xmlData.days.subscription.data;
// returns 8-8-2004
var num = xmlData.days.subscription.attributes.num;
// returns the string '3'

When you pass true as convertNumbers argument, the string will be converted to number:

var xmlData:Object = XML2Object.parseXML( anXML, true );
var num = xmlData.days.subscription.attributes.num;
// returns the number 3

Multiple child nodes of the same parent with the same name will be put into an array. However, there is no way of knowing at parse time whether a single node was meant to be an array. For that purpose, the function makeArray() can be used.

Example:

XML:
```
<L1>
    <L2>item 1</L2>
    <L2>item 2</L2>
</L1>
<L3>
    <L4>item 3</L4>
<L3>
```
After parsing, L1.L2 will be an array with two items. L3.L4 will be a single Object. With XML2Object.makeArray(L3.L4) L3.L4 becomes a single item array.

Summary

Class properties

oResult : Object
oXML : XML
xml : XML
- The xml passed in the parseXML method.

Class methods

parseXML (inXmlData:XML, convertNumbers:Boolean) : Object
- Creates an value object from an XML instance.
translateXML (convertNumbers, from, path, name, position) : Object
- Core translation engine.
makeArray (inObj) : Array
- Check whether the input item is an array, if not, make an array with the input item as single value.

Class properties

oResult

static private oResult:Object = new Object ()

(read)

oXML

static private oXML:XML

(read)

xml

static xml:XML

(read)

The xml passed in the parseXML method.

Class methods

makeArray

static function makeArray (

inObj) : Array

Check whether the input item is an array, if not, make an array with the input item as single value.

Parameters:

inObj:

Object

Returns:

Array

parseXML

static function parseXML (

inXmlData:XML, convertNumbers:Boolean) : Object

Creates an value object from an XML instance.

Parameters:

xmlData :

XML instance to parse

convertNumbers:

Set to true to automatically convert number strings to numbers (all text in xml is treated as text otherwise)

Returns:

an Object with the contents of the passed XML

Usage:

XML2Object.parseXML( theXMLtoParse );

translateXML

static private function translateXML (

convertNumbers, from, path, name, position) : Object

Core translation engine.