001: /*
002: * $Id: IXmlPullParser.java 459300 2006-02-14 02:23:24Z jdonnerstag $
003: * $Revision: 459300 $ $Date: 2006-02-14 03:23:24 +0100 (Tue, 14 Feb 2006) $
004: *
005: * ==============================================================================
006: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
007: * use this file except in compliance with the License. You may obtain a copy of
008: * the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
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 under
016: * the License.
017: */
018: package wicket.markup.parser;
019:
020: import java.io.IOException;
021:
022: import wicket.util.resource.IResourceStream;
023: import 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: public abstract 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: public 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: public abstract 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: public abstract CharSequence getInput(final int fromPos,
071: final int toPos);
072:
073: /**
074: * Parse the markup provided. Use nextTag() to access the tags contained one
075: * after another.
076: * <p>
077: * Note: xml character encoding is NOT applied. It is assumed the input
078: * provided does have the correct encoding already.
079: *
080: * @param string
081: * The markup to be parsed
082: * @throws IOException
083: * Error while reading the resource
084: * @throws ResourceStreamNotFoundException
085: * Resource not found
086: */
087: public abstract void parse(final CharSequence string)
088: throws IOException, ResourceStreamNotFoundException;
089:
090: /**
091: * Reads and parses markup from a resource like file. Use nextTag() to
092: * access the tags contained, one after another.
093: *
094: * @param resource
095: * A resource like e.g. a file
096: * @param encoding
097: * Use null to apply JVM/OS default
098: * @throws IOException
099: * Error while reading the resource
100: * @throws ResourceStreamNotFoundException
101: * Resource not found
102: */
103: public abstract void parse(final IResourceStream resource,
104: final String encoding) throws IOException,
105: ResourceStreamNotFoundException;
106:
107: /**
108: * Set the position marker of the markup at the current position.
109: */
110: public abstract void setPositionMarker();
111:
112: /**
113: * Set the position marker of the markup
114: *
115: * @param pos
116: */
117: public abstract void setPositionMarker(final int pos);
118: }
|