From bb7c119dff783eb5b77f81069cd6a63c1476a875 Mon Sep 17 00:00:00 2001 From: singingbush Date: Tue, 2 Dec 2025 22:50:31 +0000 Subject: [PATCH 1/2] [XERCES-1781] Javadoc changes for AbstractSAXParser --- .../xerces/parsers/AbstractSAXParser.java | 505 ++++++++++-------- 1 file changed, 274 insertions(+), 231 deletions(-) diff --git a/src/org/apache/xerces/parsers/AbstractSAXParser.java b/src/org/apache/xerces/parsers/AbstractSAXParser.java index ef8257931..3e3dbc1d7 100644 --- a/src/org/apache/xerces/parsers/AbstractSAXParser.java +++ b/src/org/apache/xerces/parsers/AbstractSAXParser.java @@ -205,7 +205,12 @@ public abstract class AbstractSAXParser // Constructors // - /** Default constructor. */ + /** + * Default constructor. + * Constructs a SAX parser using the default properties and features. + * + * @param config a parser configuration from which properties and features can be retrieved + */ protected AbstractSAXParser(XMLParserConfiguration config) { super(config); @@ -227,29 +232,24 @@ protected AbstractSAXParser(XMLParserConfiguration config) { /** * The start of the document. * - * @param locator The document locator, or null if the document - * location cannot be reported during the parsing - * of this document. However, it is strongly - * recommended that a locator be supplied that can - * at least report the system identifier of the - * document. - * @param encoding The auto-detected IANA encoding name of the entity - * stream. This value will be null in those situations - * where the entity encoding is not auto-detected (e.g. - * internal entities or a document entity that is - * parsed from a java.io.Reader). - * @param namespaceContext - * The namespace context in effect at the - * start of this document. - * This object represents the current context. - * Implementors of this class are responsible - * for copying the namespace bindings from the - * the current context (and its parent contexts) - * if that information is important. - * @param augs Additional information that may include infoset augmentations + * @param locator the document locator, or null if the document location cannot be + * reported during the parsing of this document. However, it is + * strongly recommended that a locator be supplied that + * can at least report the system identifier of the document. + * @param encoding the auto-detected IANA encoding name of the entity stream. + * This value will be null in those situations where the entity + * encoding is not auto-detected (e.g. internal entities or a + * document entity that is parsed from a java.io.Reader). + * @param namespaceContext the namespace context in effect at the start of this + * document. This object represents the current context. Implementors + * of this class are responsible for copying the namespace bindings + * from the current context (and its parent contexts) if that + * information is important. + * @param augs additional information that may include infoset augmentations * * @throws XNIException Thrown by handler to signal an error. */ + @Override public void startDocument(XMLLocator locator, String encoding, NamespaceContext namespaceContext, Augmentations augs) throws XNIException { @@ -291,15 +291,15 @@ public void startDocument(XMLLocator locator, String encoding, * Notifies of the presence of an XMLDecl line in the document. If * present, this method will be called immediately following the * startDocument call. - * - * @param version The XML version. - * @param encoding The IANA encoding name of the document, or null if - * not specified. - * @param standalone The standalone value, or null if not specified. - * @param augs Additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @param version the XML version + * @param encoding the IANA encoding name of the document, or null + * @param standalone the standalone value, or null + * @param augs additional information that may include infoset augmentations + * + * @throws XNIException thrown by handler to signal an error */ + @Override public void xmlDecl(String version, String encoding, String standalone, Augmentations augs) throws XNIException { // the version need only be set once; if @@ -311,15 +311,15 @@ public void xmlDecl(String version, String encoding, String standalone, Augmenta /** * Notifies of the presence of the DOCTYPE line in the document. * - * @param rootElement The name of the root element. - * @param publicId The public identifier if an external DTD or null - * if the external DTD is specified using SYSTEM. - * @param systemId The system identifier if an external DTD, null - * otherwise. - * @param augs Additional information that may include infoset augmentations + * @param rootElement the name of the root element + * @param publicId the public identifier if an external DTD or null if the + * external DTD is specified using SYSTEM + * @param systemId the system identifier if an external DTD, otherwise null + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @throws XNIException thrown by handler to signal an error */ + @Override public void doctypeDecl(String rootElement, String publicId, String systemId, Augmentations augs) throws XNIException { @@ -342,7 +342,7 @@ public void doctypeDecl(String rootElement, } // doctypeDecl(String,String,String) - /** + /** * This method notifies of the start of an entity. The DTD has the * pseudo-name of "[dtd]" parameter entity names start with '%'; and * general entity names are just the entity name. @@ -356,16 +356,17 @@ public void doctypeDecl(String rootElement, * Note: This method is not called for entity references * appearing as part of attribute values. * - * @param name The name of the entity. - * @param identifier The resource identifier. - * @param encoding The auto-detected IANA encoding name of the entity - * stream. This value will be null in those situations - * where the entity encoding is not auto-detected (e.g. - * internal parameter entities). - * @param augs Additional information that may include infoset augmentations + * @param name the name of the entity + * @param identifier the resource identifier + * @param encoding the auto-detected IANA encoding name of the entity stream. + * This value will be null in those situations where the entity + * encoding is not auto-detected (e.g. internal parameter entities). * - * @throws XNIException Thrown by handler to signal an error. + * @param augs additional information that may include infoset augmentations + * + * @throws XNIException thrown by handler to signal an error */ + @Override public void startGeneralEntity(String name, XMLResourceIdentifier identifier, String encoding, Augmentations augs) throws XNIException { @@ -405,11 +406,12 @@ public void startGeneralEntity(String name, XMLResourceIdentifier identifier, * Note: This method is not called for entity references * appearing as part of attribute values. * - * @param name The name of the entity. - * @param augs Additional information that may include infoset augmentations + * @param name the name of the entity + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @throws XNIException thrown by handler to signal an error */ + @Override public void endGeneralEntity(String name, Augmentations augs) throws XNIException { try { @@ -427,17 +429,18 @@ public void endGeneralEntity(String name, Augmentations augs) throws XNIExceptio } // endEntity(String) - /** + /** * The start of an element. If the document specifies the start element * by using an empty tag, then the startElement method will immediately * be followed by the endElement method, with no intervening methods. * - * @param element The name of the element. - * @param attributes The element attributes. - * @param augs Additional information that may include infoset augmentations + * @param element the name of the element + * @param attributes the element attributes + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @throws XNIException thrown by handler to signal an error */ + @Override public void startElement(QName element, XMLAttributes attributes, Augmentations augs) throws XNIException { @@ -508,11 +511,12 @@ else if (!fXMLNSURIs) { /** * Character content. * - * @param text The content. - * @param augs Additional information that may include infoset augmentations + * @param text the content + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @throws XNIException thrown by handler to signal an error */ + @Override public void characters(XMLString text, Augmentations augs) throws XNIException { // if type is union (XML Schema) it is possible that we receive @@ -549,11 +553,12 @@ public void characters(XMLString text, Augmentations augs) throws XNIException { * characters in the document are ignorable based on the element * content model. * - * @param text The ignorable whitespace. - * @param augs Additional information that may include infoset augmentations + * @param text the ignorable whitespace + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @throws XNIException thrown by handler to signal an error */ + @Override public void ignorableWhitespace(XMLString text, Augmentations augs) throws XNIException { try { @@ -576,14 +581,13 @@ public void ignorableWhitespace(XMLString text, Augmentations augs) throws XNIEx /** * The end of an element. * - * @param element The name of the element. - * @param augs Additional information that may include infoset augmentations + * @param element the name of the element + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @throws XNIException thrown by handler to signal an error */ + @Override public void endElement(QName element, Augmentations augs) throws XNIException { - - try { // SAX1 if (fDocumentHandler != null) { @@ -608,12 +612,14 @@ public void endElement(QName element, Augmentations augs) throws XNIException { } // endElement(QName) - /** + /** * The start of a CDATA section. - * @param augs Additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @param augs additional information that may include infoset augmentations + * + * @throws XNIException thrown by handler to signal an error */ + @Override public void startCDATA(Augmentations augs) throws XNIException { try { @@ -630,9 +636,10 @@ public void startCDATA(Augmentations augs) throws XNIException { /** * The end of a CDATA section. - * @param augs Additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @param augs additional information that may include infoset augmentations + * + * @throws XNIException thrown by handler to signal an error */ public void endCDATA(Augmentations augs) throws XNIException { @@ -651,11 +658,12 @@ public void endCDATA(Augmentations augs) throws XNIException { /** * A comment. * - * @param text The text in the comment. - * @param augs Additional information that may include infoset augmentations + * @param text the text in the comment + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by application to signal an error. + * @throws XNIException thrown by application to signal an error */ + @Override public void comment(XMLString text, Augmentations augs) throws XNIException { try { @@ -681,12 +689,13 @@ public void comment(XMLString text, Augmentations augs) throws XNIException { * to the application as anything other than text. The application is * responsible for parsing the data. * - * @param target The target. - * @param data The data or null if none specified. - * @param augs Additional information that may include infoset augmentations + * @param target the target + * @param data the data or null if none specified + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @throws XNIException thrown by handler to signal an error */ + @Override public void processingInstruction(String target, XMLString data, Augmentations augs) throws XNIException { @@ -717,10 +726,12 @@ public void processingInstruction(String target, XMLString data, Augmentations a /** * The end of the document. - * @param augs Additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @param augs additional information that may include infoset augmentations + * + * @throws XNIException thrown by handler to signal an error */ + @Override public void endDocument(Augmentations augs) throws XNIException { try { @@ -747,11 +758,11 @@ public void endDocument(Augmentations augs) throws XNIException { /** * The start of the DTD external subset. * - * @param augs Additional information that may include infoset - * augmentations. + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @throws XNIException thrown by handler to signal an error */ + @Override public void startExternalSubset(XMLResourceIdentifier identifier, Augmentations augs) throws XNIException { startParameterEntity("[dtd]", null, null, augs); @@ -760,11 +771,11 @@ public void startExternalSubset(XMLResourceIdentifier identifier, /** * The end of the DTD external subset. * - * @param augs Additional information that may include infoset - * augmentations. + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @throws XNIException thrown by handler to signal an error */ + @Override public void endExternalSubset(Augmentations augs) throws XNIException { endParameterEntity("[dtd]", augs); } @@ -783,17 +794,16 @@ public void endExternalSubset(Augmentations augs) throws XNIException { * Note: This method is not called for entity references * appearing as part of attribute values. * - * @param name The name of the parameter entity. - * @param identifier The resource identifier. - * @param encoding The auto-detected IANA encoding name of the entity - * stream. This value will be null in those situations - * where the entity encoding is not auto-detected (e.g. - * internal parameter entities). - * @param augs Additional information that may include infoset - * augmentations. + * @param name the name of the parameter entity + * @param identifier the resource identifier + * @param encoding the auto-detected IANA encoding name of the entity stream. + * This value will be null in those situations where the entity + * encoding is not auto-detected (e.g. internal parameter entities). + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @throws XNIException thrown by handler to signal an error */ + @Override public void startParameterEntity(String name, XMLResourceIdentifier identifier, String encoding, Augmentations augs) @@ -834,12 +844,12 @@ public void startParameterEntity(String name, * Note: This method is not called for entity references * appearing as part of attribute values. * - * @param name The name of the parameter entity. - * @param augs Additional information that may include infoset - * augmentations. + * @param name the name of the parameter entity + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @throws XNIException thrown by handler to signal an error */ + @Override public void endParameterEntity(String name, Augmentations augs) throws XNIException { try { @@ -860,14 +870,13 @@ public void endParameterEntity(String name, Augmentations augs) throws XNIExcept /** * An element declaration. * - * @param name The name of the element. - * @param contentModel The element content model. - * - * @param augs Additional information that may include infoset - * augmentations. + * @param name the name of the element + * @param contentModel the element content model + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @throws XNIException thrown by handler to signal an error */ + @Override public void elementDecl(String name, String contentModel, Augmentations augs) throws XNIException { @@ -886,29 +895,24 @@ public void elementDecl(String name, String contentModel, Augmentations augs) /** * An attribute declaration. * - * @param elementName The name of the element that this attribute - * is associated with. - * @param attributeName The name of the attribute. - * @param type The attribute type. This value will be one of - * the following: "CDATA", "ENTITY", "ENTITIES", - * "ENUMERATION", "ID", "IDREF", "IDREFS", - * "NMTOKEN", "NMTOKENS", or "NOTATION". - * @param enumeration If the type has the value "ENUMERATION" or - * "NOTATION", this array holds the allowed attribute - * values; otherwise, this array is null. - * @param defaultType The attribute default type. This value will be - * one of the following: "#FIXED", "#IMPLIED", - * "#REQUIRED", or null. - * @param defaultValue The attribute default value, or null if no - * default value is specified. - * - * @param nonNormalizedDefaultValue The attribute default value with no normalization - * performed, or null if no default value is specified. - * @param augs Additional information that may include infoset - * augmentations. - * - * @throws XNIException Thrown by handler to signal an error. + * @param elementName the name of the element that this attribute is associated with + * @param attributeName the name of the attribute + * @param type the attribute type. This value will be one of the following: + * "CDATA", "ENTITY", "ENTITIES", "ENUMERATION", "ID", "IDREF", + * "IDREFS", "NMTOKEN", "NMTOKENS", or "NOTATION". + * @param enumeration if the type has the value "ENUMERATION" or "NOTATION", + * this array holds the allowed attribute values, otherwise null + * @param defaultType the attribute default type. This value will be one of the following: + * "#FIXED", "#IMPLIED", "#REQUIRED", or null. + * @param defaultValue the attribute default value, or null if no default value is specified + * + * @param nonNormalizedDefaultValue the attribute default value with no normalization + * performed, or null if no default value is specified. + * @param augs additional information that may include infoset augmentations + * + * @throws XNIException thrown by handler to signal an error */ + @Override public void attributeDecl(String elementName, String attributeName, String type, String[] enumeration, String defaultType, XMLString defaultValue, @@ -958,20 +962,18 @@ public void attributeDecl(String elementName, String attributeName, /** * An internal entity declaration. * - * @param name The name of the entity. Parameter entity names start with - * '%', whereas the name of a general entity is just the - * entity name. - * @param text The value of the entity. - * @param nonNormalizedText The non-normalized value of the entity. This - * value contains the same sequence of characters that was in - * the internal entity declaration, without any entity - * references expanded. + * @param name the name of the entity. Parameter entity names start with '%', + * whereas the name of a general entity is just the entity name. + * @param text the value of the entity + * @param nonNormalizedText the non-normalized value of the entity. This value + * contains the same sequence of characters that was in the internal + * entity declaration, without any entity references expanded. * - * @param augs Additional information that may include infoset - * augmentations. + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @throws XNIException thrown by handler to signal an error */ + @Override public void internalEntityDecl(String name, XMLString text, XMLString nonNormalizedText, Augmentations augs) throws XNIException { @@ -991,16 +993,14 @@ public void internalEntityDecl(String name, XMLString text, /** * An external entity declaration. * - * @param name The name of the entity. Parameter entity names start - * with '%', whereas the name of a general entity is just - * the entity name. - * @param identifier An object containing all location information - * pertinent to this entity. - * @param augs Additional information that may include infoset - * augmentations. + * @param name the name of the entity. Parameter entity names start with '%', + * whereas the name of a general entity is just the entity name. + * @param identifier an object containing all location information pertinent to this entity + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @throws XNIException thrown by handler to signal an error */ + @Override public void externalEntityDecl(String name, XMLResourceIdentifier identifier, Augmentations augs) throws XNIException { try { @@ -1021,16 +1021,14 @@ public void externalEntityDecl(String name, XMLResourceIdentifier identifier, /** * An unparsed entity declaration. * - * @param name The name of the entity. - * @param identifier An object containing all location information - * pertinent to this entity. - * @param notation The name of the notation. - * - * @param augs Additional information that may include infoset - * augmentations. + * @param name the name of the notation + * @param identifier an object containing all location information pertinent to this notation + * @param notation the name of the notation + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @throws XNIException thrown by handler to signal an error */ + @Override public void unparsedEntityDecl(String name, XMLResourceIdentifier identifier, String notation, Augmentations augs) throws XNIException { @@ -1050,16 +1048,15 @@ public void unparsedEntityDecl(String name, XMLResourceIdentifier identifier, } // unparsedEntityDecl(String,XMLResourceIdentifier, String, Augmentations) /** - * A notation declaration + * A notation declaration. * - * @param name The name of the notation. - * @param identifier An object containing all location information - * pertinent to this notation. - * @param augs Additional information that may include infoset - * augmentations. + * @param name the name of the notation + * @param identifier an object containing all location information pertinent to this notation + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @throws XNIException thrown by handler to signal an error */ + @Override public void notationDecl(String name, XMLResourceIdentifier identifier, Augmentations augs) throws XNIException { try { @@ -1080,11 +1077,11 @@ public void notationDecl(String name, XMLResourceIdentifier identifier, /** * The end of the DTD. * - * @param augs Additional information that may include infoset - * augmentations. + * @param augs additional information that may include infoset augmentations * - * @throws XNIException Thrown by handler to signal an error. + * @throws XNIException thrown by handler to signal an error */ + @Override public void endDTD(Augmentations augs) throws XNIException { fInDTD = false; @@ -1116,11 +1113,12 @@ public void endDTD(Augmentations augs) throws XNIException { * parse(new InputSource(systemId)); * * - * @param systemId The system identifier (URI). + * @param systemId the system identifier (URI) * - * @exception org.xml.sax.SAXException Throws exception on SAX error. - * @exception java.io.IOException Throws exception on i/o error. + * @throws org.xml.sax.SAXException any SAX exception, possibly wrapping another exception + * @throws java.io.IOException if an IO error occurs while parsing the input source */ + @Override public void parse(String systemId) throws SAXException, IOException { // parse document @@ -1176,13 +1174,14 @@ public void parse(String systemId) throws SAXException, IOException { } // parse(String) /** - * parse + * Parse an XML document. * - * @param inputSource + * @param inputSource the input source for the top-level of the XML document * - * @exception org.xml.sax.SAXException - * @exception java.io.IOException + * @throws org.xml.sax.SAXException any SAX exception, possibly wrapping another exception + * @throws java.io.IOException if an IO error occurs while parsing the input source */ + @Override public void parse(InputSource inputSource) throws SAXException, IOException { @@ -1248,9 +1247,10 @@ public void parse(InputSource inputSource) * Sets the resolver used to resolve external entities. The EntityResolver * interface supports resolution of public and system identifiers. * - * @param resolver The new entity resolver. Passing a null value will - * uninstall the currently installed resolver. + * @param resolver the new entity resolver. Passing a null value will + * uninstall the currently installed resolver */ + @Override public void setEntityResolver(EntityResolver resolver) { try { @@ -1285,10 +1285,10 @@ public void setEntityResolver(EntityResolver resolver) { /** * Return the current entity resolver. * - * @return The current entity resolver, or null if none - * has been registered. + * @return the current entity resolver, or null if none has been registered * @see #setEntityResolver */ + @Override public EntityResolver getEntityResolver() { EntityResolver entityResolver = null; @@ -1329,6 +1329,7 @@ else if (xmlEntityResolver instanceof EntityResolver2Wrapper) { * @param errorHandler The error handler. * @see #getErrorHandler */ + @Override public void setErrorHandler(ErrorHandler errorHandler) { try { @@ -1351,10 +1352,10 @@ public void setErrorHandler(ErrorHandler errorHandler) { /** * Return the current error handler. * - * @return The current error handler, or null if none - * has been registered. + * @return the current error handler, or null if none has been registered * @see #setErrorHandler */ + @Override public ErrorHandler getErrorHandler() { ErrorHandler errorHandler = null; @@ -1382,6 +1383,7 @@ public ErrorHandler getErrorHandler() { * * @see org.xml.sax.Parser#setLocale(Locale) */ + @Override public void setLocale(Locale locale) throws SAXException { //REVISIT:this methods is not part of SAX2 interfaces, we should throw exception //if any application uses SAX2 and sets locale also. -nb @@ -1403,6 +1405,7 @@ public void setLocale(Locale locale) throws SAXException { * * @see #getDTDHandler */ + @Override public void setDTDHandler(DTDHandler dtdHandler) { fDTDHandler = dtdHandler; } // setDTDHandler(DTDHandler) @@ -1423,8 +1426,9 @@ public void setDTDHandler(DTDHandler dtdHandler) { * middle of a parse, and the SAX parser must begin using the new * handler immediately. * - * @param documentHandler The document handler. + * @param documentHandler the document handler */ + @Override public void setDocumentHandler(DocumentHandler documentHandler) { fDocumentHandler = documentHandler; } // setDocumentHandler(DocumentHandler) @@ -1444,10 +1448,11 @@ public void setDocumentHandler(DocumentHandler documentHandler) { * middle of a parse, and the SAX parser must begin using the new * handler immediately. * - * @param contentHandler The content handler. + * @param contentHandler the content handler * * @see #getContentHandler */ + @Override public void setContentHandler(ContentHandler contentHandler) { fContentHandler = contentHandler; } // setContentHandler(ContentHandler) @@ -1455,11 +1460,11 @@ public void setContentHandler(ContentHandler contentHandler) { /** * Return the current content handler. * - * @return The current content handler, or null if none - * has been registered. + * @return the current content handler, or null if none has been registered * * @see #setContentHandler */ + @Override public ContentHandler getContentHandler() { return fContentHandler; } // getContentHandler():ContentHandler @@ -1467,10 +1472,10 @@ public ContentHandler getContentHandler() { /** * Return the current DTD handler. * - * @return The current DTD handler, or null if none - * has been registered. + * @return the current DTD handler, or null if none has been registered * @see #setDTDHandler */ + @Override public DTDHandler getDTDHandler() { return fDTDHandler; } // getDTDHandler():DTDHandler @@ -1480,15 +1485,14 @@ public DTDHandler getDTDHandler() { * might not recognize the feature, and if it does recognize * it, it might not be able to fulfill the request. * - * @param featureId The unique identifier (URI) of the feature. - * @param state The requested state of the feature (true or false). + * @param featureId the unique identifier (URI) of the feature + * @param state the requested state of the feature (true or false) * - * @exception SAXNotRecognizedException If the - * requested feature is not known. - * @exception SAXNotSupportedException If the - * requested feature is known, but the requested - * state is not supported. + * @throws SAXNotRecognizedException if the requested feature is not known + * @throws SAXNotSupportedException if the requested feature is known, + * but the requested state is not supported */ + @Override public void setFeature(String featureId, boolean state) throws SAXNotRecognizedException, SAXNotSupportedException { @@ -1665,17 +1669,15 @@ else if (featureId.startsWith(XERCES_FEATURES_PREFIX)) { /** * Query the state of a feature. * - * Query the current state of any feature in a SAX2 parser. The - * parser might not recognize the feature. + *

Query the current state of any feature in a SAX2 parser. The + * parser might not recognize the feature.

* - * @param featureId The unique identifier (URI) of the feature - * being set. - * @return The current state of the feature. - * @exception org.xml.sax.SAXNotRecognizedException If the - * requested feature is not known. - * @exception SAXNotSupportedException If the - * requested feature is known but not supported. + * @param featureId the unique identifier (URI) of the feature being set + * @return the current state of the feature + * @throws SAXNotRecognizedException if the requested feature is not known + * @throws SAXNotSupportedException if the requested feature is known but not supported */ + @Override public boolean getFeature(String featureId) throws SAXNotRecognizedException, SAXNotSupportedException { @@ -1823,16 +1825,14 @@ else if (featureId.startsWith(XERCES_FEATURES_PREFIX)) { * might not recognize the property, and if it does recognize * it, it might not support the requested value. * - * @param propertyId The unique identifier (URI) of the property - * being set. - * @param value The value to which the property is being set. + * @param propertyId the unique identifier (URI) of the property being set + * @param value the value to which the property is being set * - * @exception SAXNotRecognizedException If the - * requested property is not known. - * @exception SAXNotSupportedException If the - * requested property is known, but the requested - * value is not supported. + * @throws SAXNotRecognizedException if the requested property is not known + * @throws SAXNotSupportedException if the requested property is known, + * but the requested value is not supported */ + @Override public void setProperty(String propertyId, Object value) throws SAXNotRecognizedException, SAXNotSupportedException { @@ -1944,17 +1944,15 @@ else if (propertyId.startsWith(XERCES_PROPERTIES_PREFIX)) { /** * Query the value of a property. * - * Return the current value of a property in a SAX2 parser. - * The parser might not recognize the property. + *

Return the current value of a property in a SAX2 parser. + * The parser might not recognize the property.

* - * @param propertyId The unique identifier (URI) of the property - * being set. - * @return The current value of the property. - * @exception org.xml.sax.SAXNotRecognizedException If the - * requested property is not known. - * @exception SAXNotSupportedException If the - * requested property is known but not supported. + * @param propertyId the unique identifier (URI) of the property being set + * @return the current value of the property + * @throws SAXNotRecognizedException if the requested property is not known + * @throws SAXNotSupportedException if the requested property is known but not supported */ + @Override public Object getProperty(String propertyId) throws SAXNotRecognizedException, SAXNotSupportedException { @@ -2070,7 +2068,8 @@ else if (propertyId.startsWith(XERCES_PROPERTIES_PREFIX)) { * * * @param handler The new handler. - * + * @throws SAXNotRecognizedException not thrown by the abstract SAX parser + * @throws SAXNotSupportedException if parse in progress * @see #getDeclHandler * @see #setProperty */ @@ -2090,6 +2089,9 @@ protected void setDeclHandler(DeclHandler handler) /** * Returns the DTD declaration event handler. * + * @return the DTD declaration handler + * @throws SAXNotRecognizedException not thrown by the abstract SAX parser + * @throws SAXNotSupportedException not thrown by the abstract SAX parser * @see #setDeclHandler */ protected DeclHandler getDeclHandler() @@ -2106,7 +2108,8 @@ protected DeclHandler getDeclHandler() * * * @param handler lexical event handler - * + * @throws SAXNotRecognizedException not thrown by the abstract SAX parser + * @throws SAXNotSupportedException if parse in progress * @see #getLexicalHandler * @see #setProperty */ @@ -2127,6 +2130,9 @@ protected void setLexicalHandler(LexicalHandler handler) * Returns the lexical handler. * * @see #setLexicalHandler + * @return the lexical handler + * @throws SAXNotRecognizedException not thrown by the abstract SAX parser + * @throws SAXNotSupportedException not thrown by the abstract SAX parser */ protected LexicalHandler getLexicalHandler() throws SAXNotRecognizedException, SAXNotSupportedException { @@ -2134,7 +2140,9 @@ protected LexicalHandler getLexicalHandler() } // getLexicalHandler():LexicalHandler /** - * Send startPrefixMapping events + * Send startPrefixMapping events. + * + * @throws SAXException if an error occurs */ protected final void startNamespaceMapping() throws SAXException{ int count = fNamespaceContext.getDeclaredPrefixCount(); @@ -2151,7 +2159,9 @@ protected final void startNamespaceMapping() throws SAXException{ } /** - * Send endPrefixMapping events + * Send endPrefixMapping events. + * + * @throws SAXException if an error occurs */ protected final void endNamespaceMapping() throws SAXException { int count = fNamespaceContext.getDeclaredPrefixCount(); @@ -2165,7 +2175,7 @@ protected final void endNamespaceMapping() throws SAXException { // // XMLDocumentParser methods // - + @Override public void reset() throws XNIException { super.reset(); @@ -2199,7 +2209,11 @@ protected static final class LocatorProxy // Constructors // - /** Constructs an XML locator proxy. */ + /** + * Constructs an XML locator proxy. + * + * @param locator an XML locator + */ public LocatorProxy(XMLLocator locator) { fLocator = locator; } @@ -2209,37 +2223,43 @@ public LocatorProxy(XMLLocator locator) { // /** Public identifier. */ + @Override public String getPublicId() { return fLocator.getPublicId(); } /** System identifier. */ + @Override public String getSystemId() { return fLocator.getExpandedSystemId(); } + /** Line number. */ + @Override public int getLineNumber() { return fLocator.getLineNumber(); } /** Column number. */ + @Override public int getColumnNumber() { return fLocator.getColumnNumber(); } // Locator2 methods + @Override public String getXMLVersion() { return fLocator.getXMLVersion(); } + @Override public String getEncoding() { return fLocator.getEncoding(); } } // class LocatorProxy - protected static final class AttributesProxy - implements AttributeList, Attributes2 { + protected static final class AttributesProxy implements AttributeList, Attributes2 { // // Data @@ -2252,23 +2272,31 @@ protected static final class AttributesProxy // Public methods // - /** Sets the XML attributes. */ + /** + * Sets the XML attributes. + * + * @param attributes the XML attributes + */ public void setAttributes(XMLAttributes attributes) { fAttributes = attributes; } // setAttributes(XMLAttributes) + @Override public int getLength() { return fAttributes.getLength(); } + @Override public String getName(int i) { return fAttributes.getQName(i); } + @Override public String getQName(int index) { return fAttributes.getQName(index); } + @Override public String getURI(int index) { // REVISIT: this hides the fact that internally we use // null instead of empty string @@ -2277,47 +2305,57 @@ public String getURI(int index) { return uri != null ? uri : ""; } + @Override public String getLocalName(int index) { return fAttributes.getLocalName(index); } + @Override public String getType(int i) { return fAttributes.getType(i); } + @Override public String getType(String name) { return fAttributes.getType(name); } + @Override public String getType(String uri, String localName) { return uri.length() == 0 ? fAttributes.getType(null, localName) : fAttributes.getType(uri, localName); } + @Override public String getValue(int i) { return fAttributes.getValue(i); } + @Override public String getValue(String name) { return fAttributes.getValue(name); } + @Override public String getValue(String uri, String localName) { return uri.length() == 0 ? fAttributes.getValue(null, localName) : fAttributes.getValue(uri, localName); } + @Override public int getIndex(String qName) { return fAttributes.getIndex(qName); } + @Override public int getIndex(String uri, String localPart) { return uri.length() == 0 ? fAttributes.getIndex(null, localPart) : fAttributes.getIndex(uri, localPart); } - + // Attributes2 methods // REVISIT: Localize exception messages. -- mrglavas + @Override public boolean isDeclared(int index) { if (index < 0 || index >= fAttributes.getLength()) { throw new ArrayIndexOutOfBoundsException(index); @@ -2326,7 +2364,8 @@ public boolean isDeclared(int index) { fAttributes.getAugmentations(index).getItem( Constants.ATTRIBUTE_DECLARED)); } - + + @Override public boolean isDeclared(String qName) { int index = getIndex(qName); if (index == -1) { @@ -2336,7 +2375,8 @@ public boolean isDeclared(String qName) { fAttributes.getAugmentations(index).getItem( Constants.ATTRIBUTE_DECLARED)); } - + + @Override public boolean isDeclared(String uri, String localName) { int index = getIndex(uri, localName); if (index == -1) { @@ -2346,14 +2386,16 @@ public boolean isDeclared(String uri, String localName) { fAttributes.getAugmentations(index).getItem( Constants.ATTRIBUTE_DECLARED)); } - + + @Override public boolean isSpecified(int index) { if (index < 0 || index >= fAttributes.getLength()) { throw new ArrayIndexOutOfBoundsException(index); } return fAttributes.isSpecified(index); } - + + @Override public boolean isSpecified(String qName) { int index = getIndex(qName); if (index == -1) { @@ -2361,7 +2403,8 @@ public boolean isSpecified(String qName) { } return fAttributes.isSpecified(index); } - + + @Override public boolean isSpecified(String uri, String localName) { int index = getIndex(uri, localName); if (index == -1) { @@ -2375,17 +2418,17 @@ public boolean isSpecified(String uri, String localName) { // PSVIProvider methods + @Override public ElementPSVI getElementPSVI(){ return (fAugmentations != null)?(ElementPSVI)fAugmentations.getItem(Constants.ELEMENT_PSVI):null; } - + @Override public AttributePSVI getAttributePSVI(int index){ - return (AttributePSVI)fAttributesProxy.fAttributes.getAugmentations(index).getItem(Constants.ATTRIBUTE_PSVI); } - + @Override public AttributePSVI getAttributePSVIByName(String uri, String localname){ return (AttributePSVI)fAttributesProxy.fAttributes.getAugmentations(uri, localname).getItem(Constants.ATTRIBUTE_PSVI); From faa459c7b21c8e4bd2b093c959e9e12ab67797ea Mon Sep 17 00:00:00 2001 From: singingbush Date: Wed, 3 Dec 2025 19:09:23 +0000 Subject: [PATCH 2/2] [XERCES-1781] Javadoc changes for AbstractSAXParser --- src/org/apache/xerces/parsers/AbstractSAXParser.java | 1 - 1 file changed, 1 deletion(-) diff --git a/src/org/apache/xerces/parsers/AbstractSAXParser.java b/src/org/apache/xerces/parsers/AbstractSAXParser.java index 3e3dbc1d7..aa0f24d26 100644 --- a/src/org/apache/xerces/parsers/AbstractSAXParser.java +++ b/src/org/apache/xerces/parsers/AbstractSAXParser.java @@ -206,7 +206,6 @@ public abstract class AbstractSAXParser // /** - * Default constructor. * Constructs a SAX parser using the default properties and features. * * @param config a parser configuration from which properties and features can be retrieved