package org.mandarax.xkb.framework;

/**
 *  Copyright (C) 1999-2004  Jens Dietrich (mailto:mandarax@jbdietrich.com)
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

import java.util.Map;

import org.jdom.Element;
import org.mandarax.kernel.LogicFactory;
import org.mandarax.xkb.XKBException;
/**
 * Abstract adapter class supporting caching. I.e., elements get an ID attribute with
 * a unique object id value. When two elements with the same id are imported, the same
 * object is returned. We have some utility methods here to support this behaviour.
 * <p>
 * <strong>Warning:</strong> We use a map for caching. Implementations such as <code>HashMap</code>
 * identify keys using <code>equal()</code>, but there might be alternative implementations
 * using == (like the Smalltalk class IdentityDictionary). Therefore the effects of using
 * a cache depend on the implementation of map choosen!
 * @see java.util.Map
 * @author <A HREF="mailto:mandarax@jbdietrich.com">Jens Dietrich</A>
 * @version 3.3.1 <9 August 2004>
 * @since 1.6
 */
public abstract class CachedXMLAdapter extends AbstractXMLAdapter{
      public static final String ID = "id";
/**
 * Get the next object id.
 * @return a unique id
 */
protected String nextId(){
      return UIDGenerator.nextId().toString();
};
/**
 * Export the object, check first whether an element is aleady in the cache.
 * @param obj an object
 * @param driver the generic driver
 * @param cache a cache used in order to associate the same
 * id with various occurences of the same object
 * @exception an XKBException is thrown if export fails
 */
public Element exportObject(Object obj,GenericDriver driver,Map cache) throws  XKBException {
      Element e = (Element)cache.get(obj);
      if (e==null) {
            e = _exportObject(obj,driver,cache);
            e.setAttribute(ID,nextId());
            cache.put(obj,e);
      }
      return (Element)e.clone();
}
/**
 * Build an object from an XML element. First we check whether an object for the respective id
 * is already in the cache.
 * @param e an element
 * @param driver the generic driver
 * @param cache a cache used to identify objects that have the same id
 * @param lfactory the logic factory used to create objects
 * @exception an XKBException is thrown if export fails
 */
public Object importObject(Element e,GenericDriver driver,Map cache,LogicFactory lfactory) throws XKBException {
      String id = e.getAttributeValue(ID);
      Object cachedObj = cache.get(id);
      if (cachedObj==null) {
            cachedObj = _importObject(e,driver,cache,lfactory);
            cache.put(id,cachedObj);
      }
      return cachedObj;
}
/**
 * Export the object. Subclasses must implement this method and must not care about caching.
 * @param obj an object
 * @param driver the generic driver
 * @param cache a cache used in order to associate the same
 * id with various occurences of the same object
 * @exception an XKBException is thrown if export fails
 */
protected abstract Element _exportObject(Object obj,GenericDriver driver,Map cache) throws  XKBException;
/**
 * Build an object from an XML element. Subclasses must implement this method and must not care about caching.
 * @param e an element
 * @param driver the generic driver
 * @param cache a cache used to identify objects that have the same id
 * @param lfactory the logic factory used to create objects
 * @exception an XKBException is thrown if export fails
 */
protected abstract Object _importObject(Element e,GenericDriver driver,Map cache,LogicFactory lfactory) throws XKBException;

}
