diff --git a/make/Docs.gmk b/make/Docs.gmk index 748429da409..19e962b79af 100644 --- a/make/Docs.gmk +++ b/make/Docs.gmk @@ -298,6 +298,8 @@ define SetupApiDocsGenerationBody # Create a string like "-Xdoclint:all,-syntax,-html,..." $1_OPTIONS += -Xdoclint:all,$$(call CommaList, $$(addprefix -, \ $$(JAVADOC_DISABLED_DOCLINT))) + # Ignore the doclint warnings in the W3C DOM package + $1_OPTIONS += -Xdoclint/package:-org.w3c.* $1_DOC_TITLE := $$($1_LONG_NAME)
Version $$(VERSION_SPECIFICATION) API \ Specification diff --git a/src/java.xml/share/classes/javax/xml/stream/FactoryConfigurationError.java b/src/java.xml/share/classes/javax/xml/stream/FactoryConfigurationError.java index 2351f59c406..e882914b622 100644 --- a/src/java.xml/share/classes/javax/xml/stream/FactoryConfigurationError.java +++ b/src/java.xml/share/classes/javax/xml/stream/FactoryConfigurationError.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -36,6 +36,9 @@ package javax.xml.stream; public class FactoryConfigurationError extends Error { private static final long serialVersionUID = -2994412584589975744L; + /** + * The nested exception. + */ Exception nested; /** diff --git a/src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java b/src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java index 1b10d6b5ee5..00b163f9227 100644 --- a/src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java +++ b/src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -45,11 +45,15 @@ import javax.xml.stream.events.*; * @since 1.6 */ public abstract class XMLEventFactory { - protected XMLEventFactory(){} - static final String JAXPFACTORYID = "javax.xml.stream.XMLEventFactory"; static final String DEFAULIMPL = "com.sun.xml.internal.stream.events.XMLEventFactoryImpl"; + /** + * Protected constructor to prevent instantiation. + * Use {@link #newFactory()} instead. + */ + protected XMLEventFactory(){} + /** * Creates a new instance of the {@code XMLEventFactory} builtin * system-default implementation. @@ -66,6 +70,8 @@ public abstract class XMLEventFactory { /** * Creates a new instance of the factory in exactly the same manner as the * {@link #newFactory()} method. + * + * @return an instance of the {@code XMLEventFactory} * @throws FactoryConfigurationError if an instance of this factory cannot be loaded */ public static XMLEventFactory newInstance() @@ -126,6 +132,7 @@ public abstract class XMLEventFactory { * Once an application has obtained a reference to a XMLEventFactory it * can use the factory to configure and obtain stream instances. * + * @return an instance of the {@code XMLEventFactory} * @throws FactoryConfigurationError in case of {@linkplain * java.util.ServiceConfigurationError service configuration error} or if * the implementation is not available or cannot be instantiated. @@ -474,9 +481,9 @@ public abstract class XMLEventFactory { public abstract EntityReference createEntityReference(String name, EntityDeclaration declaration); /** - * Create a comment + * Create a comment. * @param text The text of the comment - * a Comment event + * @return a Comment event */ public abstract Comment createComment(String text); diff --git a/src/java.xml/share/classes/javax/xml/stream/XMLEventReader.java b/src/java.xml/share/classes/javax/xml/stream/XMLEventReader.java index d20fe24bb87..93d2779d400 100644 --- a/src/java.xml/share/classes/javax/xml/stream/XMLEventReader.java +++ b/src/java.xml/share/classes/javax/xml/stream/XMLEventReader.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -68,7 +68,7 @@ public interface XMLEventReader extends Iterator { * * @return the next XMLEvent * @see XMLEvent - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public XMLEvent peek() throws XMLStreamException; diff --git a/src/java.xml/share/classes/javax/xml/stream/XMLEventWriter.java b/src/java.xml/share/classes/javax/xml/stream/XMLEventWriter.java index 54656d52c2e..9e36278e19f 100644 --- a/src/java.xml/share/classes/javax/xml/stream/XMLEventWriter.java +++ b/src/java.xml/share/classes/javax/xml/stream/XMLEventWriter.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -50,13 +50,13 @@ public interface XMLEventWriter extends XMLEventConsumer { /** * Writes any cached events to the underlying output mechanism - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void flush() throws XMLStreamException; /** * Frees any resources associated with this stream - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void close() throws XMLStreamException; @@ -180,7 +180,7 @@ public interface XMLEventWriter extends XMLEventConsumer { * * * @param event the event to be added - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void add(XMLEvent event) throws XMLStreamException; @@ -192,7 +192,7 @@ public interface XMLEventWriter extends XMLEventConsumer { * event reader and call add on each event. * * @param reader the event stream to add to the output - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void add(XMLEventReader reader) throws XMLStreamException; @@ -200,7 +200,8 @@ public interface XMLEventWriter extends XMLEventConsumer { /** * Gets the prefix the uri is bound to * @param uri the uri to look up - * @throws XMLStreamException + * @return the prefix + * @throws XMLStreamException if an error occurs */ public String getPrefix(String uri) throws XMLStreamException; @@ -211,7 +212,7 @@ public interface XMLEventWriter extends XMLEventConsumer { * the prefix is bound in the root scope. * @param prefix the prefix to bind to the uri * @param uri the uri to bind to the prefix - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void setPrefix(String prefix, String uri) throws XMLStreamException; @@ -222,7 +223,7 @@ public interface XMLEventWriter extends XMLEventConsumer { * If this method is called before a START_ELEMENT has been written * the uri is bound in the root scope. * @param uri the uri to bind to the default namespace - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void setDefaultNamespace(String uri) throws XMLStreamException; @@ -234,7 +235,7 @@ public interface XMLEventWriter extends XMLEventConsumer { * the context passed to the method as the root context for resolving * namespaces. * @param context the namespace context to use for this writer - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void setNamespaceContext(NamespaceContext context) throws XMLStreamException; diff --git a/src/java.xml/share/classes/javax/xml/stream/XMLInputFactory.java b/src/java.xml/share/classes/javax/xml/stream/XMLInputFactory.java index aa94f4ff94f..086970790f3 100644 --- a/src/java.xml/share/classes/javax/xml/stream/XMLInputFactory.java +++ b/src/java.xml/share/classes/javax/xml/stream/XMLInputFactory.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -135,6 +135,10 @@ public abstract class XMLInputFactory { static final String DEFAULIMPL = "com.sun.xml.internal.stream.XMLInputFactoryImpl"; + /** + * Protected constructor to prevent instantiation. + * Use {@link #newFactory()} instead. + */ protected XMLInputFactory(){} /** @@ -153,6 +157,7 @@ public abstract class XMLInputFactory { /** * Creates a new instance of the factory in exactly the same manner as the * {@link #newFactory()} method. + * @return an instance of the {@code XMLInputFactory} * @throws FactoryConfigurationError if an instance of this factory cannot be loaded */ public static XMLInputFactory newInstance() @@ -210,6 +215,7 @@ public abstract class XMLInputFactory { * Once an application has obtained a reference to a XMLInputFactory it * can use the factory to configure and obtain stream instances. * + * @return an instance of the {@code XMLInputFactory} * @throws FactoryConfigurationError in case of {@linkplain * java.util.ServiceConfigurationError service configuration error} or if * the implementation is not available or cannot be instantiated. @@ -221,7 +227,7 @@ public abstract class XMLInputFactory { } /** - * Create a new instance of the factory + * Create a new instance of the factory. * * @param factoryId Name of the factory to find, same as * a property name @@ -324,9 +330,10 @@ public abstract class XMLInputFactory { } /** - * Create a new XMLStreamReader from a reader + * Create a new XMLStreamReader from a reader. * @param reader the XML data to read from - * @throws XMLStreamException + * @return an instance of the {@code XMLStreamReader} + * @throws XMLStreamException if an error occurs */ public abstract XMLStreamReader createXMLStreamReader(java.io.Reader reader) throws XMLStreamException; @@ -334,59 +341,68 @@ public abstract class XMLInputFactory { /** * Create a new XMLStreamReader from a JAXP source. This method is optional. * @param source the source to read from + * @return an instance of the {@code XMLStreamReader} * @throws UnsupportedOperationException if this method is not * supported by this XMLInputFactory - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public abstract XMLStreamReader createXMLStreamReader(Source source) throws XMLStreamException; /** - * Create a new XMLStreamReader from a java.io.InputStream + * Create a new XMLStreamReader from a java.io.InputStream. * @param stream the InputStream to read from - * @throws XMLStreamException + * @return an instance of the {@code XMLStreamReader} + * @throws XMLStreamException if an error occurs */ public abstract XMLStreamReader createXMLStreamReader(java.io.InputStream stream) throws XMLStreamException; /** - * Create a new XMLStreamReader from a java.io.InputStream + * Create a new XMLStreamReader from a java.io.InputStream. * @param stream the InputStream to read from * @param encoding the character encoding of the stream - * @throws XMLStreamException + * @return an instance of the {@code XMLStreamReader} + * @throws XMLStreamException if an error occurs */ public abstract XMLStreamReader createXMLStreamReader(java.io.InputStream stream, String encoding) throws XMLStreamException; /** - * Create a new XMLStreamReader from a java.io.InputStream + * Create a new XMLStreamReader from a java.io.InputStream. * @param systemId the system ID of the stream * @param stream the InputStream to read from + * @return an instance of the {@code XMLStreamReader} + * @throws XMLStreamException if an error occurs */ public abstract XMLStreamReader createXMLStreamReader(String systemId, java.io.InputStream stream) throws XMLStreamException; /** - * Create a new XMLStreamReader from a java.io.InputStream + * Create a new XMLStreamReader from a java.io.InputStream. * @param systemId the system ID of the stream * @param reader the InputStream to read from + * @return an instance of the {@code XMLStreamReader} + * @throws XMLStreamException if an error occurs */ public abstract XMLStreamReader createXMLStreamReader(String systemId, java.io.Reader reader) throws XMLStreamException; /** - * Create a new XMLEventReader from a reader + * Create a new XMLEventReader from a reader. * @param reader the XML data to read from - * @throws XMLStreamException + * @return an instance of the {@code XMLEventReader} + * @throws XMLStreamException if an error occurs */ public abstract XMLEventReader createXMLEventReader(java.io.Reader reader) throws XMLStreamException; /** - * Create a new XMLEventReader from a reader + * Create a new XMLEventReader from a reader. * @param systemId the system ID of the input * @param reader the XML data to read from - * @throws XMLStreamException + * @return an instance of the {@code XMLEventReader} + * @throws XMLStreamException if an error occurs */ public abstract XMLEventReader createXMLEventReader(String systemId, java.io.Reader reader) throws XMLStreamException; @@ -397,7 +413,7 @@ public abstract class XMLInputFactory { * the XMLStreamReader must not be used. * @param reader the XMLStreamReader to read from (may not be modified) * @return a new XMLEventReader - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public abstract XMLEventReader createXMLEventReader(XMLStreamReader reader) throws XMLStreamException; @@ -406,6 +422,8 @@ public abstract class XMLInputFactory { * Create a new XMLEventReader from a JAXP source. * Support of this method is optional. * @param source the source to read from + * @return an instance of the {@code XMLEventReader} + * @throws XMLStreamException if an error occurs * @throws UnsupportedOperationException if this method is not * supported by this XMLInputFactory */ @@ -415,7 +433,8 @@ public abstract class XMLInputFactory { /** * Create a new XMLEventReader from a java.io.InputStream * @param stream the InputStream to read from - * @throws XMLStreamException + * @return an instance of the {@code XMLEventReader} + * @throws XMLStreamException if an error occurs */ public abstract XMLEventReader createXMLEventReader(java.io.InputStream stream) throws XMLStreamException; @@ -424,7 +443,8 @@ public abstract class XMLInputFactory { * Create a new XMLEventReader from a java.io.InputStream * @param stream the InputStream to read from * @param encoding the character encoding of the stream - * @throws XMLStreamException + * @return an instance of the {@code XMLEventReader} + * @throws XMLStreamException if an error occurs */ public abstract XMLEventReader createXMLEventReader(java.io.InputStream stream, String encoding) throws XMLStreamException; @@ -433,7 +453,8 @@ public abstract class XMLInputFactory { * Create a new XMLEventReader from a java.io.InputStream * @param systemId the system ID of the stream * @param stream the InputStream to read from - * @throws XMLStreamException + * @return an instance of the {@code XMLEventReader} + * @throws XMLStreamException if an error occurs */ public abstract XMLEventReader createXMLEventReader(String systemId, java.io.InputStream stream) throws XMLStreamException; @@ -442,7 +463,8 @@ public abstract class XMLInputFactory { * Create a filtered reader that wraps the filter around the reader * @param reader the reader to filter * @param filter the filter to apply to the reader - * @throws XMLStreamException + * @return an instance of the {@code XMLEventReader} + * @throws XMLStreamException if an error occurs */ public abstract XMLStreamReader createFilteredReader(XMLStreamReader reader, StreamFilter filter) throws XMLStreamException; @@ -451,7 +473,8 @@ public abstract class XMLInputFactory { * Create a filtered event reader that wraps the filter around the event reader * @param reader the event reader to wrap * @param filter the filter to apply to the event reader - * @throws XMLStreamException + * @return an instance of the {@code XMLEventReader} + * @throws XMLStreamException if an error occurs */ public abstract XMLEventReader createFilteredReader(XMLEventReader reader, EventFilter filter) throws XMLStreamException; @@ -459,6 +482,7 @@ public abstract class XMLInputFactory { /** * The resolver that will be set on any XMLStreamReader or XMLEventReader created * by this factory instance. + * @return an instance of the {@code XMLResolver} */ public abstract XMLResolver getXMLResolver(); @@ -472,6 +496,7 @@ public abstract class XMLInputFactory { /** * The reporter that will be set on any XMLStreamReader or XMLEventReader created * by this factory instance. + * @return an instance of the {@code XMLReporter} */ public abstract XMLReporter getXMLReporter(); @@ -535,6 +560,7 @@ public abstract class XMLInputFactory { /** * Gets the allocator used by streams created with this factory + * @return an instance of the {@code XMLEventAllocator} */ public abstract XMLEventAllocator getEventAllocator(); diff --git a/src/java.xml/share/classes/javax/xml/stream/XMLOutputFactory.java b/src/java.xml/share/classes/javax/xml/stream/XMLOutputFactory.java index cb95d8af250..aa7aa267741 100644 --- a/src/java.xml/share/classes/javax/xml/stream/XMLOutputFactory.java +++ b/src/java.xml/share/classes/javax/xml/stream/XMLOutputFactory.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -112,6 +112,10 @@ public abstract class XMLOutputFactory { static final String DEFAULIMPL = "com.sun.xml.internal.stream.XMLOutputFactoryImpl"; + /** + * Protected constructor to prevent instantiation. + * Use {@link #newFactory()} instead. + */ protected XMLOutputFactory(){} /** @@ -130,6 +134,7 @@ public abstract class XMLOutputFactory { /** * Creates a new instance of the factory in exactly the same manner as the * {@link #newFactory()} method. + * @return an instance of the {@code XMLOutputFactory} * @throws FactoryConfigurationError if an instance of this factory cannot be loaded */ public static XMLOutputFactory newInstance() @@ -190,6 +195,7 @@ public abstract class XMLOutputFactory { * Once an application has obtained a reference to a XMLOutputFactory it * can use the factory to configure and obtain stream instances. * + * @return an instance of the {@code XMLOutputFactory} * @throws FactoryConfigurationError in case of {@linkplain * java.util.ServiceConfigurationError service configuration error} or if * the implementation is not available or cannot be instantiated. @@ -302,14 +308,16 @@ public abstract class XMLOutputFactory { /** * Create a new XMLStreamWriter that writes to a writer * @param stream the writer to write to - * @throws XMLStreamException + * @return instance of the {@code XMLStreamWriter} + * @throws XMLStreamException if an error occurs */ public abstract XMLStreamWriter createXMLStreamWriter(java.io.Writer stream) throws XMLStreamException; /** * Create a new XMLStreamWriter that writes to a stream * @param stream the stream to write to - * @throws XMLStreamException + * @return instance of the {@code XMLStreamWriter} + * @throws XMLStreamException if an error occurs */ public abstract XMLStreamWriter createXMLStreamWriter(java.io.OutputStream stream) throws XMLStreamException; @@ -317,7 +325,8 @@ public abstract class XMLOutputFactory { * Create a new XMLStreamWriter that writes to a stream * @param stream the stream to write to * @param encoding the encoding to use - * @throws XMLStreamException + * @return instance of the {@code XMLStreamWriter} + * @throws XMLStreamException if an error occurs */ public abstract XMLStreamWriter createXMLStreamWriter(java.io.OutputStream stream, String encoding) throws XMLStreamException; @@ -325,9 +334,10 @@ public abstract class XMLOutputFactory { /** * Create a new XMLStreamWriter that writes to a JAXP result. This method is optional. * @param result the result to write to + * @return instance of the {@code XMLStreamWriter} * @throws UnsupportedOperationException if this method is not * supported by this XMLOutputFactory - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public abstract XMLStreamWriter createXMLStreamWriter(Result result) throws XMLStreamException; @@ -335,16 +345,18 @@ public abstract class XMLOutputFactory { /** * Create a new XMLEventWriter that writes to a JAXP result. This method is optional. * @param result the result to write to + * @return instance of the {@code XMLEventWriter} * @throws UnsupportedOperationException if this method is not * supported by this XMLOutputFactory - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public abstract XMLEventWriter createXMLEventWriter(Result result) throws XMLStreamException; /** * Create a new XMLEventWriter that writes to a stream * @param stream the stream to write to - * @throws XMLStreamException + * @return instance of the {@code XMLEventWriter} + * @throws XMLStreamException if an error occurs */ public abstract XMLEventWriter createXMLEventWriter(java.io.OutputStream stream) throws XMLStreamException; @@ -354,7 +366,8 @@ public abstract class XMLOutputFactory { * Create a new XMLEventWriter that writes to a stream * @param stream the stream to write to * @param encoding the encoding to use - * @throws XMLStreamException + * @return instance of the {@code XMLEventWriter} + * @throws XMLStreamException if an error occurs */ public abstract XMLEventWriter createXMLEventWriter(java.io.OutputStream stream, String encoding) throws XMLStreamException; @@ -362,7 +375,8 @@ public abstract class XMLOutputFactory { /** * Create a new XMLEventWriter that writes to a writer * @param stream the stream to write to - * @throws XMLStreamException + * @return instance of the {@code XMLEventWriter} + * @throws XMLStreamException if an error occurs */ public abstract XMLEventWriter createXMLEventWriter(java.io.Writer stream) throws XMLStreamException; diff --git a/src/java.xml/share/classes/javax/xml/stream/XMLReporter.java b/src/java.xml/share/classes/javax/xml/stream/XMLReporter.java index 6cf5cb9a292..5a67ae785cb 100644 --- a/src/java.xml/share/classes/javax/xml/stream/XMLReporter.java +++ b/src/java.xml/share/classes/javax/xml/stream/XMLReporter.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -35,27 +35,16 @@ package javax.xml.stream; public interface XMLReporter { /** - * Report the desired message in an application specific format. - * Only warnings and non-fatal errors should be reported through - * this interface. - * Fatal errors should be thrown as XMLStreamException. - * - * @param message the error message - * @param errorType an implementation defined error type - * @param relatedInformation information related to the error, if available - * @param location the location of the error, if available - - * @throws XMLStreamException - + * @throws XMLStreamException if an error occurs */ public void report(String message, String errorType, Object relatedInformation, Location location) throws XMLStreamException; diff --git a/src/java.xml/share/classes/javax/xml/stream/XMLStreamException.java b/src/java.xml/share/classes/javax/xml/stream/XMLStreamException.java index 8dc6bb42e74..5a229ed1ea2 100644 --- a/src/java.xml/share/classes/javax/xml/stream/XMLStreamException.java +++ b/src/java.xml/share/classes/javax/xml/stream/XMLStreamException.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -37,7 +37,14 @@ package javax.xml.stream; public class XMLStreamException extends Exception { private static final long serialVersionUID = 2018819321811497362L; + /** + * The nested exception. + */ protected Throwable nested; + + /** + * The location of the error. + */ protected Location location; /** diff --git a/src/java.xml/share/classes/javax/xml/stream/XMLStreamReader.java b/src/java.xml/share/classes/javax/xml/stream/XMLStreamReader.java index a16e2a1f570..c2a230fe285 100644 --- a/src/java.xml/share/classes/javax/xml/stream/XMLStreamReader.java +++ b/src/java.xml/share/classes/javax/xml/stream/XMLStreamReader.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, 2018, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -256,6 +256,7 @@ public interface XMLStreamReader extends XMLStreamConstants { * return buf.toString(); * * + * @return the content of a text-only element * @throws XMLStreamException if the current event is not a START_ELEMENT * or if a non text element is encountered */ diff --git a/src/java.xml/share/classes/javax/xml/stream/XMLStreamWriter.java b/src/java.xml/share/classes/javax/xml/stream/XMLStreamWriter.java index 0ad0c29a03c..b81b8c9ca44 100644 --- a/src/java.xml/share/classes/javax/xml/stream/XMLStreamWriter.java +++ b/src/java.xml/share/classes/javax/xml/stream/XMLStreamWriter.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -192,7 +192,7 @@ public interface XMLStreamWriter { * open a new scope in the internal namespace context. Writing the * corresponding EndElement causes the scope to be closed. * @param localName local name of the tag, may not be null - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeStartElement(String localName) throws XMLStreamException; @@ -212,7 +212,7 @@ public interface XMLStreamWriter { * @param localName local name of the tag, may not be null * @param prefix the prefix of the tag, may not be null * @param namespaceURI the uri to bind the prefix to, may not be null - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeStartElement(String prefix, String localName, @@ -234,7 +234,7 @@ public interface XMLStreamWriter { * @param prefix the prefix of the tag, may not be null * @param localName local name of the tag, may not be null * @param namespaceURI the uri to bind the tag to, may not be null - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeEmptyElement(String prefix, String localName, String namespaceURI) throws XMLStreamException; @@ -242,7 +242,7 @@ public interface XMLStreamWriter { /** * Writes an empty element tag to the output * @param localName local name of the tag, may not be null - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeEmptyElement(String localName) throws XMLStreamException; @@ -264,14 +264,14 @@ public interface XMLStreamWriter { * Writes an end tag to the output relying on the internal * state of the writer to determine the prefix and local name * of the event. - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeEndElement() throws XMLStreamException; /** * Closes any start tags and writes corresponding end tags. - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeEndDocument() throws XMLStreamException; @@ -279,14 +279,14 @@ public interface XMLStreamWriter { /** * Close this writer and free any resources associated with the * writer. This must not close the underlying output stream. - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void close() throws XMLStreamException; /** * Write any cached data to the underlying output mechanism. - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void flush() throws XMLStreamException; @@ -297,7 +297,7 @@ public interface XMLStreamWriter { * @param localName the local name of the attribute * @param value the value of the attribute * @throws IllegalStateException if the current state does not allow Attribute writing - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeAttribute(String localName, String value) throws XMLStreamException; @@ -341,7 +341,7 @@ public interface XMLStreamWriter { * @param prefix the prefix to bind this namespace to * @param namespaceURI the uri to bind the prefix to * @throws IllegalStateException if the current state does not allow Namespace writing - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeNamespace(String prefix, String namespaceURI) throws XMLStreamException; @@ -350,7 +350,7 @@ public interface XMLStreamWriter { * Writes the default namespace to the stream * @param namespaceURI the uri to bind the default namespace to * @throws IllegalStateException if the current state does not allow Namespace writing - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeDefaultNamespace(String namespaceURI) throws XMLStreamException; @@ -358,7 +358,7 @@ public interface XMLStreamWriter { /** * Writes an xml comment with the data enclosed * @param data the data contained in the comment, may be null - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeComment(String data) throws XMLStreamException; @@ -366,7 +366,7 @@ public interface XMLStreamWriter { /** * Writes a processing instruction * @param target the target of the processing instruction, may not be null - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeProcessingInstruction(String target) throws XMLStreamException; @@ -375,7 +375,7 @@ public interface XMLStreamWriter { * Writes a processing instruction * @param target the target of the processing instruction, may not be null * @param data the data contained in the processing instruction, may not be null - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeProcessingInstruction(String target, String data) @@ -384,7 +384,7 @@ public interface XMLStreamWriter { /** * Writes a CData section * @param data the data contained in the CData Section, may not be null - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeCData(String data) throws XMLStreamException; @@ -394,7 +394,7 @@ public interface XMLStreamWriter { * from the XML 1.0 specification. * * @param dtd the DTD to be written - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeDTD(String dtd) throws XMLStreamException; @@ -402,14 +402,14 @@ public interface XMLStreamWriter { /** * Writes an entity reference * @param name the name of the entity - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeEntityRef(String name) throws XMLStreamException; /** * Write the XML Declaration. Defaults the XML version to 1.0, and the encoding to utf-8 - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeStartDocument() throws XMLStreamException; @@ -417,7 +417,7 @@ public interface XMLStreamWriter { /** * Write the XML Declaration. Defaults the XML version to 1.0 * @param version version of the xml document - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeStartDocument(String version) throws XMLStreamException; @@ -439,7 +439,7 @@ public interface XMLStreamWriter { /** * Write text to the output * @param text the value to write - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeCharacters(String text) throws XMLStreamException; @@ -449,15 +449,16 @@ public interface XMLStreamWriter { * @param text the value to write * @param start the starting position in the array * @param len the number of characters to write - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void writeCharacters(char[] text, int start, int len) throws XMLStreamException; /** - * Gets the prefix the uri is bound to + * Gets the prefix the uri is bound to. + * @param uri the uri the prefix is bound to * @return the prefix or null - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public String getPrefix(String uri) throws XMLStreamException; @@ -469,7 +470,7 @@ public interface XMLStreamWriter { * the prefix is bound in the root scope. * @param prefix the prefix to bind to the uri, may not be null * @param uri the uri to bind to the prefix, may be null - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void setPrefix(String prefix, String uri) throws XMLStreamException; @@ -482,7 +483,7 @@ public interface XMLStreamWriter { * If this method is called before a START_ELEMENT has been written * the uri is bound in the root scope. * @param uri the uri to bind to the default namespace, may be null - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void setDefaultNamespace(String uri) throws XMLStreamException; @@ -499,7 +500,7 @@ public interface XMLStreamWriter { * context it is treated as declared and the prefix may be used * by the StreamWriter. * @param context the namespace context to use for this writer, may not be null - * @throws XMLStreamException + * @throws XMLStreamException if an error occurs */ public void setNamespaceContext(NamespaceContext context) throws XMLStreamException; diff --git a/src/java.xml/share/classes/javax/xml/stream/events/Attribute.java b/src/java.xml/share/classes/javax/xml/stream/events/Attribute.java index ffc53508693..3e903efe3c1 100644 --- a/src/java.xml/share/classes/javax/xml/stream/events/Attribute.java +++ b/src/java.xml/share/classes/javax/xml/stream/events/Attribute.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -40,18 +40,20 @@ import javax.xml.namespace.QName; public interface Attribute extends XMLEvent { /** - * Returns the QName for this attribute + * Returns the QName for this attribute. + * @return the QName of the attribute */ QName getName(); /** - * Gets the normalized value of this attribute + * Gets the normalized value of this attribute. + * @return the normalized value of the attribute */ public String getValue(); /** * Gets the type of this attribute, default is - * the String "CDATA" + * the String "CDATA". * @return the type as a String, default is "CDATA" */ public String getDTDType(); diff --git a/src/java.xml/share/classes/javax/xml/stream/events/Characters.java b/src/java.xml/share/classes/javax/xml/stream/events/Characters.java index ab59dcbcb81..bda8de0285a 100644 --- a/src/java.xml/share/classes/javax/xml/stream/events/Characters.java +++ b/src/java.xml/share/classes/javax/xml/stream/events/Characters.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -40,6 +40,7 @@ package javax.xml.stream.events; public interface Characters extends XMLEvent { /** * Get the character data of this event + * @return the character data */ public String getData(); @@ -49,6 +50,7 @@ public interface Characters extends XMLEvent { * is reported as CHARACTERS. This method allows * checking of CHARACTERS events to see if they * are composed of only whitespace characters + * @return true if the {@code Characters} are all whitespace, false otherwise */ public boolean isWhiteSpace(); @@ -60,6 +62,7 @@ public interface Characters extends XMLEvent { * that are surrounded by non CDATA characters will be reported * as a single Characters event. This method will return false * in this case. + * @return true if it is {@code CDATA}, false otherwise */ public boolean isCData(); @@ -67,6 +70,7 @@ public interface Characters extends XMLEvent { * Return true if this is ignorableWhiteSpace. If * this event is ignorableWhiteSpace its event type will * be SPACE. + * @return true if it is ignorable whitespace, false otherwise */ public boolean isIgnorableWhiteSpace(); diff --git a/src/java.xml/share/classes/javax/xml/stream/events/Comment.java b/src/java.xml/share/classes/javax/xml/stream/events/Comment.java index 1ebee8f49af..48dd29bd58d 100644 --- a/src/java.xml/share/classes/javax/xml/stream/events/Comment.java +++ b/src/java.xml/share/classes/javax/xml/stream/events/Comment.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -36,7 +36,8 @@ public interface Comment extends XMLEvent { /** * Return the string data of the comment, returns empty string if it - * does not exist + * does not exist. + * @return the string data of the comment */ public String getText(); } diff --git a/src/java.xml/share/classes/javax/xml/stream/events/EntityReference.java b/src/java.xml/share/classes/javax/xml/stream/events/EntityReference.java index 0087b0a0bbb..0199082f333 100644 --- a/src/java.xml/share/classes/javax/xml/stream/events/EntityReference.java +++ b/src/java.xml/share/classes/javax/xml/stream/events/EntityReference.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -48,6 +48,7 @@ public interface EntityReference extends XMLEvent { /** * Return the declaration of this entity. + * @return the declaration */ EntityDeclaration getDeclaration(); diff --git a/src/java.xml/share/classes/javax/xml/stream/events/Namespace.java b/src/java.xml/share/classes/javax/xml/stream/events/Namespace.java index fac3a7eec8b..5f8a666f08d 100644 --- a/src/java.xml/share/classes/javax/xml/stream/events/Namespace.java +++ b/src/java.xml/share/classes/javax/xml/stream/events/Namespace.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -41,16 +41,19 @@ public interface Namespace extends Attribute { /** * Gets the prefix, returns "" if this is a default * namespace declaration. + * @return the prefix */ public String getPrefix(); /** * Gets the uri bound to the prefix of this namespace + * @return the {@code NamespaceURI} */ public String getNamespaceURI(); /** * returns true if this attribute declares the default namespace + * @return true if this is default namespace, false otherwise */ public boolean isDefaultNamespaceDeclaration(); } diff --git a/src/java.xml/share/classes/javax/xml/stream/events/NotationDeclaration.java b/src/java.xml/share/classes/javax/xml/stream/events/NotationDeclaration.java index 6d5ba68260c..a99b710a7ab 100644 --- a/src/java.xml/share/classes/javax/xml/stream/events/NotationDeclaration.java +++ b/src/java.xml/share/classes/javax/xml/stream/events/NotationDeclaration.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -40,16 +40,19 @@ package javax.xml.stream.events; public interface NotationDeclaration extends XMLEvent { /** * The notation name. + * @return the notation name */ String getName(); /** * The notation's public identifier, or null if none was given. + * @return the public identifier */ String getPublicId(); /** * The notation's system identifier, or null if none was given. + * @return the system identifier */ String getSystemId(); } diff --git a/src/java.xml/share/classes/javax/xml/stream/events/StartDocument.java b/src/java.xml/share/classes/javax/xml/stream/events/StartDocument.java index 6cd1fc4d3b2..76b9dc3a66b 100644 --- a/src/java.xml/share/classes/javax/xml/stream/events/StartDocument.java +++ b/src/java.xml/share/classes/javax/xml/stream/events/StartDocument.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -46,8 +46,9 @@ public interface StartDocument extends XMLEvent { public String getCharacterEncodingScheme(); /** - * Returns true if CharacterEncodingScheme was set in + * Returns true if CharacterEncodingScheme is set in * the encoding declaration of the document + * @return true if {@code CharacterEncodingScheme} is set, false otherwise */ public boolean encodingSet(); @@ -58,8 +59,9 @@ public interface StartDocument extends XMLEvent { public boolean isStandalone(); /** - * Returns true if the standalone attribute was set in + * Returns true if the standalone attribute is set in * the encoding declaration of the document. + * @return true if the standalone attribute is set, false otherwise */ public boolean standaloneSet(); diff --git a/src/java.xml/share/classes/javax/xml/stream/events/XMLEvent.java b/src/java.xml/share/classes/javax/xml/stream/events/XMLEvent.java index 43f8becb512..8b8dbb99176 100644 --- a/src/java.xml/share/classes/javax/xml/stream/events/XMLEvent.java +++ b/src/java.xml/share/classes/javax/xml/stream/events/XMLEvent.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -51,6 +51,7 @@ public interface XMLEvent extends javax.xml.stream.XMLStreamConstants { /** * Returns an integer code for this event. + * @return the event type * @see #START_ELEMENT * @see #END_ELEMENT * @see #CHARACTERS @@ -68,24 +69,28 @@ public interface XMLEvent extends javax.xml.stream.XMLStreamConstants { * Return the location of this event. The Location * returned from this method is non-volatile and * will retain its information. + * @return the location of the event * @see javax.xml.stream.Location */ javax.xml.stream.Location getLocation(); /** * A utility function to check if this event is a StartElement. + * @return true if the event is {@code StartElement}, false otherwise * @see StartElement */ public boolean isStartElement(); /** * A utility function to check if this event is an Attribute. + * @return true if the event is {@code Attribute}, false otherwise * @see Attribute */ public boolean isAttribute(); /** * A utility function to check if this event is a Namespace. + * @return true if the event is {@code Namespace}, false otherwise * @see Namespace */ public boolean isNamespace(); @@ -93,36 +98,42 @@ public interface XMLEvent extends javax.xml.stream.XMLStreamConstants { /** * A utility function to check if this event is a EndElement. + * @return true if the event is {@code EndElement}, false otherwise * @see EndElement */ public boolean isEndElement(); /** * A utility function to check if this event is an EntityReference. + * @return true if the event is {@code EntityReference}, false otherwise * @see EntityReference */ public boolean isEntityReference(); /** * A utility function to check if this event is a ProcessingInstruction. + * @return true if the event is {@code ProcessingInstruction}, false otherwise * @see ProcessingInstruction */ public boolean isProcessingInstruction(); /** * A utility function to check if this event is Characters. + * @return true if the event is {@code Characters}, false otherwise * @see Characters */ public boolean isCharacters(); /** * A utility function to check if this event is a StartDocument. + * @return true if the event is {@code StartDocument}, false otherwise * @see StartDocument */ public boolean isStartDocument(); /** * A utility function to check if this event is an EndDocument. + * @return true if the event is {@code EndDocument}, false otherwise * @see EndDocument */ public boolean isEndDocument(); @@ -130,18 +141,21 @@ public interface XMLEvent extends javax.xml.stream.XMLStreamConstants { /** * Returns this event as a start element event, may result in * a class cast exception if this event is not a start element. + * @return a {@code StartElement} event */ public StartElement asStartElement(); /** * Returns this event as an end element event, may result in * a class cast exception if this event is not a end element. + * @return a {@code EndElement} event */ public EndElement asEndElement(); /** * Returns this event as Characters, may result in * a class cast exception if this event is not Characters. + * @return a {@code Characters} event */ public Characters asCharacters(); @@ -150,6 +164,7 @@ public interface XMLEvent extends javax.xml.stream.XMLStreamConstants { * optional type information about the associated event. * It is optional and will return null if no information * is available. + * @return the type of the event, null if not available */ public QName getSchemaType(); diff --git a/src/java.xml/share/classes/javax/xml/stream/util/XMLEventAllocator.java b/src/java.xml/share/classes/javax/xml/stream/util/XMLEventAllocator.java index dbcfea03193..030fb09a68e 100644 --- a/src/java.xml/share/classes/javax/xml/stream/util/XMLEventAllocator.java +++ b/src/java.xml/share/classes/javax/xml/stream/util/XMLEventAllocator.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -47,6 +47,7 @@ public interface XMLEventAllocator { /** * This method creates an instance of the XMLEventAllocator. This * allows the XMLInputFactory to allocate a new instance per reader. + * @return an instance of the {@code XMLEventAllocator} */ public XMLEventAllocator newInstance(); @@ -58,6 +59,7 @@ public interface XMLEventAllocator { * must not modify the state of the XMLStreamReader. * @param reader The XMLStreamReader to allocate from * @return the event corresponding to the current reader state + * @throws XMLStreamException if an error occurs */ public XMLEvent allocate(XMLStreamReader reader) throws XMLStreamException; @@ -72,6 +74,7 @@ public interface XMLEventAllocator { * This method may modify the state of the XMLStreamReader. * @param reader The XMLStreamReader to allocate from * @param consumer The XMLEventConsumer to add to. + * @throws XMLStreamException if an error occurs */ public void allocate(XMLStreamReader reader, XMLEventConsumer consumer) throws XMLStreamException; diff --git a/src/java.xml/share/classes/javax/xml/stream/util/XMLEventConsumer.java b/src/java.xml/share/classes/javax/xml/stream/util/XMLEventConsumer.java index b1ba16064e5..876e7be73f8 100644 --- a/src/java.xml/share/classes/javax/xml/stream/util/XMLEventConsumer.java +++ b/src/java.xml/share/classes/javax/xml/stream/util/XMLEventConsumer.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -49,6 +49,7 @@ public interface XMLEventConsumer { * is undefined. * * @param event the event to add, may not be null + * @throws XMLStreamException if there is an error in adding the event */ public void add(XMLEvent event) throws XMLStreamException; diff --git a/src/java.xml/share/classes/javax/xml/xpath/XPathException.java b/src/java.xml/share/classes/javax/xml/xpath/XPathException.java index dd4a9e0003a..1cc7aa11c83 100644 --- a/src/java.xml/share/classes/javax/xml/xpath/XPathException.java +++ b/src/java.xml/share/classes/javax/xml/xpath/XPathException.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -40,7 +40,9 @@ import java.io.InvalidClassException; * @since 1.5 */ public class XPathException extends Exception { - + /** + * Serializable fields. + */ private static final ObjectStreamField[] serialPersistentFields = { new ObjectStreamField( "cause", Throwable.class ) }; diff --git a/src/java.xml/share/classes/org/xml/sax/DTDHandler.java b/src/java.xml/share/classes/org/xml/sax/DTDHandler.java index 5a83f3e7445..bb29e80de80 100644 --- a/src/java.xml/share/classes/org/xml/sax/DTDHandler.java +++ b/src/java.xml/share/classes/org/xml/sax/DTDHandler.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -84,7 +84,7 @@ public interface DTDHandler { * none was given. * @param systemId The notation's system identifier, or null if * none was given. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see #unparsedEntityDecl * @see org.xml.sax.Attributes @@ -108,7 +108,7 @@ public interface DTDHandler { *

If the system identifier is a URL, the parser must resolve it * fully before passing it to the application.

* - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @param name The unparsed entity's name. * @param publicId The entity's public identifier, or null if none diff --git a/src/java.xml/share/classes/org/xml/sax/DocumentHandler.java b/src/java.xml/share/classes/org/xml/sax/DocumentHandler.java index 06203e5006d..dfa1ee49304 100644 --- a/src/java.xml/share/classes/org/xml/sax/DocumentHandler.java +++ b/src/java.xml/share/classes/org/xml/sax/DocumentHandler.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -95,7 +95,7 @@ public interface DocumentHandler { * other methods in this interface or in DTDHandler (except for * setDocumentLocator).

* - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. */ public abstract void startDocument () @@ -111,7 +111,7 @@ public interface DocumentHandler { * (because of an unrecoverable error) or reached the end of * input.

* - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. */ public abstract void endDocument () @@ -135,7 +135,7 @@ public interface DocumentHandler { * * @param name The element type name. * @param atts The attributes attached to the element, if any. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see #endElement * @see org.xml.sax.AttributeList @@ -156,7 +156,7 @@ public interface DocumentHandler { * still be attached to the name.

* * @param name The element type name - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. */ public abstract void endElement (String name) @@ -183,7 +183,7 @@ public interface DocumentHandler { * @param ch The characters from the XML document. * @param start The start position in the array. * @param length The number of characters to read from the array. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see #ignorableWhitespace * @see org.xml.sax.Locator @@ -212,7 +212,7 @@ public interface DocumentHandler { * @param ch The characters from the XML document. * @param start The start position in the array. * @param length The number of characters to read from the array. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see #characters */ @@ -234,7 +234,7 @@ public interface DocumentHandler { * @param target The processing instruction target. * @param data The processing instruction data, or null if * none was supplied. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. */ public abstract void processingInstruction (String target, String data) diff --git a/src/java.xml/share/classes/org/xml/sax/EntityResolver.java b/src/java.xml/share/classes/org/xml/sax/EntityResolver.java index 77a3920333b..abacab3f796 100644 --- a/src/java.xml/share/classes/org/xml/sax/EntityResolver.java +++ b/src/java.xml/share/classes/org/xml/sax/EntityResolver.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -115,9 +115,9 @@ public interface EntityResolver { * @return An InputSource object describing the new input source, * or null to request that the parser open a regular * URI connection to the system identifier. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. - * @exception java.io.IOException A Java-specific IO exception, + * @throws java.io.IOException A Java-specific IO exception, * possibly the result of creating a new InputStream * or Reader for the InputSource. * @see org.xml.sax.InputSource diff --git a/src/java.xml/share/classes/org/xml/sax/ErrorHandler.java b/src/java.xml/share/classes/org/xml/sax/ErrorHandler.java index 47a5cb86528..56d2e66baf1 100644 --- a/src/java.xml/share/classes/org/xml/sax/ErrorHandler.java +++ b/src/java.xml/share/classes/org/xml/sax/ErrorHandler.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -78,7 +78,7 @@ public interface ErrorHandler { * * @param exception The warning information encapsulated in a * SAX parse exception. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.SAXParseException */ @@ -107,7 +107,7 @@ public interface ErrorHandler { * * @param exception The error information encapsulated in a * SAX parse exception. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.SAXParseException */ diff --git a/src/java.xml/share/classes/org/xml/sax/HandlerBase.java b/src/java.xml/share/classes/org/xml/sax/HandlerBase.java index 23e1da1e18d..f7c3be20072 100644 --- a/src/java.xml/share/classes/org/xml/sax/HandlerBase.java +++ b/src/java.xml/share/classes/org/xml/sax/HandlerBase.java @@ -59,7 +59,7 @@ public class HandlerBase implements EntityResolver, DTDHandler, DocumentHandler, ErrorHandler { /** - * Constructs a {@code HandlerBase}. + * Creates a {@code HandlerBase}. */ public HandlerBase() {} @@ -82,7 +82,7 @@ public class HandlerBase * document. * @return The new input source, or null to require the * default behaviour. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.EntityResolver#resolveEntity */ @@ -170,7 +170,7 @@ public class HandlerBase * of a document (such as allocating the root node of a tree or * creating an output file).

* - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.DocumentHandler#startDocument */ @@ -189,7 +189,7 @@ public class HandlerBase * of a document (such as finalising a tree or closing an output * file).

* - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.DocumentHandler#endDocument */ @@ -210,7 +210,7 @@ public class HandlerBase * * @param name The element type name. * @param attributes The specified or defaulted attributes. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.DocumentHandler#startElement */ @@ -230,7 +230,7 @@ public class HandlerBase * output to a file).

* * @param name the element name - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.DocumentHandler#endElement */ @@ -253,7 +253,7 @@ public class HandlerBase * @param start The start position in the character array. * @param length The number of characters to use from the * character array. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.DocumentHandler#characters */ @@ -276,7 +276,7 @@ public class HandlerBase * @param start The start position in the character array. * @param length The number of characters to use from the * character array. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.DocumentHandler#ignorableWhitespace */ @@ -298,7 +298,7 @@ public class HandlerBase * @param target The processing instruction target. * @param data The processing instruction data, or null if * none is supplied. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.DocumentHandler#processingInstruction */ @@ -324,7 +324,7 @@ public class HandlerBase * printing it to the console.

* * @param e The warning information encoded as an exception. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.ErrorHandler#warning * @see org.xml.sax.SAXParseException @@ -345,7 +345,7 @@ public class HandlerBase * printing it to the console.

* * @param e The warning information encoded as an exception. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.ErrorHandler#warning * @see org.xml.sax.SAXParseException @@ -369,7 +369,7 @@ public class HandlerBase * the parser may no longer report parsing events.

* * @param e The error information encoded as an exception. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.ErrorHandler#fatalError * @see org.xml.sax.SAXParseException diff --git a/src/java.xml/share/classes/org/xml/sax/InputSource.java b/src/java.xml/share/classes/org/xml/sax/InputSource.java index 9eeae9f850a..bcdc62e0029 100644 --- a/src/java.xml/share/classes/org/xml/sax/InputSource.java +++ b/src/java.xml/share/classes/org/xml/sax/InputSource.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -139,6 +139,7 @@ public class InputSource { * *

The character stream shall not include a byte order mark.

* + * @param characterStream the character stream * @see #setPublicId * @see #setSystemId * @see #setByteStream diff --git a/src/java.xml/share/classes/org/xml/sax/Parser.java b/src/java.xml/share/classes/org/xml/sax/Parser.java index dd77611cedb..083ab54f452 100644 --- a/src/java.xml/share/classes/org/xml/sax/Parser.java +++ b/src/java.xml/share/classes/org/xml/sax/Parser.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -74,7 +74,7 @@ public interface Parser * not request a locale change in the middle of a parse.

* * @param locale A Java Locale object. - * @exception org.xml.sax.SAXException Throws an exception + * @throws org.xml.sax.SAXException Throws an exception * (using the previous or default locale) if the * requested locale is not supported. * @see org.xml.sax.SAXException @@ -176,9 +176,9 @@ public interface Parser * * @param source The input source for the top-level of the * XML document. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. - * @exception java.io.IOException An IO exception from the parser, + * @throws java.io.IOException An IO exception from the parser, * possibly from a byte stream or character stream * supplied by the application. * @see org.xml.sax.InputSource @@ -207,9 +207,9 @@ public interface Parser * by the application before it is passed to the parser.

* * @param systemId The system identifier (URI). - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. - * @exception java.io.IOException An IO exception from the parser, + * @throws java.io.IOException An IO exception from the parser, * possibly from a byte stream or character stream * supplied by the application. * @see #parse(org.xml.sax.InputSource) diff --git a/src/java.xml/share/classes/org/xml/sax/SAXException.java b/src/java.xml/share/classes/org/xml/sax/SAXException.java index 172ac416a78..99362eb2f01 100644 --- a/src/java.xml/share/classes/org/xml/sax/SAXException.java +++ b/src/java.xml/share/classes/org/xml/sax/SAXException.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -166,6 +166,9 @@ public class SAXException extends Exception { // Internal state. ////////////////////////////////////////////////////////////////////// + /** + * serializable fields + */ private static final ObjectStreamField[] serialPersistentFields = { new ObjectStreamField( "exception", Exception.class ) }; diff --git a/src/java.xml/share/classes/org/xml/sax/XMLReader.java b/src/java.xml/share/classes/org/xml/sax/XMLReader.java index 2a78f082e4a..34d6e0587ee 100644 --- a/src/java.xml/share/classes/org/xml/sax/XMLReader.java +++ b/src/java.xml/share/classes/org/xml/sax/XMLReader.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -127,9 +127,9 @@ public interface XMLReader * * @param name The feature name, which is a fully-qualified URI. * @return The current value of the feature (true or false). - * @exception org.xml.sax.SAXNotRecognizedException If the feature + * @throws org.xml.sax.SAXNotRecognizedException If the feature * value can't be assigned or retrieved. - * @exception org.xml.sax.SAXNotSupportedException When the + * @throws org.xml.sax.SAXNotSupportedException When the * XMLReader recognizes the feature name but * cannot determine its value at this time. * @see #setFeature @@ -154,9 +154,9 @@ public interface XMLReader * * @param name The feature name, which is a fully-qualified URI. * @param value The requested value of the feature (true or false). - * @exception org.xml.sax.SAXNotRecognizedException If the feature + * @throws org.xml.sax.SAXNotRecognizedException If the feature * value can't be assigned or retrieved. - * @exception org.xml.sax.SAXNotSupportedException When the + * @throws org.xml.sax.SAXNotSupportedException When the * XMLReader recognizes the feature name but * cannot set the requested value. * @see #getFeature @@ -183,9 +183,9 @@ public interface XMLReader * * @param name The property name, which is a fully-qualified URI. * @return The current value of the property. - * @exception org.xml.sax.SAXNotRecognizedException If the property + * @throws org.xml.sax.SAXNotRecognizedException If the property * value can't be assigned or retrieved. - * @exception org.xml.sax.SAXNotSupportedException When the + * @throws org.xml.sax.SAXNotSupportedException When the * XMLReader recognizes the property name but * cannot determine its value at this time. * @see #setProperty @@ -213,9 +213,9 @@ public interface XMLReader * * @param name The property name, which is a fully-qualified URI. * @param value The requested value for the property. - * @exception org.xml.sax.SAXNotRecognizedException If the property + * @throws org.xml.sax.SAXNotRecognizedException If the property * value can't be assigned or retrieved. - * @exception org.xml.sax.SAXNotSupportedException When the + * @throws org.xml.sax.SAXNotSupportedException When the * XMLReader recognizes the property name but * cannot set the requested value. */ @@ -372,9 +372,9 @@ public interface XMLReader * * @param input The input source for the top-level of the * XML document. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. - * @exception java.io.IOException An IO exception from the parser, + * @throws java.io.IOException An IO exception from the parser, * possibly from a byte stream or character stream * supplied by the application. * @see org.xml.sax.InputSource @@ -403,9 +403,9 @@ public interface XMLReader * by the application before it is passed to the parser.

* * @param systemId The system identifier (URI). - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. - * @exception java.io.IOException An IO exception from the parser, + * @throws java.io.IOException An IO exception from the parser, * possibly from a byte stream or character stream * supplied by the application. * @see #parse(org.xml.sax.InputSource) diff --git a/src/java.xml/share/classes/org/xml/sax/ext/Attributes2.java b/src/java.xml/share/classes/org/xml/sax/ext/Attributes2.java index 4a590f3c8b3..ab5aab93cc7 100644 --- a/src/java.xml/share/classes/org/xml/sax/ext/Attributes2.java +++ b/src/java.xml/share/classes/org/xml/sax/ext/Attributes2.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2004, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2004, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -61,7 +61,7 @@ public interface Attributes2 extends Attributes * @param index The attribute index (zero-based). * @return true if the attribute was declared in the DTD, * false otherwise. - * @exception java.lang.ArrayIndexOutOfBoundsException When the + * @throws java.lang.ArrayIndexOutOfBoundsException When the * supplied index does not identify an attribute. */ public boolean isDeclared (int index); @@ -75,7 +75,7 @@ public interface Attributes2 extends Attributes * @param qName The XML qualified (prefixed) name. * @return true if the attribute was declared in the DTD, * false otherwise. - * @exception java.lang.IllegalArgumentException When the + * @throws java.lang.IllegalArgumentException When the * supplied name does not identify an attribute. */ public boolean isDeclared (String qName); @@ -96,7 +96,7 @@ public interface Attributes2 extends Attributes * @param localName The attribute's local name. * @return true if the attribute was declared in the DTD, * false otherwise. - * @exception java.lang.IllegalArgumentException When the + * @throws java.lang.IllegalArgumentException When the * supplied names do not identify an attribute. */ public boolean isDeclared (String uri, String localName); @@ -108,7 +108,7 @@ public interface Attributes2 extends Attributes * @param index The attribute index (zero-based). * @return true if the value was found in the XML text, * false if the value was provided by DTD defaulting. - * @exception java.lang.ArrayIndexOutOfBoundsException When the + * @throws java.lang.ArrayIndexOutOfBoundsException When the * supplied index does not identify an attribute. */ public boolean isSpecified (int index); @@ -127,7 +127,7 @@ public interface Attributes2 extends Attributes * @param localName The attribute's local name. * @return true if the value was found in the XML text, * false if the value was provided by DTD defaulting. - * @exception java.lang.IllegalArgumentException When the + * @throws java.lang.IllegalArgumentException When the * supplied names do not identify an attribute. */ public boolean isSpecified (String uri, String localName); @@ -139,7 +139,7 @@ public interface Attributes2 extends Attributes * @param qName The XML qualified (prefixed) name. * @return true if the value was found in the XML text, * false if the value was provided by DTD defaulting. - * @exception java.lang.IllegalArgumentException When the + * @throws java.lang.IllegalArgumentException When the * supplied name does not identify an attribute. */ public boolean isSpecified (String qName); diff --git a/src/java.xml/share/classes/org/xml/sax/ext/Attributes2Impl.java b/src/java.xml/share/classes/org/xml/sax/ext/Attributes2Impl.java index c86efbdfa2c..eefde9db579 100644 --- a/src/java.xml/share/classes/org/xml/sax/ext/Attributes2Impl.java +++ b/src/java.xml/share/classes/org/xml/sax/ext/Attributes2Impl.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2004, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2004, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -138,7 +138,7 @@ public class Attributes2Impl extends AttributesImpl implements Attributes2 * * @param index The attribute index (zero-based). * @return current flag value - * @exception java.lang.ArrayIndexOutOfBoundsException When the + * @throws java.lang.ArrayIndexOutOfBoundsException When the * supplied index does not identify an attribute. */ public boolean isSpecified (int index) @@ -157,7 +157,7 @@ public class Attributes2Impl extends AttributesImpl implements Attributes2 * the name has no Namespace URI. * @param localName The attribute's local name. * @return current flag value - * @exception java.lang.IllegalArgumentException When the + * @throws java.lang.IllegalArgumentException When the * supplied names do not identify an attribute. */ public boolean isSpecified (String uri, String localName) @@ -177,7 +177,7 @@ public class Attributes2Impl extends AttributesImpl implements Attributes2 * * @param qName The XML qualified (prefixed) name. * @return current flag value - * @exception java.lang.IllegalArgumentException When the + * @throws java.lang.IllegalArgumentException When the * supplied name does not identify an attribute. */ public boolean isSpecified (String qName) @@ -289,7 +289,7 @@ public class Attributes2Impl extends AttributesImpl implements Attributes2 * * @param index The index of the attribute (zero-based). * @param value The desired flag value. - * @exception java.lang.ArrayIndexOutOfBoundsException When the + * @throws java.lang.ArrayIndexOutOfBoundsException When the * supplied index does not identify an attribute. * @see #setType */ @@ -309,7 +309,7 @@ public class Attributes2Impl extends AttributesImpl implements Attributes2 * * @param index The index of the attribute (zero-based). * @param value The desired flag value. - * @exception java.lang.ArrayIndexOutOfBoundsException When the + * @throws java.lang.ArrayIndexOutOfBoundsException When the * supplied index does not identify an attribute. */ public void setSpecified (int index, boolean value) diff --git a/src/java.xml/share/classes/org/xml/sax/ext/DeclHandler.java b/src/java.xml/share/classes/org/xml/sax/ext/DeclHandler.java index e5e12f56fa4..7d5944656f2 100644 --- a/src/java.xml/share/classes/org/xml/sax/ext/DeclHandler.java +++ b/src/java.xml/share/classes/org/xml/sax/ext/DeclHandler.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -74,7 +74,7 @@ public interface DeclHandler * * @param name The element type name. * @param model The content model as a normalized string. - * @exception SAXException The application may raise an exception. + * @throws SAXException The application may raise an exception. */ public abstract void elementDecl (String name, String model) throws SAXException; @@ -103,7 +103,7 @@ public interface DeclHandler * none of these applies. * @param value A string representing the attribute's default value, * or null if there is none. - * @exception SAXException The application may raise an exception. + * @throws SAXException The application may raise an exception. */ public abstract void attributeDecl (String eName, String aName, @@ -123,7 +123,7 @@ public interface DeclHandler * @param name The name of the entity. If it is a parameter * entity, the name will begin with '%'. * @param value The replacement text of the entity. - * @exception SAXException The application may raise an exception. + * @throws SAXException The application may raise an exception. * @see #externalEntityDecl * @see org.xml.sax.DTDHandler#unparsedEntityDecl */ @@ -145,7 +145,7 @@ public interface DeclHandler * @param publicId The entity's public identifier, or null if none * was given. * @param systemId The entity's system identifier. - * @exception SAXException The application may raise an exception. + * @throws SAXException The application may raise an exception. * @see #internalEntityDecl * @see org.xml.sax.DTDHandler#unparsedEntityDecl */ diff --git a/src/java.xml/share/classes/org/xml/sax/ext/EntityResolver2.java b/src/java.xml/share/classes/org/xml/sax/ext/EntityResolver2.java index 8b99f14fdf8..5de54eca28b 100644 --- a/src/java.xml/share/classes/org/xml/sax/ext/EntityResolver2.java +++ b/src/java.xml/share/classes/org/xml/sax/ext/EntityResolver2.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2004, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2004, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -137,9 +137,9 @@ public interface EntityResolver2 extends EntityResolver * to be used by the parser, or null to indicate that no external * subset is provided. * - * @exception SAXException Any SAX exception, possibly wrapping + * @throws SAXException Any SAX exception, possibly wrapping * another exception. - * @exception IOException Probably indicating a failure to create + * @throws IOException Probably indicating a failure to create * a new InputStream or Reader, or an illegal URL. */ public InputSource getExternalSubset (String name, String baseURI) @@ -194,9 +194,9 @@ public interface EntityResolver2 extends EntityResolver * resolve the system ID against the base URI and open a connection * to resulting URI. * - * @exception SAXException Any SAX exception, possibly wrapping + * @throws SAXException Any SAX exception, possibly wrapping * another exception. - * @exception IOException Probably indicating a failure to create + * @throws IOException Probably indicating a failure to create * a new InputStream or Reader, or an illegal URL. */ public InputSource resolveEntity ( diff --git a/src/java.xml/share/classes/org/xml/sax/ext/LexicalHandler.java b/src/java.xml/share/classes/org/xml/sax/ext/LexicalHandler.java index b1ad8eb06ee..ae9a6fc4237 100644 --- a/src/java.xml/share/classes/org/xml/sax/ext/LexicalHandler.java +++ b/src/java.xml/share/classes/org/xml/sax/ext/LexicalHandler.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -89,7 +89,7 @@ public interface LexicalHandler * external DTD subset, or null if none was declared. * (Note that this is not resolved against the document * base URI.) - * @exception SAXException The application may raise an + * @throws SAXException The application may raise an * exception. * @see #endDTD * @see #startEntity @@ -106,7 +106,7 @@ public interface LexicalHandler * DOCTYPE declaration; if the document has no DOCTYPE declaration, * this method will not be invoked.

* - * @exception SAXException The application may raise an exception. + * @throws SAXException The application may raise an exception. * @see #startDTD */ public abstract void endDTD () @@ -157,7 +157,7 @@ public interface LexicalHandler * @param name The name of the entity. If it is a parameter * entity, the name will begin with '%', and if it is the * external DTD subset, it will be "[dtd]". - * @exception SAXException The application may raise an exception. + * @throws SAXException The application may raise an exception. * @see #endEntity * @see org.xml.sax.ext.DeclHandler#internalEntityDecl * @see org.xml.sax.ext.DeclHandler#externalEntityDecl @@ -170,7 +170,7 @@ public interface LexicalHandler * Report the end of an entity. * * @param name The name of the entity that is ending. - * @exception SAXException The application may raise an exception. + * @throws SAXException The application may raise an exception. * @see #startEntity */ public abstract void endEntity (String name) @@ -185,7 +185,7 @@ public interface LexicalHandler * characters} event; this event is intended only to report * the boundary.

* - * @exception SAXException The application may raise an exception. + * @throws SAXException The application may raise an exception. * @see #endCDATA */ public abstract void startCDATA () @@ -195,7 +195,7 @@ public interface LexicalHandler /** * Report the end of a CDATA section. * - * @exception SAXException The application may raise an exception. + * @throws SAXException The application may raise an exception. * @see #startCDATA */ public abstract void endCDATA () @@ -214,7 +214,7 @@ public interface LexicalHandler * @param ch An array holding the characters in the comment. * @param start The starting position in the array. * @param length The number of characters to use from the array. - * @exception SAXException The application may raise an exception. + * @throws SAXException The application may raise an exception. */ public abstract void comment (char ch[], int start, int length) throws SAXException; diff --git a/src/java.xml/share/classes/org/xml/sax/helpers/AttributesImpl.java b/src/java.xml/share/classes/org/xml/sax/helpers/AttributesImpl.java index 724da5b5eed..3e4a1bc8e03 100644 --- a/src/java.xml/share/classes/org/xml/sax/helpers/AttributesImpl.java +++ b/src/java.xml/share/classes/org/xml/sax/helpers/AttributesImpl.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -417,7 +417,7 @@ public class AttributesImpl implements Attributes * if qualified names are not available. * @param type The attribute type as a string. * @param value The attribute value. - * @exception java.lang.ArrayIndexOutOfBoundsException When the + * @throws java.lang.ArrayIndexOutOfBoundsException When the * supplied index does not point to an attribute * in the list. */ @@ -440,7 +440,7 @@ public class AttributesImpl implements Attributes * Remove an attribute from the list. * * @param index The index of the attribute (zero-based). - * @exception java.lang.ArrayIndexOutOfBoundsException When the + * @throws java.lang.ArrayIndexOutOfBoundsException When the * supplied index does not point to an attribute * in the list. */ @@ -470,7 +470,7 @@ public class AttributesImpl implements Attributes * @param index The index of the attribute (zero-based). * @param uri The attribute's Namespace URI, or the empty * string for none. - * @exception java.lang.ArrayIndexOutOfBoundsException When the + * @throws java.lang.ArrayIndexOutOfBoundsException When the * supplied index does not point to an attribute * in the list. */ @@ -490,7 +490,7 @@ public class AttributesImpl implements Attributes * @param index The index of the attribute (zero-based). * @param localName The attribute's local name, or the empty * string for none. - * @exception java.lang.ArrayIndexOutOfBoundsException When the + * @throws java.lang.ArrayIndexOutOfBoundsException When the * supplied index does not point to an attribute * in the list. */ @@ -510,7 +510,7 @@ public class AttributesImpl implements Attributes * @param index The index of the attribute (zero-based). * @param qName The attribute's qualified name, or the empty * string for none. - * @exception java.lang.ArrayIndexOutOfBoundsException When the + * @throws java.lang.ArrayIndexOutOfBoundsException When the * supplied index does not point to an attribute * in the list. */ @@ -529,7 +529,7 @@ public class AttributesImpl implements Attributes * * @param index The index of the attribute (zero-based). * @param type The attribute's type. - * @exception java.lang.ArrayIndexOutOfBoundsException When the + * @throws java.lang.ArrayIndexOutOfBoundsException When the * supplied index does not point to an attribute * in the list. */ @@ -548,7 +548,7 @@ public class AttributesImpl implements Attributes * * @param index The index of the attribute (zero-based). * @param value The attribute's value. - * @exception java.lang.ArrayIndexOutOfBoundsException When the + * @throws java.lang.ArrayIndexOutOfBoundsException When the * supplied index does not point to an attribute * in the list. */ @@ -604,7 +604,7 @@ public class AttributesImpl implements Attributes * Report a bad array index in a manipulator. * * @param index The index to report. - * @exception java.lang.ArrayIndexOutOfBoundsException Always. + * @throws java.lang.ArrayIndexOutOfBoundsException Always. */ private void badIndex (int index) throws ArrayIndexOutOfBoundsException diff --git a/src/java.xml/share/classes/org/xml/sax/helpers/DefaultHandler.java b/src/java.xml/share/classes/org/xml/sax/helpers/DefaultHandler.java index 1ee6153baed..ef7fed3f08f 100644 --- a/src/java.xml/share/classes/org/xml/sax/helpers/DefaultHandler.java +++ b/src/java.xml/share/classes/org/xml/sax/helpers/DefaultHandler.java @@ -94,12 +94,13 @@ public class DefaultHandler * document. * @return The new input source, or null to require the * default behaviour. - * @exception java.io.IOException If there is an error setting + * @throws java.io.IOException If there is an error setting * up the new input source. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.EntityResolver#resolveEntity */ + @Override public InputSource resolveEntity (String publicId, String systemId) throws IOException, SAXException { @@ -124,10 +125,11 @@ public class DefaultHandler * @param publicId The notation public identifier, or null if not * available. * @param systemId The notation system identifier. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.DTDHandler#notationDecl */ + @Override public void notationDecl (String name, String publicId, String systemId) throws SAXException { @@ -147,10 +149,11 @@ public class DefaultHandler * available. * @param systemId The entity system identifier. * @param notationName The name of the associated notation. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.DTDHandler#unparsedEntityDecl */ + @Override public void unparsedEntityDecl (String name, String publicId, String systemId, String notationName) throws SAXException @@ -176,6 +179,7 @@ public class DefaultHandler * @see org.xml.sax.ContentHandler#setDocumentLocator * @see org.xml.sax.Locator */ + @Override public void setDocumentLocator (Locator locator) { // no op @@ -190,10 +194,11 @@ public class DefaultHandler * of a document (such as allocating the root node of a tree or * creating an output file).

* - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.ContentHandler#startDocument */ + @Override public void startDocument () throws SAXException { @@ -209,10 +214,11 @@ public class DefaultHandler * of a document (such as finalising a tree or closing an output * file).

* - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.ContentHandler#endDocument */ + @Override public void endDocument () throws SAXException { @@ -229,10 +235,11 @@ public class DefaultHandler * * @param prefix The Namespace prefix being declared. * @param uri The Namespace URI mapped to the prefix. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.ContentHandler#startPrefixMapping */ + @Override public void startPrefixMapping (String prefix, String uri) throws SAXException { @@ -248,10 +255,11 @@ public class DefaultHandler * each prefix mapping.

* * @param prefix The Namespace prefix being declared. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.ContentHandler#endPrefixMapping */ + @Override public void endPrefixMapping (String prefix) throws SAXException { @@ -278,10 +286,11 @@ public class DefaultHandler * @param attributes The attributes attached to the element. If * there are no attributes, it shall be an empty * Attributes object. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.ContentHandler#startElement */ + @Override public void startElement (String uri, String localName, String qName, Attributes attributes) throws SAXException @@ -306,10 +315,11 @@ public class DefaultHandler * performed. * @param qName The qualified name (with prefix), or the * empty string if qualified names are not available. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.ContentHandler#endElement */ + @Override public void endElement (String uri, String localName, String qName) throws SAXException { @@ -329,10 +339,11 @@ public class DefaultHandler * @param start The start position in the character array. * @param length The number of characters to use from the * character array. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.ContentHandler#characters */ + @Override public void characters (char ch[], int start, int length) throws SAXException { @@ -352,10 +363,11 @@ public class DefaultHandler * @param start The start position in the character array. * @param length The number of characters to use from the * character array. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.ContentHandler#ignorableWhitespace */ + @Override public void ignorableWhitespace (char ch[], int start, int length) throws SAXException { @@ -374,10 +386,11 @@ public class DefaultHandler * @param target The processing instruction target. * @param data The processing instruction data, or null if * none is supplied. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.ContentHandler#processingInstruction */ + @Override public void processingInstruction (String target, String data) throws SAXException { @@ -394,10 +407,11 @@ public class DefaultHandler * invoking other methods.

* * @param name The name of the skipped entity. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.ContentHandler#processingInstruction */ + @Override public void skippedEntity (String name) throws SAXException { @@ -420,11 +434,12 @@ public class DefaultHandler * printing it to the console.

* * @param e The warning information encoded as an exception. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.ErrorHandler#warning * @see org.xml.sax.SAXParseException */ + @Override public void warning (SAXParseException e) throws SAXException { @@ -441,11 +456,12 @@ public class DefaultHandler * printing it to the console.

* * @param e The error information encoded as an exception. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.ErrorHandler#warning * @see org.xml.sax.SAXParseException */ + @Override public void error (SAXParseException e) throws SAXException { @@ -465,11 +481,12 @@ public class DefaultHandler * the parser may no longer report parsing events.

* * @param e The error information encoded as an exception. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. * @see org.xml.sax.ErrorHandler#fatalError * @see org.xml.sax.SAXParseException */ + @Override public void fatalError (SAXParseException e) throws SAXException { diff --git a/src/java.xml/share/classes/org/xml/sax/helpers/NamespaceSupport.java b/src/java.xml/share/classes/org/xml/sax/helpers/NamespaceSupport.java index 7c636901ac4..f78cae7c620 100644 --- a/src/java.xml/share/classes/org/xml/sax/helpers/NamespaceSupport.java +++ b/src/java.xml/share/classes/org/xml/sax/helpers/NamespaceSupport.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -487,9 +487,11 @@ public class NamespaceSupport * by {@link #processName processName()}. This may only be * changed before any contexts have been pushed. * + * @param value a flag indicating whether namespace declaration attributes + * are placed into the {@link #NSDECL NSDECL} namespace * @since 1.5, SAX 2.1alpha * - * @exception IllegalStateException when attempting to set this + * @throws IllegalStateException when attempting to set this * after any context has been pushed. */ public void setNamespaceDeclUris (boolean value) @@ -511,6 +513,8 @@ public class NamespaceSupport * Returns true if namespace declaration attributes are placed into * a namespace. This behavior is not the default. * + * @return true if namespace declaration attributes are placed into a namespace, + * false otherwise * @since 1.5, SAX 2.1alpha */ public boolean isNamespaceDeclUris () diff --git a/src/java.xml/share/classes/org/xml/sax/helpers/ParserAdapter.java b/src/java.xml/share/classes/org/xml/sax/helpers/ParserAdapter.java index a12bfe991a4..072b81f1671 100644 --- a/src/java.xml/share/classes/org/xml/sax/helpers/ParserAdapter.java +++ b/src/java.xml/share/classes/org/xml/sax/helpers/ParserAdapter.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -81,7 +81,7 @@ public class ParserAdapter implements XMLReader, DocumentHandler *

Use the "org.xml.sax.parser" property to locate the * embedded SAX1 driver.

* - * @exception SAXException If the embedded driver + * @throws SAXException If the embedded driver * cannot be instantiated or if the * org.xml.sax.parser property is not specified. */ @@ -128,7 +128,7 @@ public class ParserAdapter implements XMLReader, DocumentHandler * a new ParserAdapter.

* * @param parser The SAX1 parser to embed. - * @exception java.lang.NullPointerException If the parser parameter + * @throws java.lang.NullPointerException If the parser parameter * is null. */ public ParserAdapter (Parser parser) @@ -142,7 +142,7 @@ public class ParserAdapter implements XMLReader, DocumentHandler * Internal setup method. * * @param parser The embedded parser. - * @exception java.lang.NullPointerException If the parser parameter + * @throws java.lang.NullPointerException If the parser parameter * is null. */ private void setup (Parser parser) @@ -181,9 +181,9 @@ public class ParserAdapter implements XMLReader, DocumentHandler * * @param name The feature name, as a complete URI. * @param value The requested feature value. - * @exception SAXNotRecognizedException If the feature + * @throws SAXNotRecognizedException If the feature * can't be assigned or retrieved. - * @exception SAXNotSupportedException If the feature + * @throws SAXNotSupportedException If the feature * can't be assigned that value. * @see org.xml.sax.XMLReader#setFeature */ @@ -219,9 +219,9 @@ public class ParserAdapter implements XMLReader, DocumentHandler * * @param name The feature name, as a complete URI. * @return The current feature value. - * @exception SAXNotRecognizedException If the feature + * @throws SAXNotRecognizedException If the feature * value can't be assigned or retrieved. - * @exception SAXNotSupportedException If the + * @throws SAXNotSupportedException If the * feature is not currently readable. * @see org.xml.sax.XMLReader#setFeature */ @@ -247,9 +247,9 @@ public class ParserAdapter implements XMLReader, DocumentHandler * * @param name The property name. * @param value The property value. - * @exception SAXNotRecognizedException If the property + * @throws SAXNotRecognizedException If the property * value can't be assigned or retrieved. - * @exception SAXNotSupportedException If the property + * @throws SAXNotSupportedException If the property * can't be assigned that value. * @see org.xml.sax.XMLReader#setProperty */ @@ -267,9 +267,9 @@ public class ParserAdapter implements XMLReader, DocumentHandler * * @param name The property name. * @return The property value. - * @exception SAXNotRecognizedException If the property + * @throws SAXNotRecognizedException If the property * value can't be assigned or retrieved. - * @exception SAXNotSupportedException If the property + * @throws SAXNotSupportedException If the property * value is not currently readable. * @see org.xml.sax.XMLReader#getProperty */ @@ -380,9 +380,9 @@ public class ParserAdapter implements XMLReader, DocumentHandler * Parse an XML document. * * @param systemId The absolute URL of the document. - * @exception java.io.IOException If there is a problem reading + * @throws java.io.IOException If there is a problem reading * the raw content of the document. - * @exception SAXException If there is a problem + * @throws SAXException If there is a problem * processing the document. * @see #parse(org.xml.sax.InputSource) * @see org.xml.sax.Parser#parse(java.lang.String) @@ -398,9 +398,9 @@ public class ParserAdapter implements XMLReader, DocumentHandler * Parse an XML document. * * @param input An input source for the document. - * @exception java.io.IOException If there is a problem reading + * @throws java.io.IOException If there is a problem reading * the raw content of the document. - * @exception SAXException If there is a problem + * @throws SAXException If there is a problem * processing the document. * @see #parse(java.lang.String) * @see org.xml.sax.Parser#parse(org.xml.sax.InputSource) @@ -448,7 +448,7 @@ public class ParserAdapter implements XMLReader, DocumentHandler * Adapter implementation method; do not call. * Adapt a SAX1 start document event. * - * @exception SAXException The client may raise a + * @throws SAXException The client may raise a * processing exception. * @see org.xml.sax.DocumentHandler#startDocument */ @@ -465,7 +465,7 @@ public class ParserAdapter implements XMLReader, DocumentHandler * Adapter implementation method; do not call. * Adapt a SAX1 end document event. * - * @exception SAXException The client may raise a + * @throws SAXException The client may raise a * processing exception. * @see org.xml.sax.DocumentHandler#endDocument */ @@ -486,7 +486,7 @@ public class ParserAdapter implements XMLReader, DocumentHandler * * @param qName The qualified (prefixed) name. * @param qAtts The XML attribute list (with qnames). - * @exception SAXException The client may raise a + * @throws SAXException The client may raise a * processing exception. */ public void startElement (String qName, AttributeList qAtts) @@ -616,7 +616,7 @@ public class ParserAdapter implements XMLReader, DocumentHandler * Adapt a SAX1 end element event. * * @param qName The qualified (prefixed) name. - * @exception SAXException The client may raise a + * @throws SAXException The client may raise a * processing exception. * @see org.xml.sax.DocumentHandler#endElement */ @@ -653,7 +653,7 @@ public class ParserAdapter implements XMLReader, DocumentHandler * @param ch An array of characters. * @param start The starting position in the array. * @param length The number of characters to use. - * @exception SAXException The client may raise a + * @throws SAXException The client may raise a * processing exception. * @see org.xml.sax.DocumentHandler#characters */ @@ -673,7 +673,7 @@ public class ParserAdapter implements XMLReader, DocumentHandler * @param ch An array of characters. * @param start The starting position in the array. * @param length The number of characters to use. - * @exception SAXException The client may raise a + * @throws SAXException The client may raise a * processing exception. * @see org.xml.sax.DocumentHandler#ignorableWhitespace */ @@ -692,7 +692,7 @@ public class ParserAdapter implements XMLReader, DocumentHandler * * @param target The processing instruction target. * @param data The remainder of the processing instruction - * @exception SAXException The client may raise a + * @throws SAXException The client may raise a * processing exception. * @see org.xml.sax.DocumentHandler#processingInstruction */ @@ -748,7 +748,7 @@ public class ParserAdapter implements XMLReader, DocumentHandler * @param qName The qualified (prefixed) name. * @param isAttribute true if this is an attribute name. * @return The name split into three parts. - * @exception SAXException The client may throw + * @throws SAXException The client may throw * an exception if there is an error callback. */ private String [] processName (String qName, boolean isAttribute, @@ -773,7 +773,7 @@ public class ParserAdapter implements XMLReader, DocumentHandler * Report a non-fatal error. * * @param message The error message. - * @exception SAXException The client may throw + * @throws SAXException The client may throw * an exception. */ void reportError (String message) @@ -807,7 +807,7 @@ public class ParserAdapter implements XMLReader, DocumentHandler * * @param type The type of thing (feature or property). * @param name The feature or property name. - * @exception SAXNotSupportedException If a + * @throws SAXNotSupportedException If a * document is currently being parsed. */ private void checkNotParsing (String type, String name) diff --git a/src/java.xml/share/classes/org/xml/sax/helpers/ParserFactory.java b/src/java.xml/share/classes/org/xml/sax/helpers/ParserFactory.java index 5bc072eb790..d4dfb6ca6ce 100644 --- a/src/java.xml/share/classes/org/xml/sax/helpers/ParserFactory.java +++ b/src/java.xml/share/classes/org/xml/sax/helpers/ParserFactory.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -70,16 +70,17 @@ public class ParserFactory { *

The named class must exist and must implement the * {@link org.xml.sax.Parser Parser} interface.

* - * @exception java.lang.NullPointerException There is no value + * @return a new SAX parser + * @throws java.lang.NullPointerException There is no value * for the `org.xml.sax.parser' system property. - * @exception java.lang.ClassNotFoundException The SAX parser + * @throws java.lang.ClassNotFoundException The SAX parser * class was not found (check your CLASSPATH). - * @exception IllegalAccessException The SAX parser class was + * @throws IllegalAccessException The SAX parser class was * found, but you do not have permission to load * it. - * @exception InstantiationException The SAX parser class was + * @throws InstantiationException The SAX parser class was * found but could not be instantiated. - * @exception java.lang.ClassCastException The SAX parser class + * @throws java.lang.ClassCastException The SAX parser class * was found and instantiated, but does not implement * org.xml.sax.Parser. * @see #makeParser(java.lang.String) @@ -109,14 +110,15 @@ public class ParserFactory { * * @param className A string containing the name of the * SAX parser class. - * @exception java.lang.ClassNotFoundException The SAX parser + * @return a new SAX parser + * @throws java.lang.ClassNotFoundException The SAX parser * class was not found (check your CLASSPATH). - * @exception IllegalAccessException The SAX parser class was + * @throws IllegalAccessException The SAX parser class was * found, but you do not have permission to load * it. - * @exception InstantiationException The SAX parser class was + * @throws InstantiationException The SAX parser class was * found but could not be instantiated. - * @exception java.lang.ClassCastException The SAX parser class + * @throws java.lang.ClassCastException The SAX parser class * was found and instantiated, but does not implement * org.xml.sax.Parser. * @see #makeParser() diff --git a/src/java.xml/share/classes/org/xml/sax/helpers/XMLFilterImpl.java b/src/java.xml/share/classes/org/xml/sax/helpers/XMLFilterImpl.java index 10564ff0978..6571f3618c9 100644 --- a/src/java.xml/share/classes/org/xml/sax/helpers/XMLFilterImpl.java +++ b/src/java.xml/share/classes/org/xml/sax/helpers/XMLFilterImpl.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -92,6 +92,7 @@ public class XMLFilterImpl /** * Construct an XML filter with the specified parent. * + * @param parent the specified parent * @see #setParent * @see #getParent */ @@ -152,9 +153,9 @@ public class XMLFilterImpl * * @param name The feature name. * @param value The requested feature value. - * @exception org.xml.sax.SAXNotRecognizedException If the feature + * @throws org.xml.sax.SAXNotRecognizedException If the feature * value can't be assigned or retrieved from the parent. - * @exception org.xml.sax.SAXNotSupportedException When the + * @throws org.xml.sax.SAXNotSupportedException When the * parent recognizes the feature name but * cannot set the requested value. */ @@ -176,9 +177,9 @@ public class XMLFilterImpl * * @param name The feature name. * @return The current value of the feature. - * @exception org.xml.sax.SAXNotRecognizedException If the feature + * @throws org.xml.sax.SAXNotRecognizedException If the feature * value can't be assigned or retrieved from the parent. - * @exception org.xml.sax.SAXNotSupportedException When the + * @throws org.xml.sax.SAXNotSupportedException When the * parent recognizes the feature name but * cannot determine its value at this time. */ @@ -200,9 +201,9 @@ public class XMLFilterImpl * * @param name The property name. * @param value The requested property value. - * @exception org.xml.sax.SAXNotRecognizedException If the property + * @throws org.xml.sax.SAXNotRecognizedException If the property * value can't be assigned or retrieved from the parent. - * @exception org.xml.sax.SAXNotSupportedException When the + * @throws org.xml.sax.SAXNotSupportedException When the * parent recognizes the property name but * cannot set the requested value. */ @@ -222,9 +223,9 @@ public class XMLFilterImpl * * @param name The property name. * @return The current value of the property. - * @exception org.xml.sax.SAXNotRecognizedException If the property + * @throws org.xml.sax.SAXNotRecognizedException If the property * value can't be assigned or retrieved from the parent. - * @exception org.xml.sax.SAXNotSupportedException When the + * @throws org.xml.sax.SAXNotSupportedException When the * parent recognizes the property name but * cannot determine its value at this time. */ @@ -331,9 +332,9 @@ public class XMLFilterImpl * Parse a document. * * @param input The input source for the document entity. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. - * @exception java.io.IOException An IO exception from the parser, + * @throws java.io.IOException An IO exception from the parser, * possibly from a byte stream or character stream * supplied by the application. */ @@ -349,9 +350,9 @@ public class XMLFilterImpl * Parse a document. * * @param systemId The system identifier as a fully-qualified URI. - * @exception org.xml.sax.SAXException Any SAX exception, possibly + * @throws org.xml.sax.SAXException Any SAX exception, possibly * wrapping another exception. - * @exception java.io.IOException An IO exception from the parser, + * @throws java.io.IOException An IO exception from the parser, * possibly from a byte stream or character stream * supplied by the application. */ @@ -374,9 +375,9 @@ public class XMLFilterImpl * @param publicId The entity's public identifier, or null. * @param systemId The entity's system identifier. * @return A new InputSource or null for the default. - * @exception org.xml.sax.SAXException The client may throw + * @throws org.xml.sax.SAXException The client may throw * an exception during processing. - * @exception java.io.IOException The client may throw an + * @throws java.io.IOException The client may throw an * I/O-related exception while obtaining the * new InputSource. */ @@ -403,7 +404,7 @@ public class XMLFilterImpl * @param name The notation name. * @param publicId The notation's public identifier, or null. * @param systemId The notation's system identifier, or null. - * @exception org.xml.sax.SAXException The client may throw + * @throws org.xml.sax.SAXException The client may throw * an exception during processing. */ public void notationDecl (String name, String publicId, String systemId) @@ -422,7 +423,7 @@ public class XMLFilterImpl * @param publicId The entity's public identifier, or null. * @param systemId The entity's system identifier, or null. * @param notationName The name of the associated notation. - * @exception org.xml.sax.SAXException The client may throw + * @throws org.xml.sax.SAXException The client may throw * an exception during processing. */ public void unparsedEntityDecl (String name, String publicId, @@ -459,7 +460,7 @@ public class XMLFilterImpl /** * Filter a start document event. * - * @exception org.xml.sax.SAXException The client may throw + * @throws org.xml.sax.SAXException The client may throw * an exception during processing. */ public void startDocument () @@ -474,7 +475,7 @@ public class XMLFilterImpl /** * Filter an end document event. * - * @exception org.xml.sax.SAXException The client may throw + * @throws org.xml.sax.SAXException The client may throw * an exception during processing. */ public void endDocument () @@ -491,7 +492,7 @@ public class XMLFilterImpl * * @param prefix The Namespace prefix. * @param uri The Namespace URI. - * @exception org.xml.sax.SAXException The client may throw + * @throws org.xml.sax.SAXException The client may throw * an exception during processing. */ public void startPrefixMapping (String prefix, String uri) @@ -507,7 +508,7 @@ public class XMLFilterImpl * Filter an end Namespace prefix mapping event. * * @param prefix The Namespace prefix. - * @exception org.xml.sax.SAXException The client may throw + * @throws org.xml.sax.SAXException The client may throw * an exception during processing. */ public void endPrefixMapping (String prefix) @@ -527,7 +528,7 @@ public class XMLFilterImpl * @param qName The element's qualified (prefixed) name, or the empty * string. * @param atts The element's attributes. - * @exception org.xml.sax.SAXException The client may throw + * @throws org.xml.sax.SAXException The client may throw * an exception during processing. */ public void startElement (String uri, String localName, String qName, @@ -547,7 +548,7 @@ public class XMLFilterImpl * @param localName The element's local name, or the empty string. * @param qName The element's qualified (prefixed) name, or the empty * string. - * @exception org.xml.sax.SAXException The client may throw + * @throws org.xml.sax.SAXException The client may throw * an exception during processing. */ public void endElement (String uri, String localName, String qName) @@ -565,7 +566,7 @@ public class XMLFilterImpl * @param ch An array of characters. * @param start The starting position in the array. * @param length The number of characters to use from the array. - * @exception org.xml.sax.SAXException The client may throw + * @throws org.xml.sax.SAXException The client may throw * an exception during processing. */ public void characters (char ch[], int start, int length) @@ -583,7 +584,7 @@ public class XMLFilterImpl * @param ch An array of characters. * @param start The starting position in the array. * @param length The number of characters to use from the array. - * @exception org.xml.sax.SAXException The client may throw + * @throws org.xml.sax.SAXException The client may throw * an exception during processing. */ public void ignorableWhitespace (char ch[], int start, int length) @@ -600,7 +601,7 @@ public class XMLFilterImpl * * @param target The processing instruction target. * @param data The text following the target. - * @exception org.xml.sax.SAXException The client may throw + * @throws org.xml.sax.SAXException The client may throw * an exception during processing. */ public void processingInstruction (String target, String data) @@ -616,7 +617,7 @@ public class XMLFilterImpl * Filter a skipped entity event. * * @param name The name of the skipped entity. - * @exception org.xml.sax.SAXException The client may throw + * @throws org.xml.sax.SAXException The client may throw * an exception during processing. */ public void skippedEntity (String name) @@ -638,7 +639,7 @@ public class XMLFilterImpl * Filter a warning event. * * @param e The warning as an exception. - * @exception org.xml.sax.SAXException The client may throw + * @throws org.xml.sax.SAXException The client may throw * an exception during processing. */ public void warning (SAXParseException e) @@ -654,7 +655,7 @@ public class XMLFilterImpl * Filter an error event. * * @param e The error as an exception. - * @exception org.xml.sax.SAXException The client may throw + * @throws org.xml.sax.SAXException The client may throw * an exception during processing. */ public void error (SAXParseException e) @@ -670,7 +671,7 @@ public class XMLFilterImpl * Filter a fatal error event. * * @param e The error as an exception. - * @exception org.xml.sax.SAXException The client may throw + * @throws org.xml.sax.SAXException The client may throw * an exception during processing. */ public void fatalError (SAXParseException e) diff --git a/src/java.xml/share/classes/org/xml/sax/helpers/XMLReaderAdapter.java b/src/java.xml/share/classes/org/xml/sax/helpers/XMLReaderAdapter.java index 2cc05e24f8e..ddce3f8f7d7 100644 --- a/src/java.xml/share/classes/org/xml/sax/helpers/XMLReaderAdapter.java +++ b/src/java.xml/share/classes/org/xml/sax/helpers/XMLReaderAdapter.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -76,7 +76,7 @@ public class XMLReaderAdapter implements Parser, ContentHandler *

Use the "org.xml.sax.driver" property to locate the SAX2 * driver to embed.

* - * @exception org.xml.sax.SAXException If the embedded driver + * @throws org.xml.sax.SAXException If the embedded driver * cannot be instantiated or if the * org.xml.sax.driver property is not specified. */ @@ -95,7 +95,7 @@ public class XMLReaderAdapter implements Parser, ContentHandler * Parser.

* * @param xmlReader The SAX2 XMLReader to wrap. - * @exception java.lang.NullPointerException If the argument is null. + * @throws java.lang.NullPointerException If the argument is null. */ public XMLReaderAdapter (XMLReader xmlReader) { @@ -133,7 +133,7 @@ public class XMLReaderAdapter implements Parser, ContentHandler * * @param locale the locale for error reporting. * @see org.xml.sax.Parser#setLocale - * @exception org.xml.sax.SAXException Thrown unless overridden. + * @throws org.xml.sax.SAXException Thrown unless overridden. */ public void setLocale (Locale locale) throws SAXException @@ -201,9 +201,9 @@ public class XMLReaderAdapter implements Parser, ContentHandler * http://xml.org/sax/features/namespace-prefixes property.

* * @param systemId The absolute URL of the document. - * @exception java.io.IOException If there is a problem reading + * @throws java.io.IOException If there is a problem reading * the raw content of the document. - * @exception org.xml.sax.SAXException If there is a problem + * @throws org.xml.sax.SAXException If there is a problem * processing the document. * @see #parse(org.xml.sax.InputSource) * @see org.xml.sax.Parser#parse(java.lang.String) @@ -223,9 +223,9 @@ public class XMLReaderAdapter implements Parser, ContentHandler * http://xml.org/sax/features/namespace-prefixes property.

* * @param input An input source for the document. - * @exception java.io.IOException If there is a problem reading + * @throws java.io.IOException If there is a problem reading * the raw content of the document. - * @exception org.xml.sax.SAXException If there is a problem + * @throws org.xml.sax.SAXException If there is a problem * processing the document. * @see #parse(java.lang.String) * @see org.xml.sax.Parser#parse(org.xml.sax.InputSource) @@ -277,7 +277,7 @@ public class XMLReaderAdapter implements Parser, ContentHandler /** * Start document event. * - * @exception org.xml.sax.SAXException The client may raise a + * @throws org.xml.sax.SAXException The client may raise a * processing exception. * @see org.xml.sax.ContentHandler#startDocument */ @@ -292,7 +292,7 @@ public class XMLReaderAdapter implements Parser, ContentHandler /** * End document event. * - * @exception org.xml.sax.SAXException The client may raise a + * @throws org.xml.sax.SAXException The client may raise a * processing exception. * @see org.xml.sax.ContentHandler#endDocument */ @@ -334,7 +334,7 @@ public class XMLReaderAdapter implements Parser, ContentHandler * @param localName The Namespace local name. * @param qName The qualified (prefixed) name. * @param atts The SAX2 attributes. - * @exception org.xml.sax.SAXException The client may raise a + * @throws org.xml.sax.SAXException The client may raise a * processing exception. * @see org.xml.sax.ContentHandler#endDocument */ @@ -355,7 +355,7 @@ public class XMLReaderAdapter implements Parser, ContentHandler * @param uri The Namespace URI. * @param localName The Namespace local name. * @param qName The qualified (prefixed) name. - * @exception org.xml.sax.SAXException The client may raise a + * @throws org.xml.sax.SAXException The client may raise a * processing exception. * @see org.xml.sax.ContentHandler#endElement */ @@ -374,7 +374,7 @@ public class XMLReaderAdapter implements Parser, ContentHandler * @param ch An array of characters. * @param start The starting position in the array. * @param length The number of characters to use. - * @exception org.xml.sax.SAXException The client may raise a + * @throws org.xml.sax.SAXException The client may raise a * processing exception. * @see org.xml.sax.ContentHandler#characters */ @@ -392,7 +392,7 @@ public class XMLReaderAdapter implements Parser, ContentHandler * @param ch An array of characters. * @param start The starting position in the array. * @param length The number of characters to use. - * @exception org.xml.sax.SAXException The client may raise a + * @throws org.xml.sax.SAXException The client may raise a * processing exception. * @see org.xml.sax.ContentHandler#ignorableWhitespace */ @@ -409,7 +409,7 @@ public class XMLReaderAdapter implements Parser, ContentHandler * * @param target The processing instruction target. * @param data The remainder of the processing instruction - * @exception org.xml.sax.SAXException The client may raise a + * @throws org.xml.sax.SAXException The client may raise a * processing exception. * @see org.xml.sax.ContentHandler#processingInstruction */ @@ -426,7 +426,7 @@ public class XMLReaderAdapter implements Parser, ContentHandler * * @param name The name of the skipped entity. * @see org.xml.sax.ContentHandler#skippedEntity - * @exception org.xml.sax.SAXException Throwable by subclasses. + * @throws org.xml.sax.SAXException Throwable by subclasses. */ public void skippedEntity (String name) throws SAXException diff --git a/src/java.xml/share/classes/org/xml/sax/helpers/XMLReaderFactory.java b/src/java.xml/share/classes/org/xml/sax/helpers/XMLReaderFactory.java index 21fbdc47415..d89be6ea86d 100644 --- a/src/java.xml/share/classes/org/xml/sax/helpers/XMLReaderFactory.java +++ b/src/java.xml/share/classes/org/xml/sax/helpers/XMLReaderFactory.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -117,7 +117,7 @@ final public class XMLReaderFactory * removal in a future release. * * @return a new XMLReader. - * @exception org.xml.sax.SAXException If no default XMLReader class + * @throws org.xml.sax.SAXException If no default XMLReader class * can be identified and instantiated. * @see #createXMLReader(java.lang.String) */ @@ -166,8 +166,9 @@ final public class XMLReaderFactory * the caller (perhaps an applet) is not permitted to load classes * dynamically. * + * @param className a class name * @return A new XML reader. - * @exception org.xml.sax.SAXException If the class cannot be + * @throws org.xml.sax.SAXException If the class cannot be * loaded, instantiated, and cast to XMLReader. * @see #createXMLReader() */