001/*
002 * ============================================================================
003 * Copyright © 2002-2020 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 *
007 * Licensed to the public under the agreements of the GNU Lesser General Public
008 * License, version 3.0 (the "License"). You may obtain a copy of the License at
009 *
010 *      http://www.gnu.org/licenses/lgpl.html
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
014 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
015 * License for the specific language governing permissions and limitations
016 * under the License.
017 */
018
019package org.tquadrat.foundation.xml.parse;
020
021import static org.apiguardian.api.API.Status.EXPERIMENTAL;
022
023import javax.xml.stream.XMLEventReader;
024import javax.xml.stream.XMLStreamException;
025import javax.xml.stream.events.XMLEvent;
026
027import org.apiguardian.api.API;
028import org.tquadrat.foundation.annotation.ClassVersion;
029import org.tquadrat.foundation.xml.parse.spi.HandlerProvider;
030
031/**
032 *  The interface for an implementation of a parse event handler to be used
033 *  with StAX parsing of XML files.<br>
034 *  <br>This is a functional interface whose functional method is
035 *  {@link #process(XMLEventReader, XMLEvent, Object, HandlerProvider)}.
036 *
037 *  @param  <T> The type of the target data structure.
038 *
039 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
040 *  @version $Id: XMLParseEventHandler.java 820 2020-12-29 20:34:22Z tquadrat $
041 *  @since 0.0.5
042 *
043 *  @UMLGraph.link
044 */
045@ClassVersion( sourceVersion = "$Id: XMLParseEventHandler.java 820 2020-12-29 20:34:22Z tquadrat $" )
046@FunctionalInterface
047@API( status = EXPERIMENTAL, since = "0.0.5" )
048public interface XMLParseEventHandler<T>
049{
050        /*-----------*\
051    ====** Constants **========================================================
052        \*-----------*/
053    /**
054     *  An empty array of {@code XMLParseEventHandler} objects.
055     */
056    @SuppressWarnings( "rawtypes" )
057    public static final XMLParseEventHandler [] EMPTY_XMLParseEventHandler_ARRAY = new XMLParseEventHandler [0];
058
059        /*---------*\
060    ====** Methods **==========================================================
061        \*---------*/
062    /**
063     *  Handles the given event.
064     *
065     *  @param  reader  The XML event reader.
066     *  @param  xmlEvent    The current XML event.
067     *  @param  target  The instance that takes the parse result; can be
068     *      {@code null} if the handler will create a new target.
069     *  @param  handlerProvider A provider for XML parse event handlers that
070     *      are needed to process child elements.
071     *  @return The instance that took the parse result; this is either the
072     *      object that was provided with the {@code target} argument, or a new
073     *      object if {@code target} was {@code null}.
074     *  @throws XMLStreamException  Something went wrong.
075     */
076    public T process( XMLEventReader reader, XMLEvent xmlEvent, T target, HandlerProvider handlerProvider ) throws XMLStreamException;
077}
078//  class XMLParseEventHandler
079
080/*
081 *  End of File
082 */