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}