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: */
017: package org.apache.wicket.markup.parser;
018:
019: import java.io.IOException;
020: import java.io.InputStream;
021: import java.text.ParseException;
022:
023: import org.apache.wicket.util.resource.ResourceStreamNotFoundException;
024:
025: /**
026: * The interface of a streaming XML parser as required by Wicket.
027: *
028: * @author Juergen Donnerstag
029: * @author Jonathan Locke
030: */
031: public interface IXmlPullParser extends IMarkupFilter {
032: /**
033: * Return the encoding applied while reading the markup resource. The
034: * encoding is determined by analysing the <?xml version=".."
035: * encoding=".." ?> tag.
036: *
037: * @return if null, JVM defaults have been used.
038: */
039: String getEncoding();
040:
041: /**
042: * Return the XML declaration string, in case if found in the markup.
043: *
044: * @return Null, if not found.
045: */
046: String getXmlDeclaration();
047:
048: /**
049: * Wicket dissects the markup into Wicket relevant tags and raw markup,
050: * which is not further analysed by Wicket. The method
051: * getInputFromPositionMarker() is used to access the raw markup.
052: *
053: * @param toPos
054: * To position
055: * @return The raw markup in between the position marker and toPos
056: */
057: CharSequence getInputFromPositionMarker(int toPos);
058:
059: /**
060: * Wicket dissects the markup into Wicket relevant tags and raw markup,
061: * which is not further analysed by Wicket. The getInputSubsequence() method
062: * is used to access the raw markup.
063: *
064: * @param fromPos
065: * From position
066: * @param toPos
067: * To position
068: * @return The raw markup in between fromPos and toPos
069: */
070: CharSequence getInput(final int fromPos, final int toPos);
071:
072: /**
073: * Dissect the XML markup into tags and text. Tags are further analysed into
074: * comments, CDATA, processing instruction etc as well as "standard" tags.
075: * By means of getType() the type of the current element can be retrieved
076: * and the appropriate getters must used to get hold of the informantion.
077: *
078: * @return false, if end-of-file as been reached. If true, than use
079: * getType() to determine what has been found.
080: * @throws ParseException
081: */
082: boolean next() throws ParseException;
083:
084: /**
085: * Parse the markup provided. Use nextTag() to access the tags contained one
086: * after another.
087: * <p>
088: * Note: xml character encoding is NOT applied. It is assumed the input
089: * provided does have the correct encoding already.
090: *
091: * @param string
092: * The markup to be parsed
093: * @throws IOException
094: * Error while reading the resource
095: * @throws ResourceStreamNotFoundException
096: * Resource not found
097: */
098: void parse(final CharSequence string) throws IOException,
099: ResourceStreamNotFoundException;
100:
101: /**
102: * Reads and parses markup from an input stream, using UTF-8 encoding by
103: * default when not specified in XML declaration. Use nextTag() to access
104: * the tags contained, one after another.
105: *
106: * @param inputStream
107: * The input stream to read and parse
108: * @throws IOException
109: * Error while reading the resource
110: * @throws ResourceStreamNotFoundException
111: * Resource not found
112: */
113: public abstract void parse(final InputStream inputStream)
114: throws IOException, ResourceStreamNotFoundException;
115:
116: /**
117: * Reads and parses markup from an input stream. Use nextTag() to access the
118: * tags contained, one after another.
119: *
120: * @param inputStream
121: * A resource like e.g. a file
122: * @param encoding
123: * Use null to apply JVM/OS default
124: * @throws IOException
125: * Error while reading the resource
126: * @throws ResourceStreamNotFoundException
127: * Resource not found
128: */
129: void parse(InputStream inputStream, final String encoding)
130: throws IOException, ResourceStreamNotFoundException;
131:
132: /**
133: * Set the position marker of the markup at the current position.
134: */
135: void setPositionMarker();
136:
137: /**
138: * Set the position marker of the markup
139: *
140: * @param pos
141: */
142: void setPositionMarker(final int pos);
143: }
|