/*
 *    Geotoolkit - An Open Source Java GIS Toolkit
 *    http://www.geotoolkit.org
 *
 *    (C) 2010, Geomatys
 *
 *    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.1 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.
 */
package org.geotoolkit.data.kml.xml;

import javax.xml.stream.XMLStreamException;
import org.geotoolkit.data.kml.model.Extensions;
import org.geotoolkit.data.kml.model.KmlException;
import org.geotoolkit.data.kml.xsd.SimpleTypeContainer;

/**
 * Provides methods an StaxStreamWriter needs to implement
 * to be added as an extension writer to Kml main writer with method
 * {@code addExtensionWriter()}.
 *
 * <p>Here is an example of use:</p>
 *
 * <pre>
 * final Kml kml = kmlFactory.createKml(null, folder, null, null);
 *
 * <div style="background-color: #cccccc; color: red;">
 * kml.addExtensionUri(GxConstants.URI_GX, "gx");
 * </div>
 *
 * final File temp = File.createTempFile("testMultiTrack", ".kml");
 * temp.deleteOnExit();
 * <div style="background-color: #cccccc; color: red;">
 * final KmlWriter writer = new KmlWriter();
 * final GxWriter gxWriter = new GxWriter(writer);
 * writer.setOutput(temp);
 * writer.addExtensionWriter(GxConstants.URI_GX, gxWriter);
 * </div>
 * writer.write(kml);
 * writer.dispose();
 * </pre>
 *
 * <p>For a given extension writer, writting an extension tag could depend on
 * Kml version, extension level and nature of extension object itself.</p>
 *
 * <p>For example, extension level is the difference between BasicLink extensions
 * or Link extensions that are both concluded in an Link. For extension writer,
 * tag choice for one element of these extensions coud depends of its level.</p>
 *
 * <p>Nature of an extension is more complex than its class. Class has
 * no significance for simple extensions. Because of this lack of semantics,
 * simple data are included in SimpleType container. Nature of such simple extensions
 * is indicated by uri/tag availables in simple type container.</p>
 *
 * <p>Even in the case of complex extensions, objects class is not sufficient
 * because of numerous feature types. Only the object himself contains all
 * information about his nature.</p>
 *
 * @author Samuel Andrés
 * @module
 */
public interface KmlExtensionWriter {
    /**
     * Indicates if KmlExtentionWriter can write given element contained in given extension.
     */
    boolean canHandleComplex(String kmlVersionUri, Extensions.Names ext, Object contentObject);

    /**
     * Indicates if KmlExtentionWriter can write given element contained in given extension.
     */
    boolean canHandleSimple(String kmlVersionUri, Extensions.Names ext, String elementTag);

    /**
     * Writes a complex extension element.
     */
    void writeComplexExtensionElement(String kmlVersionUri, Extensions.Names ext, Object contentElement)
            throws XMLStreamException, KmlException;

    /**
     * Writes a simple extension element.
     */
    void writeSimpleExtensionElement(String kmlVersionUri, Extensions.Names ext, SimpleTypeContainer contentElement)
            throws XMLStreamException, KmlException;
}