/*
 * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
 * Copyright (C) 2005 - Javolution (http://javolution.org/)
 * All rights reserved.
 * 
 * Permission to use, copy, modify, and distribute this software is
 * freely granted, provided that this notice is preserved.
 */
package javolution37.javolution.xml;

import java.io.IOException;

import java.lang.CharSequence;
import java.lang.IllegalStateException;
import java.util.Collection;
import java.util.Iterator;
import java.util.Map;
import javax.realtime.MemoryArea;

import java.lang.Appendable;

import javolution37.javolution.lang.ClassInitializer;
import javolution37.javolution.lang.Reflection;
import javolution37.javolution.lang.Text;
import javolution37.javolution.lang.TypeFormat;
import javolution37.javolution.util.FastCollection;
import javolution37.javolution.util.FastComparator;
import javolution37.javolution.util.FastMap;
import javolution37.javolution.util.FastTable;
import javolution37.javolution.util.LocalMap;

/**
 * 
 This class represents the format base class for XML serialization and
 *     deserialization.
 *     
 * 
 Application classes typically define a XML format for their instances 
 *     using static {@link XmlFormat} class members. 
 *     The format is inherited by sub-classes. For example:[code]
 *     public abstract class Graphic {
 *         private boolean _isVisible;
 *         private Paint _paint; // null if none.
 *         private Stroke _stroke; // null if none.
 *         private Transform _transform; // null if none.
 *          
 *         // XML format with positional associations (members identified by their position),
 *         // see xml package description for examples of name associations.
 *         protected static final XmlFormat GRAPHIC_XML = new XmlFormat(Graphic.class) {
 *              public void format(Graphic g, XmlElement xml) {
 *                  xml.setAttribute("isVisible", g._isVisible); 
 *                  xml.add(g._paint); // First.
 *                  xml.add(g._stroke); // Second.
 *                  xml.add(g._transform); // Third.
 *              }
 *              public Graphic parse(XmlElement xml) {
 *                  Graphic g = xml.object();
 *                  g._isVisible = xml.getAttribute("isVisible", true);
 *                  g._paint = xml.getNext();
 *                  g._stroke = xml.getNext();
 *                  g._transform = xml.getNext();
 *                  return g;
 *             }
 *         };
 *    }[/code]
 *    
 * 
 Due to the sequential nature of xml serialization/deserialization, 
 *     formatting/parsing of xml attributes should always be performed before 
 *     formatting/parsing of the xml content.
 * 
 * 
 Xml formats can dynamically associated. For example:[code]
 * 
 *     // XML Conversion (different formats for reading and writing).
 *     XmlFormat readFormat = new XmlFormat() {...};
 *     XmlFormat writeFormat = new XmlFormat() {...};
 *     LocalContext.enter();
 *     try {  // Local context to avoid impacting other threads.
 *        XmlFormat.setFormat(Foo.class, readFormat);
 *        Foo foo = new ObjectReader().read(in);
 *        XmlFormat.setFormat(Foo.class, writeFormat);
 *        new ObjectWriter().write(foo, out);
 *     } finally {
 *        LocalContext.exit();
 *     }
 *     
 *     // Temporary change of String format during formatting.
 *     public void format(List list, XmlElement xml) {
 *         LocalContext.enter();
 *         try {  // Always safer to scope the change.
 *             XmlFormat.setFormat(String.class, MY_STRING_FORMAT);
 *             for (Object elem : list)  {
 *                 xml.add(elem);
 *             }
 *        } finally {
 *            LocalContext.exit(); 
 *        }      
 *     }[/code]
 *     
 * 
 A default format is defined for null values 
 *     (<null/>) and the following types:

 *        
java.lang.Object (default)
 *        
java.lang.Class
 *        
java.lang.String
 *        
javolution.lang.Text
 *        
java.lang.Appendable
 *        
java.util.Collection
 *        
java.util.Map
 *        
and all primitive types wrappers (e.g. 
 *            Boolean, Integer ...)
 *        

 *        
 * 
Here is an example of serialization/deserialization using predefined 
 *    formats:[code]
 *     List list = new ArrayList();
 *     list.add("John Doe");
 *     list.add(null);
 *     Map map = new FastMap();
 *     map.put("ONE", new Integer(1));
 *     map.put("TWO", new Integer(2));
 *     list.add(map);
 *     ObjectWriter ow = new ObjectWriter();
 *     ow.write(list, new FileOutputStream("C:/list.xml"));[/code]
 *     Here is the output list.xml document produced:[code]
 *     
 *         
 *         
 *         
 *             
 *             
 *             
 *             
 *         [/code]
 *     The list can be read back with the following code:[code]
 *     ObjectReader or = new ObjectReader();
 *     List list = (List) or.read(new FileInputStream("C:/list.xml"));
 *     [/code]
 *     
 * 
 Finally, xml formats can be made impervious to obfuscation by 
 *     setting local {@link #setAlias aliases} for the obfuscated classes.
 * 
 * @author  Jean-Marie Dautelle
 * @version 3.6, October 13, 2005
 */
public abstract class XmlFormat {

    private static final FastMap CLASS_TRANSFORMATIONS = new FastMap()
            .setShared(true);

    /**
     * Holds the default formats.
     */
    private static final FastMap DEFAULT_INSTANCES = new FastMap()
            .setShared(true);

    /**
     * Holds the dynamic class-to-format override.
     */
    private static final LocalMap DYNAMIC_INSTANCES = new LocalMap();

    /**
     * Holds the local look-up.
     */
    private static final LocalMap CLASS_TO_FORMAT = new LocalMap();

    /**
     * Holds the class-to-alias mapping.
     */
    private static final LocalMap CLASS_TO_ALIAS = new LocalMap();

    /**
     * Holds the class-name to class mapping.
     */
    private static FastMap CLASS_NAME_TO_CLASS = new FastMap().setShared(true);

    /**
     * Holds the local-name/uri to class mapping (localName to uri/class pairs).
     */
    private static FastMap LOCAL_NAME_TO_URI_CLASS = new FastMap()
            .setShared(true);

    /**
     * Holds the alias-to-class mapping.
     */
    private static final LocalMap ALIAS_TO_CLASS = new LocalMap();

    /**
     * Holds the default XML representation when a more specific format 
     * cannot be found. This representation consists of an empty XML element
     * with no attribute. Objects are deserialized using the class public
     * no-arg constructor (the class being identified by the element's name).
     */
    public static final XmlFormat