Application: gvSIG desktop » gvSIG data provider for GPE

<?xml version="1.0" encoding="ISO-8859-1"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

	<modelVersion>4.0.0</modelVersion>

	<artifactId>org.gvsig.xmlpull.lib</artifactId>

	<packaging>pom</packaging>	

	<name>org.gvsig.xmlpull.lib</name>

	<description>XML Pull library</description>

	<parent>

		<groupId>org.gvsig</groupId>

		<artifactId>org.gvsig.xmlpull</artifactId>	

		<version>2.0.14</version>	

	</parent>

	<modules>

		<module>org.gvsig.xmlpull.lib.api</module>

		<module>org.gvsig.xmlpull.lib.spi</module>

		<module>org.gvsig.xmlpull.lib.impl</module>

	</modules>

</project>

<?xml version="1.0" encoding="ISO-8859-1"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

	<modelVersion>4.0.0</modelVersion>

	<artifactId>org.gvsig.xmlpull.lib.api</artifactId>

	<packaging>jar</packaging>

	<name>org.gvsig.xmlpull.lib.api</name>

	<description>XML Pull library API</description>

	<parent>

		<groupId>org.gvsig</groupId>

		<artifactId>org.gvsig.xmlpull.lib</artifactId>

		<version>2.0.14</version>		

	</parent>

	<dependencies>

		<dependency>

      		<groupId>org.gvsig</groupId>

      		<artifactId>org.gvsig.tools.lib</artifactId>

    	</dependency>

    	<dependency>

      		<groupId>org.gvsig</groupId>

      		<artifactId>org.gvsig.tools.lib</artifactId>

      		<type>test-jar</type>

    	</dependency>  

	</dependencies>

	<build>

		<plugins>

			<plugin>

				<groupId>org.apache.maven.plugins</groupId>

				<artifactId>maven-compiler-plugin</artifactId>

				<configuration>

					<source>1.4</source>

					<target>1.5</target>

				</configuration>

			</plugin>

		</plugins>

	</build>

	<profiles>

		<profile>

			<id>cdc</id>

			<build>

				<plugins>

					<plugin>

						<groupId>org.apache.maven.plugins</groupId>

						<artifactId>maven-compiler-plugin</artifactId>

						<configuration>

							<source>1.4</source>

							<target>1.4</target>

						</configuration>

					</plugin>

				</plugins>

			</build>

		</profile>

	</profiles>

</project>

/* gvSIG. Geographic Information System of the Valencian Government

*

* Copyright (C) 2007-2008 Infrastructures and Transports Department

* of the Valencian Government (CIT)

* 

* This program is free software; you can redistribute it and/or

* modify it under the terms of the GNU General Public License

* as published by the Free Software Foundation; either version 2

* of the License, or (at your option) any later version.

* 

* This program 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 General Public License for more details.

* 

* You should have received a copy of the GNU General Public License

* along with this program; if not, write to the Free Software

* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 

* MA  02110-1301, USA.

* 

*/

/*

* AUTHORS (In addition to CIT):

* 2010 {Iver T.I.}   {Task}

*/

package org.gvsig.xmlpull.lib.api;

import org.gvsig.tools.locator.AbstractLocator;

import org.gvsig.tools.locator.Locator;

import org.gvsig.tools.locator.LocatorException;

/**

 * @author <a href="mailto:jpiera@gvsig.org">Jorge Piera</a>

 */

public class XmlPullLocator extends AbstractLocator {

	private static final String LOCATOR_NAME = "XMLLocator";

	/**

	 * XMLManager name used by the locator to access the instance

	 */

	public static final String XML_MANAGER_NAME = "XMLManager";

	private static final String XML_MANAGER_DESCRIPTION = "XMLManager of gvSIG";

	/**

	 * Unique instance.

	 */

	private static final XmlPullLocator instance = new XmlPullLocator();

	/* (non-Javadoc)

	 * @see org.gvsig.tools.locator.Locator#getLocatorName()

	 */

	public String getLocatorName() {

		return LOCATOR_NAME;

	}

	/**

	 * Return a reference to {@link XmlPullManager}.

	 *

	 * @return a reference to XMLManager

	 * @throws LocatorException

	 *             if there is no access to the class or the class cannot be

	 *             instantiated

	 * @see Locator#get(String)

	 */

	public static XmlPullManager getXMLManager() throws LocatorException {

		return (XmlPullManager) getInstance().get(XML_MANAGER_NAME);

	}

	/**

	 * Return the singleton instance.

	 *

	 * @return the singleton instance

	 */

	public static XmlPullLocator getInstance() {

		return instance;

	}

	/**

	 * Registers the Class implementing the {@link XmlPullManager} interface.

	 *

	 * @param clazz

	 *            implementing the XMLManager interface

	 */

	public static void registerXMLManager(Class clazz) {

		getInstance().register(XML_MANAGER_NAME, 

				XML_MANAGER_DESCRIPTION,

				clazz);

	}	

}

/* gvSIG. Geographic Information System of the Valencian Government

*

* Copyright (C) 2007-2008 Infrastructures and Transports Department

* of the Valencian Government (CIT)

* 

* This program is free software; you can redistribute it and/or

* modify it under the terms of the GNU General Public License

* as published by the Free Software Foundation; either version 2

* of the License, or (at your option) any later version.

* 

* This program 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 General Public License for more details.

* 

* You should have received a copy of the GNU General Public License

* along with this program; if not, write to the Free Software

* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 

* MA  02110-1301, USA.

* 

*/

/*

* AUTHORS (In addition to CIT):

* 2010 {Iver T.I.}   {Task}

*/

package org.gvsig.xmlpull.lib.api;

import org.gvsig.tools.library.AbstractLibrary;

import org.gvsig.tools.library.LibraryException;

/**

 * @author <a href="mailto:jpiera@gvsig.org">Jorge Piera</a>

 */

public class XmlPullLibrary extends AbstractLibrary  {

	public void doRegistration() {

		registerAsAPI(XmlPullLibrary.class);

	}

	protected void doInitialize() throws LibraryException {

		// Nothing to do 

	}

	protected void doPostInitialize() throws LibraryException {

		// Nothing to do		

	}

}

/* gvSIG. Geographic Information System of the Valencian Government

*

* Copyright (C) 2007-2008 Infrastructures and Transports Department

* of the Valencian Government (CIT)

* 

* This program is free software; you can redistribute it and/or

* modify it under the terms of the GNU General Public License

* as published by the Free Software Foundation; either version 2

* of the License, or (at your option) any later version.

* 

* This program 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 General Public License for more details.

* 

* You should have received a copy of the GNU General Public License

* along with this program; if not, write to the Free Software

* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 

* MA  02110-1301, USA.

* 

*/

/*

* AUTHORS (In addition to CIT):

* 2010 {Iver T.I.}   {Task}

*/

package org.gvsig.xmlpull.lib.api;

import java.io.InputStream;

import java.io.OutputStream;

import org.gvsig.xmlpull.lib.api.stream.IXmlStreamReader;

import org.gvsig.xmlpull.lib.api.stream.IXmlStreamWriter;

import org.gvsig.xmlpull.lib.api.stream.XmlStreamException;

/**

 * @author <a href="mailto:jpiera@gvsig.org">Jorge Piera</a>

 */

public interface XmlPullManager {

	public IXmlStreamReader createStreamReader(String mimeType, InputStream is) throws XmlStreamException, IllegalArgumentException;

	public IXmlStreamWriter createStreamWriter(String mimeType, OutputStream os) throws XmlStreamException, IllegalArgumentException;

}

package org.gvsig.xmlpull.lib.api.stream;

/* gvSIG. Sistema de Informaci?n Geogr?fica de la Generalitat Valenciana

 *

 * Copyright (C) 2004 IVER T.I. and Generalitat Valenciana.

 *

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of the GNU General Public License

 * as published by the Free Software Foundation; either version 2

 * of the License, or (at your option) any later version.

 *

 * This program 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 General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307,USA.

 *

 * For more information, contact:

 *

 *  Generalitat Valenciana

 *   Conselleria d'Infraestructures i Transport

 *   Av. Blasco Ib??ez, 50

 *   46010 VALENCIA

 *   SPAIN

 *

 *      +34 963862235

 *   gvsig@gva.es

 *      www.gvsig.gva.es

 *

 *    or

 *

 *   IVER T.I. S.A

 *   Salamanca 50

 *   46005 Valencia

 *   Spain

 *

 *   +34 963163400

 *   dac@iver.es

 */

/* CVS MESSAGES:

 *

 * $Id: IXmlStreamReader.java 19593 2008-03-12 17:23:30Z groldan $

 * $Log$

 */

/**

 * Represents an abstraction layer over a concrete XML parsing technology.

 * <p>

 * This interface provides a pull like approach to parsing xml formatted documents for the libGPE

 * library, yet allowing to interchange implementations which can be based, for example, in XML SAX,

 * XML Pull, Binary XML, etc.

 * </p>

 * <p>

 * Note at this time this interface contract is made just of the methods from XmlPullParser that

 * where already used so far in the libGPE-GML and libGPE-KML modules. The intention is to first

 * introduce this abstraction layer and then evolve it as needed to support an intermediate level of

 * abstraction between actual xml parsing and {@link IGPEContentHandler}, while keeping the unit

 * tests passing all the time. So this is work in progress and expected to change dramatically,

 * though ensuring no functional breackages in any time.

 * </p>

 * 

 * @author Gabriel Roldan (TOPP)

 * @version $Id: IXmlStreamReader.java 19593 2008-03-12 17:23:30Z groldan $

 */

public interface IXmlStreamReader {

    /**

     * Indicates an event is a start element

     */

    public static final int START_ELEMENT = 1;

    /**

     * Indicates an event is an end element

     */

    public static final int END_ELEMENT = 2;

    /**

     * Indicates an event is a processing instruction

     */

    public static final int PROCESSING_INSTRUCTION = 3;

    /**

     * Indicates an event is characters

     */

    public static final int CHARACTERS = 4;

    /**

     * Indicates an event is a comment

     */

    public static final int COMMENT = 5;

    /**

     * The characters are white space (see [XML], 2.10 "White Space Handling"). Events are only

     * reported as SPACE if they are ignorable white space. Otherwise they are reported as

     * CHARACTERS.

     */

    public static final int SPACE = 6;

    /**

     * Indicates an event is a start document

     */

    public static final int START_DOCUMENT = 7;

    /**

     * Indicates an event is an end document

     */

    public static final int END_DOCUMENT = 8;

    /**

     * Indicates an event is an entity reference

     */

    public static final int ENTITY_REFERENCE = 9;

    /**

     * Indicates an event is an attribute

     * 

     * @see javax.xml.stream.events.Attribute

     */

    //public static final int ATTRIBUTE = 10;

    /**

     * Indicates an event is a DTD

     */

    public static final int DTD = 11;

    /**

     * Indicates an event is a CDATA section

     */

    public static final int CDATA = 12;

    /**

     * Indicates the event is a namespace declaration

     */

    public static final int NAMESPACE = 13;

    /**

     * Indicates a Notation

     */

    public static final int NOTATION_DECLARATION = 14;

    /**

     * Indicates a Entity Declaration

     */

    public static final int ENTITY_DECLARATION = 15;

    /**

     * @return

     * @throws IllegalStateException

     */

    int getAttributeCount() throws XmlStreamException;

    IQName getAttributeName(int i) throws XmlStreamException;

    /**

     * Returns the complete (coalesced) value for the attribute at index {@code i}

     * @param i

     * @return

     * @throws XmlStreamException

     */

    String getAttributeValue(int i) throws XmlStreamException;

    /**

     * Returns the qualified name (with prefix if applicable) for the current element.

     * 

     * @return the qualified name for the current START_ELEMENT or END_ELEMENT event, or

     *         <code>null</code> if the current event is not a START_ELEMENT or END_ELEMENT.

     * @throws XmlStreamException

     */

    IQName getName() throws XmlStreamException;

    int getEventType() throws XmlStreamException;

    String getText() throws XmlStreamException;

    int next() throws XmlStreamException;

    int nextTag() throws XmlStreamException;

    boolean isWhitespace() throws XmlStreamException;

}

/* gvSIG. Geographic Information System of the Valencian Government

*

* Copyright (C) 2007-2008 Infrastructures and Transports Department

* of the Valencian Government (CIT)

* 

* This program is free software; you can redistribute it and/or

* modify it under the terms of the GNU General Public License

* as published by the Free Software Foundation; either version 2

* of the License, or (at your option) any later version.

* 

* This program 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 General Public License for more details.

* 

* You should have received a copy of the GNU General Public License

* along with this program; if not, write to the Free Software

* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 

* MA  02110-1301, USA.

* 

*/

/*

* AUTHORS (In addition to CIT):

* 2010 {Iver T.I.}   {Task}

*/

package org.gvsig.xmlpull.lib.api.stream;

/**

 * @author <a href="mailto:jpiera@gvsig.org">Jorge Piera</a>

 */

public interface IQName {

	public String getLocalPart();

	public String getNamespaceURI();

}

package org.gvsig.xmlpull.lib.api.stream;

import java.io.OutputStream;

/* gvSIG. Sistema de Informaci?n Geogr?fica de la Generalitat Valenciana

 *

 * Copyright (C) 2004 IVER T.I. and Generalitat Valenciana.

 *

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of the GNU General Public License

 * as published by the Free Software Foundation; either version 2

 * of the License, or (at your option) any later version.

 *

 * This program 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 General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307,USA.

 *

 * For more information, contact:

 *

 *  Generalitat Valenciana

 *   Conselleria d'Infraestructures i Transport

 *   Av. Blasco Ib??ez, 50

 *   46010 VALENCIA

 *   SPAIN

 *

 *      +34 963862235

 *   gvsig@gva.es

 *      www.gvsig.gva.es

 *

 *    or

 *

 *   IVER T.I. S.A

 *   Salamanca 50

 *   46005 Valencia

 *   Spain

 *

 *   +34 963163400

 *   dac@iver.es

 */

/**

 * 

 */

public interface IXmlStreamWriterFactory {

    boolean canWrite(final String mimeType);

    IXmlStreamWriter createWriter(final String mimeType, final OutputStream out)

            throws XmlStreamException, IllegalArgumentException;

}

package org.gvsig.xmlpull.lib.api.stream;

/* gvSIG. Sistema de Informaci?n Geogr?fica de la Generalitat Valenciana

 *

 * Copyright (C) 2004 IVER T.I. and Generalitat Valenciana.

 *

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of the GNU General Public License

 * as published by the Free Software Foundation; either version 2

 * of the License, or (at your option) any later version.

 *

 * This program 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 General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307,USA.

 *

 * For more information, contact:

 *

 *  Generalitat Valenciana

 *   Conselleria d'Infraestructures i Transport

 *   Av. Blasco Ib??ez, 50

 *   46010 VALENCIA

 *   SPAIN

 *

 *      +34 963862235

 *   gvsig@gva.es

 *      www.gvsig.gva.es

 *

 *    or

 *

 *   IVER T.I. S.A

 *   Salamanca 50

 *   46005 Valencia

 *   Spain

 *

 *   +34 963163400

 *   dac@iver.es

 */

/* CVS MESSAGES:

 *

 * $Id: XmlStreamException.java 19593 2008-03-12 17:23:30Z groldan $

 * $Log$

 */

import java.io.IOException;

/**

 * Signals either a parsing or io error ocurred while scanning or writing an xml formatted document.

 * 

 * @author Gabriel Roldan (TOPP)

 * @version $Id: XmlStreamException.java 19593 2008-03-12 17:23:30Z groldan $

 */

public class XmlStreamException extends IOException {

	private static final long serialVersionUID = 2565360995097194850L;

	public XmlStreamException(String message) {

        this(message, null);

    }

    public XmlStreamException(String message, Throwable cause) {

        super(message);

        super.initCause(cause);

    }

    public XmlStreamException(Throwable cause) {

        this(null, cause);

    }

}

package org.gvsig.xmlpull.lib.api.stream;

import java.io.IOException;

import java.io.InputStream;

class StreamUtils {

    private StreamUtils() {

        // do nothing

    }

    /**

     * @param _is

     * @return Returns the encoding or UTF-8 encoding by default.

     * @throws IOException

     */

    public static String getEncoding(final InputStream _is) throws IOException {

        String encoding = "UTF-8";

        int srcCount = 0;

        char[] srcBuf = new char[128];

        // read four bytes

        int chk = 0;

        try {

            while (srcCount < 4) {

                int i = _is.read();

                if (i == -1)

                    break;

                chk = (chk << 8) | i;

                srcBuf[srcCount++] = (char) i;

            }

            if (srcCount == 4) {

                switch (chk) {

                case 0x00000FEFF:

                    encoding = "UTF-32BE";

                    srcCount = 0;

                    break;

                case 0x0FFFE0000:

                    encoding = "UTF-32LE";

                    srcCount = 0;

                    break;

                case 0x03c:

                    encoding = "UTF-32BE";

                    srcBuf[0] = '<';

                    srcCount = 1;

                    break;

                case 0x03c000000:

                    encoding = "UTF-32LE";

                    srcBuf[0] = '<';

                    srcCount = 1;

                    break;

                case 0x0003c003f:

                    encoding = "UTF-16BE";

                    srcBuf[0] = '<';

                    srcBuf[1] = '?';

                    srcCount = 2;

                    break;

                case 0x03c003f00:

                    encoding = "UTF-16LE";

                    srcBuf[0] = '<';

                    srcBuf[1] = '?';

                    srcCount = 2;

                    break;

                case 0x03c3f786d:

                    while (true) {

                        int i = _is.read();

                        if (i == -1)

                            break;

                        srcBuf[srcCount++] = (char) i;

                        if (i == '>') {

                            String s = new String(srcBuf, 0, srcCount);

                            int i0 = s.indexOf("encoding");

                            if (i0 != -1) {

                                while (s.charAt(i0) != '"' && s.charAt(i0) != '\'')

                                    i0++;

                                char deli = s.charAt(i0++);

                                int i1 = s.indexOf(deli, i0);

                                encoding = s.substring(i0, i1);

                            }

                            break;

                        }

                    }

                default:

                    if ((chk & 0x0ffff0000) == 0x0FEFF0000) {

                        encoding = "UTF-16BE";

                        srcBuf[0] = (char) ((srcBuf[2] << 8) | srcBuf[3]);

                        srcCount = 1;

                    } else if ((chk & 0x0ffff0000) == 0x0fffe0000) {

                        encoding = "UTF-16LE";

                        srcBuf[0] = (char) ((srcBuf[3] << 8) | srcBuf[2]);

                        srcCount = 1;

                    } else if ((chk & 0x0ffffff00) == 0x0EFBBBF00) {

                        encoding = "UTF-8";

                        srcBuf[0] = srcBuf[3];

                        srcCount = 1;

                    }

                }

            }

        } catch (IOException ex) {

            return null;

        }

        return encoding;

    }

}

package org.gvsig.xmlpull.lib.api.stream;

import java.io.InputStream;

/* gvSIG. Sistema de Informaci?n Geogr?fica de la Generalitat Valenciana

 *

 * Copyright (C) 2004 IVER T.I. and Generalitat Valenciana.

 *

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of the GNU General Public License

 * as published by the Free Software Foundation; either version 2

 * of the License, or (at your option) any later version.

 *

 * This program 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 General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307,USA.

 *

 * For more information, contact:

 *

 *  Generalitat Valenciana

 *   Conselleria d'Infraestructures i Transport

 *   Av. Blasco Ib??ez, 50

 *   46010 VALENCIA

 *   SPAIN

 *

 *      +34 963862235

 *   gvsig@gva.es

 *      www.gvsig.gva.es

 *

 *    or

 *

 *   IVER T.I. S.A

 *   Salamanca 50

 *   46005 Valencia

 *   Spain

 *

 *   +34 963163400

 *   dac@iver.es

 */

/**

 * 

 */

public interface IXmlStreamReaderFactory {

    boolean canParse(String mimeType);

    IXmlStreamReader createParser(String mimeType, InputStream in) throws XmlStreamException,

            IllegalArgumentException;

}

/* gvSIG. Sistem a de Informaci?n Geogr?fica de la Generalitat Valenciana

 *

 * Copyright (C) 2007 Generalitat Valenciana.

 *

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of the GNU General Public License

 * as published by the Free Software Foundation; either version 2

 * of the License, or (at your option) any later version.

 *

 * This program 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 General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307,USA.

 *

 * For more information, contact:

 *

 *  Generalitat Valenciana

 *   Conselleria d'Infraestructures i Transport

 *   Av. Blasco Ib??ez, 50

 *   46010 VALENCIA

 *   SPAIN

 *

 *      +34 9638 62 495

 *      gvsig@gva.es

 *      www.gvsig.gva.es

 */

package org.gvsig.xmlpull.lib.api.stream;

import java.io.IOException;

/**

 * IXmlStreamWriter defines an "XML push" like streaming API for writing XML documents encoded as

 * per the OGC Binary XML Best Practices document.

 * <p>

 * This interface does not defines setter methods to control encoding behavior such as byte order to

 * use or character encoding. A IXmlStreamWriter instance is meant to be already configured with the

 * desired encoding options when returned from the {@link BxmlOutputFactory}.

 * </p>

 * <p>

 * Sample usage:

 * 

 * <pre>

 * <code>

 * BxmlOutputFactory factory = BxmlFactoryFinder.newOutputFactory();

 * IXmlStreamWriter writer = factory.createSerializer(inputStream);

 * 

 * writer.setSchemaLocation("http://www.example.com", "http://www.example.com/schema.xsd");

 * 

 * writer.writeStartDocument();

 * 

 * writer.setPrefix("ex", "http://www.example.com")

 * writer.setDefaultNamespace("http://www.anotherexample.com");

 * 

 * writer.writeStartElement("", "root");

 * 

 * writer.writeStartElement("http://www.example.com", "child");

 * 

 * //child attributes list...

 * writer.writeStartAttribute("http://www.example.com", "att");

 * writer.writeValue("attValue");

 * writer.writeStartAttribute("http://www.example.com", "emptyAtt");

 * writer.writeEndAttributes();

 * 

 * //child value as a purely streamed int array

 * writer.startArray(EventType.VALUE_INT, 10);

 * for(int i = 0; i < 10; i++){

 *   writer.writeValue(i);

 * }

 * writer.endArray();

 * 

 * writer.writeComment("interleaved value type follow");

 * 

 * writer.writeValue("10 11 12 13");

 * 

 * writer.writeEndElement(); // child

 * writer.writeEndElement(); // root

 * writer.writeEndDocument();

 * </code>

 * </pre>

 * 

 * </p>

 * 

 * @author Gabriel Roldan (TOPP)

 * @version $Id: IXmlStreamWriter.java 21945 2008-06-30 14:04:53Z jpiera $

 * @since 1.0

 */

public interface IXmlStreamWriter {

    /**

     * Returns a safe copy of the encoding options this writer is settled up with.

     * <p>

     * Modifications to the returned object state does not affect this writer behaviour.

     * </p>

     * 

     * @return an object representing the set of encoding options this writer operates with

     */

    //public EncodingOptions getEncodingOptions();

    /**

     * Returns the event corresponding to the last write call.

     * <p>

     * For example, if the last write call was

     * {@link #writeStartElement(String, String) writeStartElement} it shall return

     * {@link EventType#START_ELEMENT START_ELEMENT}, if it was

     * {@link #writeStartAttribute(String, String) writeStartAttribute},

     * {@link EventType#ATTRIBUTE ATTRIBUTE}, etc.

     * </p>

     * 

     * @post {$return != null}

     * @return {@link EventType#NONE} if writing has not yet started (ie, writeStartDocument has not

     *         been called), the event for the last write operation otherwise.

     */

    public EventType getLastEvent();

    /**

     * @return {@code null} if no tag event has been written yet, START_ELEMENT or END_ELEMENT

     *         otherwise, depending on which of them was lately called

     */

    public EventType getLastTagEvent();

    /**

     * @post {$return >= 0}

     * @return how deep is the current element tree

     */

    public int getTagDeep();

    /**

     * Closes this stream writer and releases any system resources associated with it, including the

     * underlying output stream or any other output source it may be operating upon.

     * <p>

     * A call to this method implies a flush of any possible buffered wtrite before closing the

     * stream.

     * </p>

     * <p>

     * The first call to this method closes and releases resources. Subsequent calls shall take no

     * effect and return quitely. After the first call to this method any non query method (defined

     * as metadata retrieval methods in the class' javadoc) shall fail with an io exception.

     * </p>

     * 

     * @throws IOException if an I/O error occurs.

     */

    public void close() throws IOException;

    /**

     * Returns whether this stream writer and its underlying output source are open and able to

     * receive more write calls.

     * <p>

     * A {@code IXmlStreamWriter} should be open since its creation until {@link #close()} is

     * explicitly called by client code.

     * </p>

     * 

     * @return {@code true} if this stream is still open, {@code false} otherwise

     */

    public boolean isOpen();

    /**

     * Write any cached data to the underlying output mechanism.

     * 

     * @throws IOException

     */

    public void flush() throws IOException;

    /**

     * @pre {getLastEvent() == NONE}

     * @pre {namespaceUri != null AND schemaLocationUri != null}

     * @pre {namespaceUri != ""}

     * @param namespaceUri

     * @param schemaLocationUri

     */

    public void setSchemaLocation(String namespaceUri, String schemaLocationUri);

    /**

     * Initiates the encoding of an XML formatted document in the BXML encoding.

     * <p>

     * This should be the first non query method to call after a stream writer is created. The

     * implementation will use the call to this method to write down the document header and xml

     * declaration.

     * </p>

     * 

     * @pre {getLastEvent() == NONE}

     * @post {getLastEvent() == START_DOCUMENT}

     * @throws IOException

     */

    public void writeStartDocument() throws IOException;

    /**

     * Finishes up encoding a BXML document.

     * <p>

     * Implementations shall use this method to write down the document's trailer token.

     * </p>

     * 

     * @pre {getTagDeep() == 0}

     * @post {getLastEvent() == END_DOCUMENT}

     * @throws IOException

     */

    public void writeEndDocument() throws IOException;

    /**

     * @pre {namespaceUri != null}

     * @pre {localName != null}

     * @post {getLastEvent() == START_ELEMENT}

     * @param namespaceUri the namespace uri for the element

     * @param localName the elements non qualified (local) name

     * @throws IOException

     */

    public void writeStartElement(final String namespaceUri, final String localName)

            throws IOException;

    /**

     * @pre {qname != null}

     * @post {getLastEvent() == START_ELEMENT}

     * @param qname qualified element name. Only namespace and localName are relevant. Prefix, if

     *            present, is ignored. The currently mapped prefix for the namespace will be used in

     *            any case.

     * @throws IOException

     * @see #setPrefix(String, String)

     */

    public void writeStartElement(final IQName qname) throws IOException;

    /**

     * @pre {getTagDeep() > 0}

     * @pre { ( getLastEvent().isValue() AND getWrittenValueCount() == getValueLength() ) ||

     *      getLastEvent() IN ( START_ELEMENT, END_ELEMENT, ATTRIBUTES_END, COMMENT}

     * @post {getLastEvent() == END_ELEMENT}

     * @throws IOException

     */

    public void writeEndElement() throws IOException;

    /**

     * Starts writting an xml attribute.

     * <p>

     * Writting an attribute and its value is split in two parts. This method only stand for the

     * attribute declaration. Writting an attribute value is made after calling this method and is

     * optional. The attribute value can be done with any of the {@code writeValue} methods, even

     * using various {@code writeValue} calls for the same attribute.

     * </p>

     * <p>

     * After the last element attribute has been written, {@link #writeEndAttributes()} shall be

     * called to indicate the end of the attribute list.

     * </p>

     * Sample usage:

     * 

     * <pre>

     * <code>

     * <b>writer.startAttribute("", "att1");</b>

     * writer.writeValue("value1");

     * writer.writeValue(1);

     * writer.writeValue(2);

     * writer.writeValue(3);

     * <b>writer.startAttribute("", "att2");</b>

     * writer.writeValue(1.0L);

     * ...

     * writer.writeEndAttributes();

     * </code>

     * </pre>

     * 

     * @pre {getLastEvent() IN (START_ELEMENT, ATTRIBUTE) }

     * @pre {namespaceUri != null}

     * @pre {localName != null}

     * @post {getLastEvent() == ATTRIBUTE}

     * @param namespaceUri not null

     * @param localName not null

     * @throws IOException

     * @see #writeEndAttributes()

     */

    public void writeStartAttribute(final String namespaceUri, final String localName)

            throws IOException;

    /**

     * Starts writing an xml attribute for the given qualified name.

     * 

     * @pre {qname != null}

     * @param qname a QName where to get the namespace uri and local name for the attribute

     * @throws IOException

     * @see #writeStartAttribute(String, String)

     */

    public void writeStartAttribute(final IQName qname) throws IOException;

    /**

     * Indicates there are no more element attributes to encode for the current element.

     * <p>

     * This method is useful for the encoder to recognize (and write down the appropriate tokens)

     * the following potential call to some writeValue method corresponds to the element's contents

     * and not to the current attribute value.

     * </p>

     * Sample usage:

     * 

     * <pre>

     * <code>

     * writer.startElement("", "element");

     * writer.startAttribute("", "att1");

     * writer.writeValue("value1");

     * writer.startAttribute("", "att2");

     * writer.writeValue(1.0L);

     * ...

     * <b>writer.writeEndAttributes();</b>

     * writer.value("element value");

     * ...

     * </code>

     * </pre>

     * 

     * @pre {getLastTagEvent() == START_ELEMENT}

     * @post {getLastEvent() == ATTRIBUTES_END}

     * @throws IOException

     */

    public void writeEndAttributes() throws IOException;

    /**

     * @pre {getLastEvent().isValue() == true || getLastEvent() IN (START_ELEMENT, ATTRIBUTE,

     *      COMMENT )}

     * @post {getLastEvent() == VALUE_STRING}

     * @post {getValueLength() == 1}

     * @post {getWrittenValueCount() == 1}

     * @param value

     * @throws IOException

     */

    public void writeValue(final String value) throws IOException;

    /**

     * @pre {getLastEvent().isValue() == true || getLastEvent() IN (START_ELEMENT, ATTRIBUTE,

     *      COMMENT )}

     * @post {getLastEvent() == VALUE_STRING}

     * @param chars

     * @param offset

     * @param length

     * @throws IOException

     */

    public void writeValue(final char[] chars, final int offset, final int length)

            throws IOException;

    /**

     * @pre {getLastEvent().isValue() == true || getLastEvent() IN (START_ELEMENT, ATTRIBUTE,

     *      COMMENT )}

     * @post {getLastEvent() == VALUE_INT}

     * @param value

     * @throws IOException

     */

    public void writeValue(final int value) throws IOException;

    /**

     * @pre {getLastEvent().isValue() == true || getLastEvent() IN (START_ELEMENT, ATTRIBUTE,

     *      COMMENT )}

     * @post {getLastEvent() == VALUE_LONG}

     * @param value

     * @throws IOException

     */

    public void writeValue(final long value) throws IOException;

    /**

     * @pre {getLastEvent().isValue() == true || getLastEvent() IN (START_ELEMENT, ATTRIBUTE,

     *      COMMENT )}

     * @post {getLastEvent() == VALUE_FLOAT}

     * @param value

     * @throws IOException

     */

    public void writeValue(final float value) throws IOException;

    /**

     * @pre {getLastEvent().isValue() == true || getLastEvent() IN (START_ELEMENT, ATTRIBUTE,

     *      COMMENT )}

     * @post {getLastEvent() == VALUE_DOUBLE}

     * @param value

     * @throws IOException

     */

    public void writeValue(final double value) throws IOException;

    /**

     * @pre {getLastEvent().isValue() == true || getLastEvent() IN (START_ELEMENT, ATTRIBUTE,

     *      COMMENT )}

     * @post {getLastEvent() == VALUE_BOOL}

     * @param value

     * @throws IOException

     */

    public void writeValue(final boolean value) throws IOException;

    /**

     * @pre {getLastEvent().isValue() == true || getLastEvent() IN (START_ELEMENT, ATTRIBUTE,

     *      COMMENT )}

     * @post {getLastEvent() == VALUE_BOOL}

     * @param value

     * @param offset

     * @param length

     * @throws IOException

     */

    public void writeValue(final boolean[] value, final int offset, final int length)

            throws IOException;

    /**

     * @pre {getLastEvent().isValue() == true || getLastEvent() IN (START_ELEMENT, ATTRIBUTE,

     *      COMMENT )}

     * @post {getLastEvent() == VALUE_INT}

     * @param value

     * @param offset

     * @param length

     * @throws IOException

     */

    public void writeValue(final int[] value, final int offset, final int length)

            throws IOException;

    /**

     * @pre {getLastEvent().isValue() == true || getLastEvent() IN (START_ELEMENT, ATTRIBUTE,

     *      COMMENT )}

     * @post {getLastEvent() == VALUE_LONG}

     * @param value

     * @param offset

     * @param length

     * @throws IOException

     */

    public void writeValue(final long[] value, final int offset, final int length)

            throws IOException;

    /**

     * @pre {getLastEvent().isValue() == true || getLastEvent() IN (START_ELEMENT, ATTRIBUTE,

     *      COMMENT )}

     * @post {getLastEvent() == VALUE_FLOAT}

     * @param value

     * @param offset

     * @param length

     * @throws IOException

     */

    public void writeValue(final float[] value, final int offset, final int length)

            throws IOException;

    /**

     * Writes a value section defined by the

     * 

     * @pre {getLastEvent() IN ( START_ELEMENT START_ELEMENT, ATTRIBUTE ATTRIBUTE )}

     * @post {getLastEvent() == VALUE_DOUBLE}

     * @param value

     * @param offset

     * @param length

     * @throws IOException

     */

    public void writeValue(final double[] value, int offset, int length) throws IOException;

    /**

     * Writes a comments block

     * <p>

     * The provided {@code commentContent} is the coalesced value of the equivalent XML comment

     * block (enclosed between {@code <!--} and {@code -->} tags.

     * </p>

     * 

     * @post {getLastEvent() == COMMENT}

     * @param commentContent the coallesced value of the comment section

     * @throws IOException

     */

    public void writeComment(String commentContent) throws IOException;

    /**

     * @pre {valueType != null}

     * @pre {valueType.isValue() == true}

     * @pre {valueType != VALUE_STRING}

     * @pre {arrayLength >= 0}

     * @post {getLastEvent() == valueType}

     * @post {getWrittenValueCount() == 0}

     * @post {getValueLength() == arrayLength}

     * @param valueType

     * @param arrayLength

     * @throws IOException

     */

    public void startArray(EventType valueType, int arrayLength) throws IOException;

    /**

     * Needs to be called when done with startArray

     * 

     * @pre {getWrittenValueCount() == getValueLength()}

     * @throws IOException

     */

    public void endArray() throws IOException;

    /**

     * Binds a URI to the default namespace for the current context.

     * <p>

     * This URI is bound in the scope of the current START_ELEMENT / END_ELEMENT pair. If this

     * method is called before a START_ELEMENT has been written the uri is bound in the root scope.

     * </p>

     * 

     * @pre {getLastEvent() == NONE || getLastEvent() == START_ELEMENT}

     * @param defaultNamespaceUri the uri to bind to the default namespace, may be {@code null}

     * @throws XmlStreamException 

     */

    public void setDefaultNamespace(String defaultNamespaceUri) throws XmlStreamException;

    /**

     * Sets the prefix the uri is bound to, for the current context.

     * <p>

     * This prefix is bound in the scope of the current START_ELEMENT / END_ELEMENT pair (current

     * context). If this method is called before a START_ELEMENT has been written the prefix is

     * bound in the root scope.

     * </p>

     * 

     * @pre {getLastEvent() == NONE || getLastEvent() == START_ELEMENT}

     * @param prefix

     * @param namespaceUri

     * @throws XmlStreamException 

     */

    public void setPrefix(final String prefix, final String namespaceUri) throws XmlStreamException;

    /**

     * @pre {getLastEvent().isValue() == true}

     * @post {$return >= 0}

     * @return the length of the current value being written.

     */

    public long getValueLength();

    /**

     * @pre {getLastEvent().isValue() == true}

     * @post {$return >= 0}

     * @post {$return <= getValueLength()}

     * @return how many elements has already being written for the current value

     */

    public long getWrittenValueCount();

}

/* gvSIG. Sistem a de Informaci?n Geogr?fica de la Generalitat Valenciana

 *

 * Copyright (C) 2007 Generalitat Valenciana.

 *

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of the GNU General Public License

 * as published by the Free Software Foundation; either version 2

 * of the License, or (at your option) any later version.

 *

 * This program 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 General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307,USA.

 *

 * For more information, contact:

 *

 *  Generalitat Valenciana

 *   Conselleria d'Infraestructures i Transport

 *   Av. Blasco Ib??ez, 50

 *   46010 VALENCIA

 *   SPAIN

 *

 *      +34 9638 62 495

 *      gvsig@gva.es

 *      www.gvsig.gva.es

 */

package org.gvsig.xmlpull.lib.api.stream;

/**

 * The EventType enum defines the possible parse events a {@link IXmlStreamReader} may return during

 * each call to {@code next()}.

 * <p>

 * These are high level events and may not map one to one to the low level Binary XML format tokens.

 * This is so to better reflect the problem domain for this high level API, letting the low level

 * treatment of specific bxml tokens to the implementation criteria.

 * </p>

 * <p>

 * In general lines, it could be said that the following EventType to TokenType mappings are

 * defined: <table>

 * <tr>

 * <th>EventType</th>

 * <th>TokenType</th>

 * </tr>

 * <tr>

 * <td>NONE</td>

 * <td>Header</td>

 * </tr>

 * <tr>

 * <td>START_DOCUMENT</td>

 * <td>XmlDeclaration, if present, forced otherwise in order to always return a START_DOCUMENT

 * event</td>

 * </tr>

 * <tr>

 * <td>END_DOCUMENT</td>

 * <td>Trailer</td>

 * </tr>