001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.wicket.markup.parser;
018
019import java.io.IOException;
020import java.io.InputStream;
021import java.text.ParseException;
022
023
024
025/**
026 * The interface of a streaming XML parser as required by Wicket.
027 * 
028 * @author Juergen Donnerstag
029 * @author Jonathan Locke
030 */
031public interface IXmlPullParser
032{
033        /** The last element found */
034        enum HttpTagType {
035                /** next() must be called at least once for the Type to be valid */
036                NOT_INITIALIZED,
037
038                /** <name ...> */
039                TAG,
040
041                /** Tag body in between two tags */
042                BODY,
043
044                /** <!-- ... --> */
045                COMMENT,
046
047                /** <!--[if ] ... --> */
048                CONDITIONAL_COMMENT,
049
050                /** <![endif]--> */
051                CONDITIONAL_COMMENT_ENDIF,
052
053                /** <![CDATA[ .. ]]> */
054                CDATA,
055
056                /** <?...> */
057                PROCESSING_INSTRUCTION,
058
059                /** <!DOCTYPE ...> */
060                DOCTYPE,
061
062                /** all other tags which look like <!.. > */
063                SPECIAL_TAG,
064        }
065
066        /**
067         * Return the encoding applied while reading the markup resource. The encoding is determined by
068         * analyzing the <?xml version=".." encoding=".." ?> tag.
069         * 
070         * @return if null, JVM defaults have been used.
071         */
072        String getEncoding();
073
074        /**
075         * Gets the <!DOCTYPE ...> tag if found in the markup
076         * 
077         * @return Null, if not found
078         */
079        CharSequence getDoctype();
080
081        /**
082         * Wicket dissects the markup into Wicket relevant tags and raw markup, which is not further
083         * analyzed by Wicket. The method getInputFromPositionMarker() is used to access the raw markup.
084         * 
085         * @param toPos
086         *            To position
087         * @return The raw markup in between the position marker and toPos
088         */
089        CharSequence getInputFromPositionMarker(int toPos);
090
091        /**
092         * Wicket dissects the markup into Wicket relevant tags and raw markup, which is not further
093         * analyzed by Wicket. The getInputSubsequence() method is used to access the raw markup.
094         * 
095         * @param fromPos
096         *            From position
097         * @param toPos
098         *            To position
099         * @return The raw markup in between fromPos and toPos
100         */
101        CharSequence getInput(final int fromPos, final int toPos);
102
103        /**
104         * Parse the markup provided. Use nextTag() to access the tags contained one after another.
105         * <p>
106         * Note: xml character encoding is NOT applied. It is assumed the input provided does have the
107         * correct encoding already.
108         * 
109         * @param string
110         *            The markup to be parsed
111         * @throws IOException
112         *             Error while reading the resource
113         */
114        void parse(final CharSequence string) throws IOException;
115
116        /**
117         * Reads and parses markup from an input stream, using UTF-8 encoding by default when not
118         * specified in XML declaration. Use nextTag() to access the tags contained, one after another.
119         * 
120         * @param inputStream
121         *            The input stream to read and parse
122         * @throws IOException
123         *             Error while reading the resource
124         */
125        void parse(final InputStream inputStream) throws IOException;
126
127        /**
128         * Reads and parses markup from an input stream. Use nextTag() to access the tags contained, one
129         * after another.
130         * 
131         * @param inputStream
132         *            A resource like e.g. a file
133         * @param encoding
134         *            Use null to apply JVM/OS default
135         * @throws IOException
136         *             Error while reading the resource
137         */
138        void parse(InputStream inputStream, final String encoding) throws IOException;
139
140        /**
141         * Move to the next XML element
142         * 
143         * @return o, if end of file. Else a TAG, COMMENT etc.
144         * @throws ParseException
145         */
146        HttpTagType next() throws ParseException;
147
148        /**
149         * 
150         * @return The current element
151         */
152        XmlTag getElement();
153
154        /**
155         * @return The xml string from the last element
156         */
157        CharSequence getString();
158
159        /**
160         * Set the position marker of the markup at the current position.
161         */
162        void setPositionMarker();
163
164        /**
165         * Set the position marker of the markup
166         * 
167         * @param pos
168         */
169        void setPositionMarker(final int pos);
170}