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.spi;
020
021import static org.apiguardian.api.API.Status.EXPERIMENTAL;
022
023import javax.xml.stream.XMLStreamException;
024
025import org.apiguardian.api.API;
026import org.tquadrat.foundation.annotation.ClassVersion;
027import org.tquadrat.foundation.xml.parse.XMLParseEventHandler;
028
029/**
030 *  The interface for a function that returns an instance of
031 *  {@link XMLParseEventHandler}
032 *  for an XML element.<br>
033 *  <br>This is a functional interface whose functional method is
034 *  {@link #retrieveHandler(String)}.
035 *
036 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
037 *  @version $Id: HandlerProvider.java 820 2020-12-29 20:34:22Z tquadrat $
038 *  @since 0.0.5
039 *
040 *  @UMLGraph.link
041 */
042@ClassVersion( sourceVersion = "$Id: HandlerProvider.java 820 2020-12-29 20:34:22Z tquadrat $" )
043@API( status = EXPERIMENTAL, since = "0.0.5" )
044@FunctionalInterface
045public interface HandlerProvider
046{
047        /*-----------*\
048    ====** Constants **========================================================
049        \*-----------*/
050    /**
051     *  An empty array of {@code HandlerProvider} objects.
052     */
053    public static final HandlerProvider [] EMPTY_HandlerProvider_ARRAY = new HandlerProvider [0];
054
055        /*---------*\
056    ====** Methods **==========================================================
057        \*---------*/
058    /**
059     *  Retrieves the XML parse event handler for the given element name.
060     *
061     *  @param  elementName The name of the element to handle.
062     *  @return The requested instance of
063     *      {@link XMLParseEventHandler}.
064     *  @throws XMLStreamException  There is no registered handler for the
065     *      given element name.
066     */
067    public XMLParseEventHandler<?> retrieveHandler( final String elementName ) throws XMLStreamException;
068}
069//  class HandlerProvider
070
071/*
072 *  End of File
073 */