org.nuiton.io.xpp3.Xpp3Reader Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of maven-helper-plugin Show documentation
Plugin d'aide pour les projets nuiton
There is a newer version: 1.3
/*
 * #%L
 * Maven helper plugin
 * 
 * $Id: Xpp3Reader.java 776 2010-10-23 11:44:57Z tchemit $
 * $HeadURL: http://svn.nuiton.org/svn/maven-helper-plugin/tags/maven-helper-plugin-1.2.10/src/main/java/org/nuiton/io/xpp3/Xpp3Reader.java $
 * %%
 * Copyright (C) 2009 - 2010 Tony Chemit, CodeLutin
 * %%
 * This program 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 3 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 Lesser Public License for more details.
 * 
 * You should have received a copy of the GNU General Lesser Public 
 * License along with this program.  If not, see
 * .
 * #L%
 */

package org.nuiton.io.xpp3;

import org.codehaus.plexus.util.xml.pull.XmlPullParserException;

import java.io.IOException;
import java.io.Reader;

/**
 * A simple contract to mark all xpp readers.
 * 
 * a such reader is associated to a {@link #getType()}.
 * 

 * The implementations of such readers must be register in a file
 * 
 * META-INF/services.org.nuiton.io.xpp3.Xpp3Reader
 * 
 * 
 * to make possible auto-discovering of availables reader at runtime.
 * 

 * See {@link Xpp3Helper#getReader(Class)} and
 * {@link Xpp3Helper#getReaders()}.
 *
 * @author tchemit 
 * @param  the type of object to be build by the reader.
 * @since 1.0.3
 */
public interface Xpp3Reader {

    /** @return the type of main object to read */
    Class getType();

    /**
     * Read a single instance of the typed object and return it.
     * 

     * Note : this is a convinient method to call
     * {@link #read(Reader, boolean)} in strict mode.
     * 

     * In the xml stream, the root tag must be the {@link #getRootTagName()}.
     * 

     * Example :
     * 
     * <issue>:
     *    ...
     * </issue>:
     * 
     *
     * @param reader the xml input reader
     * @return Settings
     * @throws IOException            if any io pb
     * @throws XmlPullParserException if parsing error
     */
    O read(Reader reader) throws IOException, XmlPullParserException;

    /**
     * Read a single instance of the typed object and return it.
     * 
     * In the xml stream, the root tag must be the {@link #getRootTagName()}.
     * 

     * Example :
     * 
     * <issue>:
     *    ...
     * </issue>:
     * 
     *
     * @param reader the xml input reader
     * @param strict flag to be strict while parsing
     * @return the read object
     * @throws IOException            if any io pb
     * @throws XmlPullParserException if any parsing pb
     */
    O read(Reader reader, boolean strict) throws IOException,
            XmlPullParserException;

    /**
     * Read some instances of the typed object and return it.
     * 
     * In the xml stream, the root tag must be the
     * {@link #getArrayRootTagName()}.
     * 

     * Note : this is a convinient method to call :
     * {@link #readArray(Reader, boolean)} in stritc mode.
     * 

     * Example :
     * 
     * <issues>:
     *   <issue>:
     *    ...
     *   </issue>:
     * </issues>:
     * 
     *
     * @param reader the xml input reader
     * @return the array of read objects.
     * @throws IOException            if any io pb
     * @throws XmlPullParserException if any parsing pb
     */
    O[] readArray(Reader reader) throws IOException, XmlPullParserException;

    /**
     * Read some instances of the typed object and return it.
     * 
     * In the xml stream, the root tag must be the
     * {@link #getArrayRootTagName()}.
     * 

     * Example :
     * 
     * <issues>:
     *   <issue>:
     *    ...
     *   </issue>:
     * </issues>:
     * 
     *
     * @param reader the xml input reader
     * @param strict flag to be strict while parsing
     * @return the array of read objects.
     * @throws IOException            if any io pb
     * @throws XmlPullParserException if any parsing pb
     */
    O[] readArray(Reader reader, boolean strict) throws IOException,
            XmlPullParserException;

    /** @return the name of the root tag of a object to read */
    String getRootTagName();

    /**
     * Set the name of the root tag of an object to read.
     *
     * @param rootTagName the name of the tag
     */
    void setRootTagName(String rootTagName);

    /** @return the name of the root tag of an array of objets to read */
    String getArrayRootTagName();

    /**
     * Set the name of the root tag for an array of object to read.
     *
     * @param parentRootTagName the name of the tag
     */
    void setParentRootTagName(String parentRootTagName);

    /**
     * @return {@code true} if parser will load the default entities,
     *         {@code false} otherwise.
     */
    boolean isAddDefaultEntities();

    /**
     * Set the new value of the {@code defaultEntities} flag.
     *
     * @param addDefaultEntities the new value.
     */
    void setAddDefaultEntities(boolean addDefaultEntities);
}