[asap-cvs] SF.net SVN: asapframework: [585] trunk/asapframework/org/asapframework/data /loader/Parser.as

[<aci...@us...>]

Revision: 585
          http://svn.sourceforge.net/asapframework/?rev=585&view=rev
Author:   acidcats
Date:     2006-10-10 02:01:43 -0700 (Tue, 10 Oct 2006)

Log Message:
-----------
Documentation update

Modified Paths:
--------------
    trunk/asapframework/org/asapframework/data/loader/Parser.as

Modified: trunk/asapframework/org/asapframework/data/loader/Parser.as
===================================================================
--- trunk/asapframework/org/asapframework/data/loader/Parser.as	2006-10-10 06:03:19 UTC (rev 584)
+++ trunk/asapframework/org/asapframework/data/loader/Parser.as	2006-10-10 09:01:43 UTC (rev 585)
@@ -24,22 +24,57 @@
 When the XML structure is changed, only the parsing function in the DataValueObject class has to be changed, thereby facilitating maintenance and development.
 
 @use
+Consider an XML file with the following content:
+<code>
+<?xml version="1.0" encoding="UTF-8"?>
+	<settings>
+		<urls>
+			<url name="addressform" url="../xml/address.xml" />
+			<url name="entries" url="../xml/entries.xml" />
+		</urls>
+	</settings>
+</code>
+See the {@link DataLoader} for an example of how to load this XML and get it as an Object. Once the XML has been loaded and parsed into an Object, it can be converted into an Array of URLData objects with the following code:
+<code>
+	// objects of type URLData
+	private var mURLs:Array;
+	
+	// parse an Object containing converted XML
+	// @param o: Object from DataLoader or XML2Object
+	// @return true if parsing went ok, otherwise false
+	private function handleSettingsLoaded (o:Object) : Boolean {
+		mURLs = Parser.parseList(o.settings.urls.url, org.asapframework.data.loader.URLData, false);
+		
+		return (mURLs != null);
+	}
+</code>
+After calling this function, the member variable <code>mURLs</code> contains a list of objects of type URLData, filled with the content of the XML file.
 
+Notes to this code:
+<ul>
+<li>The first parameter to {@link parseList} is a (can be a) repeating node where each node contains similar data to be parsed into </li>
+<li>Conversion of nodes to an Array is not necessary. If the <urls>-node in the aforementioned XML file would contain only one <url>-node, the parser still returns an Array, with one object of type URLData.</li>
+<li>Since the last parameter to the call to {@link #parseList} is false, an error in the xml data will result in mURLs being null. The parsing class determines when this is the case.</li>
+</ul> 
 */
  
 class org.asapframework.data.loader.Parser {
 	/**
-	*	
+	*	Parse an array of objects from XML into an array of the specified class instance by calling its parseObject function
+	*	@param inObject: object from XML2Object (usually), will be converted to an Array if it isn't already
+	*	@param f: classname to be instanced
+	*	@param ignoreError: if true, the return value of {@link #parseObject} is always added to the array, and the array itself is returned. Otherwise, an error in parsing will return null.
+	*	@return Array of new objects of the specified type, cast to IParsable, or null if parsing returned false
 	*/
-	public static function parseList (inListObj:Object, f:Function) : Array {
+	public static function parseList (inListObj:Object, f:Function, ignoreError:Boolean) : Array {
 		var list:Array = XML2Object.makeArray(inListObj);
 		 
 		var a:Array = new Array();
 		
 		var len:Number = list.length;
 		for (var i : Number = 0; i < len; i++) {
-			var newObject:IParsable = parseObject(list[i], f);
-			if (newObject == null) return null;
+			var newObject:IParsable = parseObject(list[i], f, ignoreError);
+			if ((newObject == null) && !ignoreError) return null;
 			else a.push(newObject);
 		}
 		
@@ -50,11 +85,12 @@
 	*	Parse an object from XML into the specified class instance by calling its parseObject function
 	*	@param inObject: object from XML2Object (usually)
 	*	@param f: classname to be instanced
+	*	@param ignoreError: if true, the return value of {@link IParsable#parseObject} is ignored, and the newly created object is always returned.
 	*	@return a new object of the specified type, cast to IParsable, or null if parsing returned false
 	*/
-	public static function parseObject (inObject:Object, f:Function) : IParsable {
+	public static function parseObject (inObject:Object, f:Function, ignoreError:Boolean) : IParsable {
 		var ip:IParsable = new f();
-		if (ip.parseObject(inObject)) {
+		if (ip.parseObject(inObject) || ignoreError) {
 			return ip;
 		} else {
 			return null;


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.