You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xerces.apache.org by an...@locus.apache.org on 2000/10/18 20:19:11 UTC
cvs commit: xml-xerces/java/src/org/apache/xerces/impl XMLEntityManager.java XMLEntityScanner.java
andyc 00/10/18 11:19:11
Modified: java/src/org/apache/xerces/impl Tag: xerces_j_2
XMLEntityManager.java XMLEntityScanner.java
Log:
Added javadoc comments to the entity scanner to document how
the methods work.
Revision Changes Path
No revision
No revision
1.1.2.22 +208 -33 xml-xerces/java/src/org/apache/xerces/impl/Attic/XMLEntityManager.java
Index: XMLEntityManager.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/apache/xerces/impl/Attic/XMLEntityManager.java,v
retrieving revision 1.1.2.21
retrieving revision 1.1.2.22
diff -u -r1.1.2.21 -r1.1.2.22
--- XMLEntityManager.java 2000/10/18 02:06:50 1.1.2.21
+++ XMLEntityManager.java 2000/10/18 18:19:10 1.1.2.22
@@ -112,7 +112,7 @@
* @author Stubs generated by DesignDoc on Mon Sep 18 18:23:16 PDT 2000
* @author Andy Clark, IBM
*
- * @version $Id: XMLEntityManager.java,v 1.1.2.21 2000/10/18 02:06:50 andyc Exp $
+ * @version $Id: XMLEntityManager.java,v 1.1.2.22 2000/10/18 18:19:10 andyc Exp $
*/
public class XMLEntityManager
implements XMLComponent {
@@ -1250,6 +1250,24 @@
// XMLEntityScanner methods
//
+ /**
+ * Sets the encoding of the scanner. This method is used by the
+ * scanners if the XMLDecl or TextDecl line contains an encoding
+ * pseudo-attribute.
+ * <p>
+ * <strong>Note:</strong> The underlying character reader on the
+ * current entity will be changed to accomodate the new encoding.
+ * However, the new encoding is ignored if the current reader was
+ * not constructed from an input stream (e.g. an external entity
+ * that is resolved directly to the appropriate java.io.Reader
+ * object).
+ *
+ * @param encoding The IANA encoding name of the new encoding.
+ *
+ * @throws IOException Thrown if the new encoding is not supported.
+ *
+ * @see org.apache.xerces.util.EncodingMap
+ */
public void setEncoding(String encoding) throws IOException {
if (fCurrentEntity.stream != null) {
OneCharReader ocreader = (OneCharReader)fCurrentEntity.reader;
@@ -1258,9 +1276,14 @@
} // setEncoding(String)
/**
- * peekChar
- *
- * @return
+ * Returns the next character on the input.
+ * <p>
+ * <strong>Note:</strong> The character is <em>not</em> consumed.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
*/
public int peekChar() throws IOException, SAXException {
if (DEBUG) System.out.println("#peekChar()");
@@ -1278,9 +1301,14 @@
} // peekChar():int
/**
- * scanChar
- *
- * @return
+ * Returns the next character on the input.
+ * <p>
+ * <strong>Note:</strong> The character is consumed.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
*/
public int scanChar() throws IOException, SAXException {
if (DEBUG) System.out.println("#scanChar()");
@@ -1304,9 +1332,21 @@
} // scanChar():int
/**
- * scanNmtoken
- *
- * @return
+ * Returns a string matching the NMTOKEN production appearing immediately
+ * on the input as a symbol, or null if NMTOKEN Name string is present.
+ * <p>
+ * <strong>Note:</strong> The NMTOKEN characters are consumed.
+ * <p>
+ * <strong>Note:</strong> The string returned must be a symbol. The
+ * SymbolTable can be used for this purpose.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
+ *
+ * @see org.apache.xerces.util.SymbolTable
+ * @see org.apache.xerces.util.XMLChar#isName
*/
public String scanNmtoken() throws IOException, SAXException {
if (DEBUG) System.out.println("#scanNmtoken()");
@@ -1347,9 +1387,22 @@
} // scanNmtoken():String
/**
- * scanName
- *
- * @return
+ * Returns a string matching the Name production appearing immediately
+ * on the input as a symbol, or null if no Name string is present.
+ * <p>
+ * <strong>Note:</strong> The Name characters are consumed.
+ * <p>
+ * <strong>Note:</strong> The string returned must be a symbol. The
+ * SymbolTable can be used for this purpose.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
+ *
+ * @see org.apache.xerces.util.SymbolTable
+ * @see org.apache.xerces.util.XMLChar#isName
+ * @see org.apache.xerces.util.XMLChar#isNameStart
*/
public String scanName() throws IOException, SAXException {
if (DEBUG) System.out.println("#scanName()");
@@ -1405,9 +1458,28 @@
} // scanName():String
/**
- * scanQName
- *
- * @param qname
+ * Scans a qualified name from the input, setting the fields of the
+ * QName structure appropriately.
+ * <p>
+ * <strong>Note:</strong> The qualified name characters are consumed.
+ * <p>
+ * <strong>Note:</strong> The strings used to set the values of the
+ * QName structure must be symbols. The SymbolTable can be used for
+ * this purpose.
+ *
+ * @param qname The qualified name structure to fill.
+ *
+ * @return Returns true if a qualified name appeared immediately on
+ * the input and was scanned, false otherwise.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
+ *
+ * @see org.apache.xerces.util.SymbolTable
+ * @see org.apache.xerces.util.XMLChar#isName
+ * @see org.apache.xerces.util.XMLChar#isNameStart
*/
public boolean scanQName(QName qname) throws IOException, SAXException {
if (DEBUG) System.out.println("#scanQName()");
@@ -1488,9 +1560,32 @@
} // scanQName(QName):boolean
/**
- * scanContent
- *
- * @param content
+ * Scans a range of parsed character data, setting the fields of the
+ * XMLString structure, appropriately.
+ * <p>
+ * <strong>Note:</strong> The characters are consumed.
+ * <p>
+ * <strong>Note:</strong> This method does not guarantee to return
+ * the longest run of parsed character data. This method may return
+ * before markup due to reaching the end of the input buffer or any
+ * other reason.
+ * <p>
+ * <strong>Note:</strong> The fields contained in the XMLString
+ * structure are not guaranteed to remain valid upon subsequent calls
+ * to the entity scanner. Therefore, the caller is responsible for
+ * immediately using the returned character data or making a copy of
+ * the character data.
+ *
+ * @param content The content structure to fill.
+ *
+ * @return Returns the next character on the input, if known. This
+ * value may be -1 but this does <em>note</em> designate
+ * end of file.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
*/
public int scanContent(XMLString content)
throws IOException, SAXException {
@@ -1536,10 +1631,34 @@
} // scanContent(XMLString):int
/**
- * scanAttContent
- *
- * @param quote
- * @param content
+ * Scans a range of attribute value data, setting the fields of the
+ * XMLString structure, appropriately.
+ * <p>
+ * <strong>Note:</strong> The characters are consumed.
+ * <p>
+ * <strong>Note:</strong> This method does not guarantee to return
+ * the longest run of attribute value data. This method may return
+ * before the quote character due to reaching the end of the input
+ * buffer or any other reason.
+ * <p>
+ * <strong>Note:</strong> The fields contained in the XMLString
+ * structure are not guaranteed to remain valid upon subsequent calls
+ * to the entity scanner. Therefore, the caller is responsible for
+ * immediately using the returned character data or making a copy of
+ * the character data.
+ *
+ * @param quote The quote character that signifies the end of the
+ * attribute value data.
+ * @param content The content structure to fill.
+ *
+ * @return Returns the next character on the input, if known. This
+ * value may be -1 but this does <em>note</em> designate
+ * end of file.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
*/
public int scanAttContent(int quote, XMLString content)
throws IOException, SAXException {
@@ -1584,12 +1703,36 @@
} // scanAttContent(int,XMLString):int
/**
- * scanData scans data up to the given delimiter (which is consumed).
- * This assumes the internal buffer is at least bigger than the size
- * of the delimiter, and that the delimiter contains at least one char.
+ * Scans a range of character data up to the specicied delimiter,
+ * setting the fields of the XMLString structure, appropriately.
+ * <p>
+ * <strong>Note:</strong> The characters are consumed.
+ * <p>
+ * <strong>Note:</strong> This assumes that the internal buffer is
+ * at least the same size, or bigger, than the length of the delimiter
+ * and that the delimiter contains at least one character.
+ * <p>
+ * <strong>Note:</strong> This method does not guarantee to return
+ * the longest run of character data. This method may return before
+ * the delimiter due to reaching the end of the input buffer or any
+ * other reason.
+ * <p>
+ * <strong>Note:</strong> The fields contained in the XMLString
+ * structure are not guaranteed to remain valid upon subsequent calls
+ * to the entity scanner. Therefore, the caller is responsible for
+ * immediately using the returned character data or making a copy of
+ * the character data.
+ *
+ * @param delimiter The string that signifies the end of the character
+ * data to be scanned.
+ * @param data The data structure to fill.
+ *
+ * @return Returns true if there is more data to scan, false otherwise.
*
- * @param delimiter The end delimiter to look for.
- * @param data The string to fill in with the scanned data.
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
*/
public boolean scanData(String delimiter, XMLString data)
throws IOException, SAXException {
@@ -1652,9 +1795,19 @@
} // scanData(String,XMLString)
/**
- * skipChar
+ * Skips a character appearing immediately on the input.
+ * <p>
+ * <strong>Note:</strong> The character is consumed only if it matches
+ * the specified character.
*
- * @param c
+ * @param c The character to skip.
+ *
+ * @return Returns true if the character was skipped.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
*/
public boolean skipChar(int c) throws IOException, SAXException {
@@ -1686,7 +1839,19 @@
} // skipChar(int):boolean
/**
- * skipSpaces
+ * Skips space characters appearing immediately on the input.
+ * <p>
+ * <strong>Note:</strong> The characters are consumed only if they are
+ * space characters.
+ *
+ * @return Returns true if at least one space character was skipped.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
+ *
+ * @see org.apache.xerces.util.XMLChar#isSpace
*/
public boolean skipSpaces() throws IOException, SAXException {
if (DEBUG) System.out.println("#skipSpaces()");
@@ -1728,9 +1893,19 @@
} // skipSpaces():boolean
/**
- * skipString
+ * Skips the specified string appearing immediately on the input.
+ * <p>
+ * <strong>Note:</strong> The characters are consumed only if they are
+ * space characters.
+ *
+ * @param s The string to skip.
+ *
+ * @return Returns true if the string was skipped.
*
- * @param s
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
*/
public boolean skipString(String s) throws IOException, SAXException {
if (DEBUG) System.out.println("#skipString(\""+s+"\")");
1.1.2.5 +256 -6 xml-xerces/java/src/org/apache/xerces/impl/Attic/XMLEntityScanner.java
Index: XMLEntityScanner.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/apache/xerces/impl/Attic/XMLEntityScanner.java,v
retrieving revision 1.1.2.4
retrieving revision 1.1.2.5
diff -u -r1.1.2.4 -r1.1.2.5
--- XMLEntityScanner.java 2000/10/05 01:59:28 1.1.2.4
+++ XMLEntityScanner.java 2000/10/18 18:19:11 1.1.2.5
@@ -57,6 +57,7 @@
package org.apache.xerces.impl;
+import java.io.EOFException;
import java.io.IOException;
import org.apache.xerces.xni.QName;
@@ -78,8 +79,9 @@
* @author Stubs generated by DesignDoc on Mon Sep 18 18:23:16 PDT 2000
* @author Andy Clark, IBM
*
- * @version $Id: XMLEntityScanner.java,v 1.1.2.4 2000/10/05 01:59:28 andyc Exp $
+ * @version $Id: XMLEntityScanner.java,v 1.1.2.5 2000/10/18 18:19:11 andyc Exp $
*
+ * @see XMLEntityHandler
* @see XMLEntityManager
*/
public abstract class XMLEntityScanner
@@ -89,17 +91,265 @@
// Public methods
//
+ /**
+ * Sets the encoding of the scanner. This method is used by the
+ * scanners if the XMLDecl or TextDecl line contains an encoding
+ * pseudo-attribute.
+ * <p>
+ * <strong>Note:</strong> The underlying character reader on the
+ * current entity will be changed to accomodate the new encoding.
+ * However, the new encoding is ignored if the current reader was
+ * not constructed from an input stream (e.g. an external entity
+ * that is resolved directly to the appropriate java.io.Reader
+ * object).
+ *
+ * @param encoding The IANA encoding name of the new encoding.
+ *
+ * @throws IOException Thrown if the new encoding is not supported.
+ *
+ * @see org.apache.xerces.util.EncodingMap
+ */
public abstract void setEncoding(String encoding) throws IOException;
+
+ /**
+ * Returns the next character on the input.
+ * <p>
+ * <strong>Note:</strong> The character is <em>not</em> consumed.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
+ */
public abstract int peekChar() throws IOException, SAXException;
+
+ /**
+ * Returns the next character on the input.
+ * <p>
+ * <strong>Note:</strong> The character is consumed.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
+ */
public abstract int scanChar() throws IOException, SAXException;
+
+ /**
+ * Returns a string matching the NMTOKEN production appearing immediately
+ * on the input as a symbol, or null if NMTOKEN Name string is present.
+ * <p>
+ * <strong>Note:</strong> The NMTOKEN characters are consumed.
+ * <p>
+ * <strong>Note:</strong> The string returned must be a symbol. The
+ * SymbolTable can be used for this purpose.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
+ *
+ * @see org.apache.xerces.util.SymbolTable
+ * @see org.apache.xerces.util.XMLChar#isName
+ */
public abstract String scanNmtoken() throws IOException, SAXException;
+
+ /**
+ * Returns a string matching the Name production appearing immediately
+ * on the input as a symbol, or null if no Name string is present.
+ * <p>
+ * <strong>Note:</strong> The Name characters are consumed.
+ * <p>
+ * <strong>Note:</strong> The string returned must be a symbol. The
+ * SymbolTable can be used for this purpose.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
+ *
+ * @see org.apache.xerces.util.SymbolTable
+ * @see org.apache.xerces.util.XMLChar#isName
+ * @see org.apache.xerces.util.XMLChar#isNameStart
+ */
public abstract String scanName() throws IOException, SAXException;
- public abstract boolean scanQName(QName qname) throws IOException, SAXException;
- public abstract int scanContent(XMLString content) throws IOException, SAXException;
- public abstract int scanAttContent(int quote, XMLString content) throws IOException, SAXException;
- public abstract boolean scanData(String delimiter, XMLString data) throws IOException, SAXException;
+
+ /**
+ * Scans a qualified name from the input, setting the fields of the
+ * QName structure appropriately.
+ * <p>
+ * <strong>Note:</strong> The qualified name characters are consumed.
+ * <p>
+ * <strong>Note:</strong> The strings used to set the values of the
+ * QName structure must be symbols. The SymbolTable can be used for
+ * this purpose.
+ *
+ * @param qname The qualified name structure to fill.
+ *
+ * @return Returns true if a qualified name appeared immediately on
+ * the input and was scanned, false otherwise.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
+ *
+ * @see org.apache.xerces.util.SymbolTable
+ * @see org.apache.xerces.util.XMLChar#isName
+ * @see org.apache.xerces.util.XMLChar#isNameStart
+ */
+ public abstract boolean scanQName(QName qname)
+ throws IOException, SAXException;
+
+ /**
+ * Scans a range of parsed character data, setting the fields of the
+ * XMLString structure, appropriately.
+ * <p>
+ * <strong>Note:</strong> The characters are consumed.
+ * <p>
+ * <strong>Note:</strong> This method does not guarantee to return
+ * the longest run of parsed character data. This method may return
+ * before markup due to reaching the end of the input buffer or any
+ * other reason.
+ * <p>
+ * <strong>Note:</strong> The fields contained in the XMLString
+ * structure are not guaranteed to remain valid upon subsequent calls
+ * to the entity scanner. Therefore, the caller is responsible for
+ * immediately using the returned character data or making a copy of
+ * the character data.
+ *
+ * @param content The content structure to fill.
+ *
+ * @return Returns the next character on the input, if known. This
+ * value may be -1 but this does <em>note</em> designate
+ * end of file.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
+ */
+ public abstract int scanContent(XMLString content)
+ throws IOException, SAXException;
+
+ /**
+ * Scans a range of attribute value data, setting the fields of the
+ * XMLString structure, appropriately.
+ * <p>
+ * <strong>Note:</strong> The characters are consumed.
+ * <p>
+ * <strong>Note:</strong> This method does not guarantee to return
+ * the longest run of attribute value data. This method may return
+ * before the quote character due to reaching the end of the input
+ * buffer or any other reason.
+ * <p>
+ * <strong>Note:</strong> The fields contained in the XMLString
+ * structure are not guaranteed to remain valid upon subsequent calls
+ * to the entity scanner. Therefore, the caller is responsible for
+ * immediately using the returned character data or making a copy of
+ * the character data.
+ *
+ * @param quote The quote character that signifies the end of the
+ * attribute value data.
+ * @param content The content structure to fill.
+ *
+ * @return Returns the next character on the input, if known. This
+ * value may be -1 but this does <em>note</em> designate
+ * end of file.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
+ */
+ public abstract int scanAttContent(int quote, XMLString content)
+ throws IOException, SAXException;
+
+ /**
+ * Scans a range of character data up to the specicied delimiter,
+ * setting the fields of the XMLString structure, appropriately.
+ * <p>
+ * <strong>Note:</strong> The characters are consumed.
+ * <p>
+ * <strong>Note:</strong> This assumes that the internal buffer is
+ * at least the same size, or bigger, than the length of the delimiter
+ * and that the delimiter contains at least one character.
+ * <p>
+ * <strong>Note:</strong> This method does not guarantee to return
+ * the longest run of character data. This method may return before
+ * the delimiter due to reaching the end of the input buffer or any
+ * other reason.
+ * <p>
+ * <strong>Note:</strong> The fields contained in the XMLString
+ * structure are not guaranteed to remain valid upon subsequent calls
+ * to the entity scanner. Therefore, the caller is responsible for
+ * immediately using the returned character data or making a copy of
+ * the character data.
+ *
+ * @param delimiter The string that signifies the end of the character
+ * data to be scanned.
+ * @param data The data structure to fill.
+ *
+ * @return Returns true if there is more data to scan, false otherwise.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
+ */
+ public abstract boolean scanData(String delimiter, XMLString data)
+ throws IOException, SAXException;
+
+ /**
+ * Skips a character appearing immediately on the input.
+ * <p>
+ * <strong>Note:</strong> The character is consumed only if it matches
+ * the specified character.
+ *
+ * @param c The character to skip.
+ *
+ * @return Returns true if the character was skipped.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
+ */
public abstract boolean skipChar(int c) throws IOException, SAXException;
+
+ /**
+ * Skips space characters appearing immediately on the input.
+ * <p>
+ * <strong>Note:</strong> The characters are consumed only if they are
+ * space characters.
+ *
+ * @return Returns true if at least one space character was skipped.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
+ *
+ * @see org.apache.xerces.util.XMLChar#isSpace
+ */
public abstract boolean skipSpaces() throws IOException, SAXException;
- public abstract boolean skipString(String s) throws IOException, SAXException;
+
+ /**
+ * Skips the specified string appearing immediately on the input.
+ * <p>
+ * <strong>Note:</strong> The characters are consumed only if they are
+ * space characters.
+ *
+ * @param s The string to skip.
+ *
+ * @return Returns true if the string was skipped.
+ *
+ * @throws IOException Thrown if i/o error occurs.
+ * @throws EOFException Thrown on end of file.
+ * @throws SAXException Thrown by entity handler to signal an error
+ * when the end of an entity is reached.
+ */
+ public abstract boolean skipString(String s)
+ throws IOException, SAXException;
} // class XMLEntityScanner