Summary

Fields and methods of the XmlMap class.

//
// Copyright (c) 2006 Tobi Schäfer
// Alle Rechte vorbehalten. All rights reserved.
//
// $Revision: 446 $
// $LastChangedBy: tobi $
// $LastChangedDate: 2007-02-15 20:59:15 +0100 (Thu, 15 Feb 2007) $
// $HeadURL: http://p3k.org/source/rabbit/trunk/docs/overview-summary-XmlMap_XmlMap.js.html $
//

/**
 * @fileoverview Fields and methods of the XmlMap class.
 */

// Resolve dependencies
app.addRepository("modules/core/Object.js");
app.addRepository("modules/core/String.js");

/**
 * Returns the value of a property of the XmlMap instance.
 * @param {String} key The name of the desired property
 * @returns The resulting value
 */
XmlMap.prototype.get = function(key) {
   return this.getAll()[key];
};

/**
 * Returns the cached property map of the XmlMap instance.
 * Checks if the cache is still up-to-date and
 * (re)creates it if necessary.
 * @returns The cached map of the XmlMap instance
 * @type HopObject
 */
XmlMap.prototype.getAll = function() {
   if (this.cache.map == null) {
      var xml;
      var ref = this.getXmlRef();
      // Cache is either outdated or not existing, so (re)create it
      if (xml = this._parent[ref]) { // && this._parent[ref].trim() != "") {
         this.cache.xml = xml;
         this.cache.map = Xml.readFromString(xml);
      } else {
         this.cache.xml = "";
         this.cache.map = new HopObject();
      }
   }
   return this.cache.map;
};

/**
 * Sets a property of the cache object and updates the XML content
 * at the parent object.
 * @param {String} key The name of the desired property
 * @param {Object} value The future value of the property
 */
XmlMap.prototype.set = function(key, value) {
   if (key) {
      this.getAll();
      this.cache.map[key] = value;
      this._parent[this.getXmlRef()] = Xml.writeToString(this.cache.map);
   }
   return;
};

/**
 * Replaces the whole XML-encoded content.
 * @param {HopObject} obj The underlying HopObject
 * @returns False in case an error occured, false otherwise
 * @type Boolean
 */
XmlMap.prototype.setAll = function(obj) {
   if (!obj) {
      return false;
   }
   if (obj instanceof HopObject == false) {
      obj = obj.clone(new HopObject());
   }
   this._parent[this.getXmlRef()] = Xml.writeToString(obj);
   this.cache.map = obj;
   return true;
};

/**
 * Removes a property from the cache object and updates the XML content
 * at the parent object.
 * @param {String} key The name of the desired property
 */
XmlMap.prototype.remove = function(key) {
   var cache = this.getAll();
   cache[key] = null;
   delete cache[key];
   this._parent[this.getXmlRef()] = Xml.writeToString(cache);
   return;
};

/**
 * Removes all properties and values from the
 * XmlMap instance.
 */
XmlMap.prototype.removeAll = function() {
   delete this.cache.map;
   delete this.cache.xml;
   return;
};

/**
 * Gets the name of the property that holds the XML content
 * for this object. The name is constructed out of
 * the object's mountpoint and the suffix "_xml".
 * @returns The resulting value
 * @type String
 */
XmlMap.prototype.getXmlRef = function() {
   return this.__name__ + "_xml";
};

/**
 * Get all valid keys of the XmlMap instance.
 * @returns The list of valid keys
 * @type Array
 */
XmlMap.prototype.keys = function() {
   var cache = this.getAll();
   var arr = new Array();
   for (var i in cache) {
      arr[arr.length] = i;
   }
   return arr;
};

/**
 * Gets the amount of elements contained by
 * the XmlMap instance.
 * @returns The size of the XmlMap instance.
 * @type Number
 */
XmlMap.prototype.size = function() {
   return this.keys().length;   
};

/**
 * Gets the raw, XML-encoded content.
 * @returns The XML content
 * @type String
 */
XmlMap.prototype.valueOf = function() {
   this.getAll();
   return this.cache.xml;
};

/**
 * Returns a string representation of the XmlMap instance.
 * @returns A string representing the XmlMap object
 * @type String
 */
XmlMap.prototype.toString = function() {
   res.push();
   var keys = this.keys();
   res.write("[XmlMap (");
   if (keys.length < 1) {
      res.write("empty");
   } else {
      res.write(keys.length);
      res.write(" element");
      if (keys.length > 1) {
         res.write("s");
      }
   }
   res.write(")]");
   return res.pop();
};

/**
 * Returns the source of the underlying HopObject 
 * of the XmlMap instance.
 * Useful for debugging purposes.
 * @returns The source of the underlying HopObject.
 * @type String
 */
XmlMap.prototype.toSource = function() {
   return this.getAll().toSource();
};