001/*
002 * ============================================================================
003 * Copyright © 2002-2025 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;
024
025import org.apiguardian.api.API;
026import org.tquadrat.foundation.annotation.ClassVersion;
027import org.tquadrat.foundation.xml.parse.spi.StAXParserBase;
028
029/**
030 *  <p>{@summary Parses an XML stream to an object of type {@code T}}; that
031 *  object is either provided with the constructor
032 *  {@link #StAXParser(Object)}
033 *  or will be created by an instance of
034 *  {@link XMLParseEventHandler}.</p>
035 *  <p>To start the parsing process, call
036 *  {@link #parse(XMLEventReader)}
037 *  on the instance of {@code StAXParser}.</p>
038 *
039 *  @param  <T> The type of the target data structure.
040 *
041 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
042 *  @version $Id: StAXParser.java 1152 2025-12-25 09:51:42Z tquadrat $
043 *  @since 0.0.5
044 *
045 *  @UMLGraph.link
046 */
047@ClassVersion( sourceVersion = "$Id: StAXParser.java 1152 2025-12-25 09:51:42Z tquadrat $" )
048@API( status = EXPERIMENTAL, since = "0.0.5" )
049public final class StAXParser<T> extends StAXParserBase<T>
050{
051        /*--------------*\
052    ====** Constructors **=====================================================
053        \*--------------*/
054    /**
055     *  Creates a new {@code StAXParser} instance.
056     */
057    public StAXParser() { super(); }
058
059    /**
060     *  Creates a new {@code StAXParser} instance.
061     *
062     *  @param  target  The target data structure.
063     */
064    public StAXParser( final T target ) { super( target ); }
065
066        /*---------*\
067    ====** Methods **==========================================================
068        \*---------*/
069    /**
070     *  <p>{@summary Adds the document handler.}</p>
071     *  <p>This handler must create or update the target data structure.</p>
072     *
073     *  @param  elementName The element name for the document.
074     *  @param  handler The parse event handler.
075     */
076    public final void addDocumentHandler( final String elementName, final XMLParseEventHandler<T> handler )
077    {
078        registerElementHandler( elementName, true, handler );
079    }   //  addDocumentHandler()
080
081    /**
082     *  <p>{@summary Adds an element handler.}</p>
083     *  <p>These handlers will be called from inside another parse event
084     *  handler.</p>
085     *
086     *  @param  elementName The element name.
087     *  @param  handler The parse event handler.
088     */
089    public final void addElementHandler( final String elementName, final XMLParseEventHandler<?> handler )
090    {
091        registerElementHandler( elementName, false, handler );
092    }   //  addElementHandler()
093}
094//  class StAXParser
095
096/*
097 *  End of File
098 */