001/*
002 * MIT License
003 * 
004 * Copyright (c) 2016 Michael Angstadt
005 * 
006 * Permission is hereby granted, free of charge, to any person obtaining a copy
007 * of this software and associated documentation files (the "Software"), to deal
008 * in the Software without restriction, including without limitation the rights
009 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
010 * copies of the Software, and to permit persons to whom the Software is
011 * furnished to do so, subject to the following conditions:
012 * 
013 * The above copyright notice and this permission notice shall be included in
014 * all copies or substantial portions of the Software.
015 * 
016 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
017 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
018 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
019 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
020 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
021 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
022 * SOFTWARE.
023 */
024
025package com.github.mangstadt.vinnie.io;
026
027import com.github.mangstadt.vinnie.VObjectProperty;
028
029/**
030 * Callback interface used by {@link VObjectReader} for handling data as it is
031 * parsed off the data stream.
032 * @see VObjectReader#parse
033 * @author Michael Angstadt
034 */
035public interface VObjectDataListener {
036        /**
037         * Called when a component begins (in other words, when a BEGIN property is
038         * encountered).
039         * @param name the component name (will always be in uppercase)
040         * @param context the parse context
041         */
042        void onComponentBegin(String name, Context context);
043
044        /**
045         * <p>
046         * Called when a component ends (in other words, when an END property is
047         * encountered).
048         * </p>
049         * <p>
050         * If a component ends before any of its subcomponents end, then the parser
051         * will generate "onComponentEnd" events for each subcomponent.
052         * </p>
053         * 
054         * <p>
055         * For example, the following data will cause the following sequence of
056         * events to occur. Notice that the outer component, A, ends before its
057         * subcomponents.
058         * </p>
059         * 
060         * <p>
061         * <b>Data:</b>
062         * </p>
063         * 
064         * <pre class="brush:java">
065         * BEGIN:A
066         * BEGIN:B
067         * BEGIN:C
068         * END:A
069         * END:C
070         * END:B
071         * </pre>
072         * <p>
073         * <b>Sequence of events:</b>
074         * </p>
075         * <ol>
076         * <li>onComponentBegin(): name="A", parentComponents=[]</li>
077         * <li>onComponentBegin(): name="B", parentComponents=["A"]</li>
078         * <li>onComponentBegin(): name="C", parentComponents=["A", "B"]</li>
079         * <li>onComponentEnd(): name="C", parentComponents=["A", "B"]</li>
080         * <li>onComponentEnd(): name="B", parentComponents=["A"]</li>
081         * <li>onComponentEnd(): name="A", parentComponents=[]</li>
082         * <li>onWarning(): UNMATCHED_END</li>
083         * <li>onWarning(): UNMATCHED_END</li>
084         * </ol>
085         * @param name the component name (will always be in uppercase)
086         * @param context the parse context
087         */
088        void onComponentEnd(String name, Context context);
089
090        /**
091         * Called when a property is read.
092         * @param property the property
093         * @param context the parse context
094         */
095        void onProperty(VObjectProperty property, Context context);
096
097        /**
098         * Called when a VERSION property is read whose value and position (as
099         * defined in {@link SyntaxRules}) are recognized as valid.
100         * @param value the version string
101         * @param context the parse context
102         */
103        void onVersion(String value, Context context);
104
105        /**
106         * Called when a non-fatal error occurs during parsing.
107         * @param warning the warning
108         * @param property the property that the warning is associated with, or null
109         * if the warning is not associated with a property
110         * @param thrown the exception that was thrown or null if no exception was
111         * thrown
112         * @param context the parse context
113         */
114        void onWarning(Warning warning, VObjectProperty property, Exception thrown, Context context);
115}