< prev index next >
src/java.xml/share/classes/javax/xml/stream/XMLInputFactory.java
Print this page
@@ -1,7 +1,7 @@
/*
- * 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
@@ -133,10 +133,14 @@
public static final String ALLOCATOR=
"javax.xml.stream.allocator";
static final String DEFAULIMPL = "com.sun.xml.internal.stream.XMLInputFactoryImpl";
+ /**
+ * Protected constructor to prevent instantiation.
+ * Use {@link #newFactory()} instead.
+ */
protected XMLInputFactory(){}
/**
* Creates a new instance of the {@code XMLInputFactory} builtin
* system-default implementation.
@@ -151,10 +155,11 @@
}
/**
* 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()
throws FactoryConfigurationError
{
@@ -208,10 +213,11 @@
* </ul>
* <p>
* 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.
*/
public static XMLInputFactory newFactory()
@@ -219,11 +225,11 @@
{
return FactoryFinder.find(XMLInputFactory.class, DEFAULIMPL);
}
/**
- * 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
* @param classLoader classLoader to use
* @return the factory implementation
@@ -322,145 +328,163 @@
//do not fallback if given classloader can't find the class, throw exception
return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null);
}
/**
- * 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;
/**
* 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;
/**
* Create a new XMLEventReader from an XMLStreamReader. After being used
* to construct the XMLEventReader instance returned from this method
* 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;
/**
* 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
*/
public abstract XMLEventReader createXMLEventReader(Source source)
throws XMLStreamException;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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();
/**
* The resolver that will be set on any XMLStreamReader or XMLEventReader created
@@ -470,10 +494,11 @@
public abstract void setXMLResolver(XMLResolver resolver);
/**
* 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();
/**
* The reporter that will be set on any XMLStreamReader or XMLEventReader created
@@ -533,9 +558,10 @@
*/
public abstract void setEventAllocator(XMLEventAllocator allocator);
/**
* Gets the allocator used by streams created with this factory
+ * @return an instance of the {@code XMLEventAllocator}
*/
public abstract XMLEventAllocator getEventAllocator();
}
< prev index next >