archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-09-20 11:04:34 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8049378: Examine references to ${java.home}/lib in JAXP

Browse source 
Reviewed-by: lancea, alanb
This commit is contained in:
Joe Wang 2015-03-05 17:18:19 -08:00
parent cd16fed9b8
commit a953097a89
10 changed files with 356 additions and 201 deletions
Download patch file Download diff file Expand all files Collapse all files

26
jaxp/src/java.xml/share/classes/javax/xml/XMLConstants.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -247,9 +247,11 @@ public final class XMLConstants {
* </p> * </p>
* *
* <p> * <p>
* <b>${JAVA_HOME}/conf/jaxp.properties:</b> This configuration file is in standard * <b>jaxp.properties:</b> This configuration file is in standard
* {@link java.util.Properties} format. If the file exists and the system property is specified, * {@link java.util.Properties} format and typically located in the {@code conf}
* its value will be used to override the default of the property. * directory of the Java installation. If the file exists and the system
* property is specified, its value will be used to override the default
* of the property.
* </p> * </p>
* *
* <p> * <p>
@ -314,9 +316,11 @@ public final class XMLConstants {
* </p> * </p>
* *
* <p> * <p>
* <b>${JAVA_HOME}/conf/jaxp.properties:</b> This configuration file is in standard * <b>jaxp.properties:</b> This configuration file is in standard
* java.util.Properties format. If the file exists and the system property is specified, * {@link java.util.Properties} format and typically located in the {@code conf}
* its value will be used to override the default of the property. * directory of the Java installation. If the file exists and the system
* property is specified, its value will be used to override the default
* of the property.
* *
* @since 1.7 * @since 1.7
* </p> * </p>
@ -380,9 +384,11 @@ public final class XMLConstants {
* </p> * </p>
* *
* <p> * <p>
* <b>${JAVA_HOME}/conf/jaxp.properties: </b> This configuration file is in standard * <b>jaxp.properties:</b> This configuration file is in standard
* java.util.Properties format. If the file exists and the system property is specified, * {@link java.util.Properties} format and typically located in the {@code conf}
* its value will be used to override the default of the property. * directory of the Java installation. If the file exists and the system
* property is specified, its value will be used to override the default
* of the property.
* *
* @since 1.7 * @since 1.7
*/ */

54
jaxp/src/java.xml/share/classes/javax/xml/datatype/DatatypeFactory.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2004, 2013, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2004, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -32,23 +32,34 @@ import java.util.regex.Matcher;
import java.util.regex.Pattern; import java.util.regex.Pattern;
/** /**
* <p>Factory that creates new <code>javax.xml.datatype</code> <code>Object</code>s that map XML to/from Java <code>Object</code>s.</p> * Factory that creates new <code>javax.xml.datatype</code> <code>Object</code>s that map XML to/from Java <code>Object</code>s.
* * <p>
* <p>A new instance of the <code>DatatypeFactory</code> is created through the {@link #newInstance()} method * A new instance of the {@code DatatypeFactory} is created through the {@link #newInstance()} method
* that uses the following implementation resolution mechanisms to determine an implementation:</p> * that uses the following implementation resolution mechanisms to determine an implementation:
* <p>
* <ol> * <ol>
* <li> * <li>
* If the system property specified by {@link #DATATYPEFACTORY_PROPERTY}, "<code>javax.xml.datatype.DatatypeFactory</code>", * If the system property specified by {@link #DATATYPEFACTORY_PROPERTY}, "{@code javax.xml.datatype.DatatypeFactory}",
* exists, a class with the name of the property value is instantiated. * exists, a class with the name of the property value is instantiated.
* Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}. * Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
* </li> * </li>
* <li> * <li>
* If the file ${JAVA_HOME}/conf/jaxp.properties exists, it is loaded in a {@link java.util.Properties} <code>Object</code>. * <p>
* The <code>Properties</code> <code>Object </code> is then queried for the property as documented in the prior step * Use the configuration file "jaxp.properties". The file is in standard
* and processed as documented in the prior step. * {@link java.util.Properties} format and typically located in the
* {@code conf} directory of the Java installation. It contains the fully qualified
* name of the implementation class with the key being the system property
* defined above.
* <p>
* The jaxp.properties file is read only once by the JAXP implementation
* and its values are then cached for future use. If the file does not exist
* when the first attempt is made to read from it, no further attempts are
* made to check for its existence. It is not possible to change the value
* of any property in jaxp.properties after it has been read for the first time.
* </li> * </li>
* <li> * <li>
* Uses the service-provider loading facilities, defined by the {@link java.util.ServiceLoader} class, to attempt * <p>
* Use the service-provider loading facility, defined by the {@link java.util.ServiceLoader} class, to attempt
* to locate and load an implementation of the service using the {@linkplain * to locate and load an implementation of the service using the {@linkplain
* java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
* the service-provider loading facility will use the {@linkplain * the service-provider loading facility will use the {@linkplain
@ -56,13 +67,14 @@ import java.util.regex.Pattern;
* to attempt to load the service. If the context class * to attempt to load the service. If the context class
* loader is null, the {@linkplain * loader is null, the {@linkplain
* ClassLoader#getSystemClassLoader() system class loader} will be used. * ClassLoader#getSystemClassLoader() system class loader} will be used.
* <br> * <p>
* In case of {@link java.util.ServiceConfigurationError service * In case of {@link java.util.ServiceConfigurationError service
* configuration error} a {@link javax.xml.datatype.DatatypeConfigurationException} * configuration error}, a {@link javax.xml.datatype.DatatypeConfigurationException}
* will be thrown. * will be thrown.
* </li> * </li>
* <li> * <li>
* The final mechanism is to attempt to instantiate the <code>Class</code> specified by * <p>
* The final mechanism is to attempt to instantiate the {@code Class} specified by
* {@link #DATATYPEFACTORY_IMPLEMENTATION_CLASS}. * {@link #DATATYPEFACTORY_IMPLEMENTATION_CLASS}.
* Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}. * Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
* </li> * </li>
@ -79,7 +91,7 @@ public abstract class DatatypeFactory {
/** /**
* <p>Default property name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.</p> * <p>Default property name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.</p>
* *
* <p>Default value is <code>javax.xml.datatype.DatatypeFactory</code>.</p> * <p>Default value is {@code javax.xml.datatype.DatatypeFactory}.</p>
*/ */
public static final String DATATYPEFACTORY_PROPERTY = public static final String DATATYPEFACTORY_PROPERTY =
// We use a String constant here, rather than calling // We use a String constant here, rather than calling
@ -120,18 +132,18 @@ public abstract class DatatypeFactory {
/** /**
* <p>Protected constructor to prevent instantiation outside of package.</p> * <p>Protected constructor to prevent instantiation outside of package.</p>
* *
* <p>Use {@link #newInstance()} to create a <code>DatatypeFactory</code>.</p> * <p>Use {@link #newInstance()} to create a {@code DatatypeFactory}.</p>
*/ */
protected DatatypeFactory() { protected DatatypeFactory() {
} }
/** /**
* <p>Obtain a new instance of a <code>DatatypeFactory</code>.</p> * <p>Obtain a new instance of a {@code DatatypeFactory}.</p>
* *
* <p>The implementation resolution mechanisms are <a href="#DatatypeFactory.newInstance">defined</a> in this * <p>The implementation resolution mechanisms are <a href="#DatatypeFactory.newInstance">defined</a> in this
* <code>Class</code>'s documentation.</p> * <code>Class</code>'s documentation.</p>
* *
* @return New instance of a <code>DatatypeFactory</code> * @return New instance of a {@code DatatypeFactory}
* *
* @throws DatatypeConfigurationException If the implementation is not * @throws DatatypeConfigurationException If the implementation is not
* available or cannot be instantiated. * available or cannot be instantiated.
@ -149,12 +161,12 @@ public abstract class DatatypeFactory {
} }
/** /**
* <p>Obtain a new instance of a <code>DatatypeFactory</code> from class name. * <p>Obtain a new instance of a {@code DatatypeFactory} from class name.
* This function is useful when there are multiple providers in the classpath. * This function is useful when there are multiple providers in the classpath.
* It gives more control to the application as it can specify which provider * It gives more control to the application as it can specify which provider
* should be loaded.</p> * should be loaded.</p>
* *
* <p>Once an application has obtained a reference to a <code>DatatypeFactory</code> * <p>Once an application has obtained a reference to a {@code DatatypeFactory}
* it can use the factory to configure and obtain datatype instances.</P> * it can use the factory to configure and obtain datatype instances.</P>
* *
* *
@ -168,12 +180,12 @@ public abstract class DatatypeFactory {
* java -Djaxp.debug=1 YourProgram .... * java -Djaxp.debug=1 YourProgram ....
* </pre> * </pre>
* *
* @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.datatype.DatatypeFactory</code>. * @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.datatype.DatatypeFactory}.
* *
* @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code> * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
* current <code>Thread</code>'s context classLoader is used to load the factory class. * current <code>Thread</code>'s context classLoader is used to load the factory class.
* *
* @return New instance of a <code>DatatypeFactory</code> * @return New instance of a {@code DatatypeFactory}
* *
* @throws DatatypeConfigurationException if <code>factoryClassName</code> is <code>null</code>, or * @throws DatatypeConfigurationException if <code>factoryClassName</code> is <code>null</code>, or
* the factory class cannot be loaded, instantiated. * the factory class cannot be loaded, instantiated.

71
jaxp/src/java.xml/share/classes/javax/xml/parsers/DocumentBuilderFactory.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -55,31 +55,34 @@ public abstract class DocumentBuilderFactory {
/** /**
* Obtain a new instance of a * Obtain a new instance of a
* <code>DocumentBuilderFactory</code>. This static method creates * {@code DocumentBuilderFactory}. This static method creates
* a new factory instance. * a new factory instance.
* This method uses the following ordered lookup procedure to determine * This method uses the following ordered lookup procedure to determine
* the <code>DocumentBuilderFactory</code> implementation class to * the {@code DocumentBuilderFactory} implementation class to
* load: * load:
* <p>
* <ul> * <ul>
* <li> * <li>
* Use the <code>javax.xml.parsers.DocumentBuilderFactory</code> system * Use the {@code javax.xml.parsers.DocumentBuilderFactory} system
* property. * property.
* </li> * </li>
* <li> * <li>
* Use the properties file "conf/jaxp.properties" in the JRE directory. * <p>
* This configuration file is in standard <code>java.util.Properties * Use the configuration file "jaxp.properties". The file is in standard
* </code> format and contains the fully qualified name of the * {@link java.util.Properties} format and typically located in the
* implementation class with the key being the system property defined * {@code conf} directory of the Java installation. It contains the fully qualified
* above. * name of the implementation class with the key being the system property
* * defined above.
* <p>
* The jaxp.properties file is read only once by the JAXP implementation * The jaxp.properties file is read only once by the JAXP implementation
* and it's values are then cached for future use. If the file does not exist * and its values are then cached for future use. If the file does not exist
* when the first attempt is made to read from it, no further attempts are * when the first attempt is made to read from it, no further attempts are
* made to check for its existence. It is not possible to change the value * made to check for its existence. It is not possible to change the value
* of any property in jaxp.properties after it has been read for the first time. * of any property in jaxp.properties after it has been read for the first time.
* </li> * </li>
* <li> * <li>
* Uses the service-provider loading facilities, defined by the * <p>
* Use the service-provider loading facility, defined by the
* {@link java.util.ServiceLoader} class, to attempt to locate and load an * {@link java.util.ServiceLoader} class, to attempt to locate and load an
* implementation of the service using the {@linkplain * implementation of the service using the {@linkplain
* java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
@ -90,26 +93,30 @@ public abstract class DocumentBuilderFactory {
* ClassLoader#getSystemClassLoader() system class loader} will be used. * ClassLoader#getSystemClassLoader() system class loader} will be used.
* </li> * </li>
* <li> * <li>
* <p>
* Otherwise, the system-default implementation is returned. * Otherwise, the system-default implementation is returned.
* </li> * </li>
* </ul> * </ul>
* *
* <p>
* Once an application has obtained a reference to a * Once an application has obtained a reference to a
* <code>DocumentBuilderFactory</code> it can use the factory to * {@code DocumentBuilderFactory} it can use the factory to
* configure and obtain parser instances. * configure and obtain parser instances.
* *
* *
* <h2>Tip for Trouble-shooting</h2> * <h2>Tip for Trouble-shooting</h2>
* <p>Setting the <code>jaxp.debug</code> system property will cause * <p>
* Setting the {@code jaxp.debug} system property will cause
* this method to print a lot of debug messages * this method to print a lot of debug messages
* to <code>System.err</code> about what it is doing and where it is looking at.</p> * to {@code System.err} about what it is doing and where it is looking at.
* *
* <p> If you have problems loading {@link DocumentBuilder}s, try:</p> * <p>
* If you have problems loading {@link DocumentBuilder}s, try:
* <pre> * <pre>
* java -Djaxp.debug=1 YourProgram .... * java -Djaxp.debug=1 YourProgram ....
* </pre> * </pre>
* *
* @return New instance of a <code>DocumentBuilderFactory</code> * @return New instance of a {@code DocumentBuilderFactory}
* *
* @throws FactoryConfigurationError in case of {@linkplain * @throws FactoryConfigurationError in case of {@linkplain
* java.util.ServiceConfigurationError service configuration error} or if * java.util.ServiceConfigurationError service configuration error} or if
@ -124,31 +131,31 @@ public abstract class DocumentBuilderFactory {
} }
/** /**
* <p>Obtain a new instance of a <code>DocumentBuilderFactory</code> from class name. * <p>Obtain a new instance of a {@code DocumentBuilderFactory} from class name.
* This function is useful when there are multiple providers in the classpath. * This function is useful when there are multiple providers in the classpath.
* It gives more control to the application as it can specify which provider * It gives more control to the application as it can specify which provider
* should be loaded.</p> * should be loaded.
* *
* <p>Once an application has obtained a reference to a <code>DocumentBuilderFactory</code> * <p>Once an application has obtained a reference to a {@code DocumentBuilderFactory}
* it can use the factory to configure and obtain parser instances.</p> * it can use the factory to configure and obtain parser instances.
* *
* *
* <h2>Tip for Trouble-shooting</h2> * <h2>Tip for Trouble-shooting</h2>
* <p>Setting the <code>jaxp.debug</code> system property will cause * <p>Setting the {@code jaxp.debug} system property will cause
* this method to print a lot of debug messages * this method to print a lot of debug messages
* to <code>System.err</code> about what it is doing and where it is looking at.</p> * to {@code System.err} about what it is doing and where it is looking at.</p>
* *
* <p> If you have problems try:</p> * <p> If you have problems try:</p>
* <pre> * <pre>
* java -Djaxp.debug=1 YourProgram .... * java -Djaxp.debug=1 YourProgram ....
* </pre> * </pre>
* *
* @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.parsers.DocumentBuilderFactory</code>. * @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.parsers.DocumentBuilderFactory}.
* *
* @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code> * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
* current <code>Thread</code>'s context classLoader is used to load the factory class. * current <code>Thread</code>'s context classLoader is used to load the factory class.
* *
* @return New instance of a <code>DocumentBuilderFactory</code> * @return New instance of a {@code DocumentBuilderFactory}
* *
* @throws FactoryConfigurationError if <code>factoryClassName</code> is <code>null</code>, or * @throws FactoryConfigurationError if <code>factoryClassName</code> is <code>null</code>, or
* the factory class cannot be loaded, instantiated. * the factory class cannot be loaded, instantiated.
@ -406,14 +413,14 @@ public abstract class DocumentBuilderFactory {
throws IllegalArgumentException; throws IllegalArgumentException;
/** /**
* <p>Set a feature for this <code>DocumentBuilderFactory</code> and <code>DocumentBuilder</code>s created by this factory.</p> * <p>Set a feature for this {@code DocumentBuilderFactory} and <code>DocumentBuilder</code>s created by this factory.</p>
* *
* <p> * <p>
* Feature names are fully qualified {@link java.net.URI}s. * Feature names are fully qualified {@link java.net.URI}s.
* Implementations may define their own features. * Implementations may define their own features.
* A {@link ParserConfigurationException} is thrown if this <code>DocumentBuilderFactory</code> or the * A {@link ParserConfigurationException} is thrown if this {@code DocumentBuilderFactory} or the
* <code>DocumentBuilder</code>s it creates cannot support the feature. * <code>DocumentBuilder</code>s it creates cannot support the feature.
* It is possible for a <code>DocumentBuilderFactory</code> to expose a feature value but be unable to change its state. * It is possible for a {@code DocumentBuilderFactory} to expose a feature value but be unable to change its state.
* </p> * </p>
* *
* <p> * <p>
@ -436,7 +443,7 @@ public abstract class DocumentBuilderFactory {
* @param name Feature name. * @param name Feature name.
* @param value Is feature state <code>true</code> or <code>false</code>. * @param value Is feature state <code>true</code> or <code>false</code>.
* *
* @throws ParserConfigurationException if this <code>DocumentBuilderFactory</code> or the <code>DocumentBuilder</code>s * @throws ParserConfigurationException if this {@code DocumentBuilderFactory} or the <code>DocumentBuilder</code>s
* it creates cannot support this feature. * it creates cannot support this feature.
* @throws NullPointerException If the <code>name</code> parameter is null. * @throws NullPointerException If the <code>name</code> parameter is null.
* @since 1.5 * @since 1.5
@ -450,16 +457,16 @@ public abstract class DocumentBuilderFactory {
* <p> * <p>
* Feature names are fully qualified {@link java.net.URI}s. * Feature names are fully qualified {@link java.net.URI}s.
* Implementations may define their own features. * Implementations may define their own features.
* An {@link ParserConfigurationException} is thrown if this <code>DocumentBuilderFactory</code> or the * An {@link ParserConfigurationException} is thrown if this {@code DocumentBuilderFactory} or the
* <code>DocumentBuilder</code>s it creates cannot support the feature. * <code>DocumentBuilder</code>s it creates cannot support the feature.
* It is possible for an <code>DocumentBuilderFactory</code> to expose a feature value but be unable to change its state. * It is possible for an {@code DocumentBuilderFactory} to expose a feature value but be unable to change its state.
* </p> * </p>
* *
* @param name Feature name. * @param name Feature name.
* *
* @return State of the named feature. * @return State of the named feature.
* *
* @throws ParserConfigurationException if this <code>DocumentBuilderFactory</code> * @throws ParserConfigurationException if this {@code DocumentBuilderFactory}
* or the <code>DocumentBuilder</code>s it creates cannot support this feature. * or the <code>DocumentBuilder</code>s it creates cannot support this feature.
* @since 1.5 * @since 1.5
*/ */

54
jaxp/src/java.xml/share/classes/javax/xml/parsers/SAXParserFactory.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -59,31 +59,34 @@ public abstract class SAXParserFactory {
} }
/** /**
* Obtain a new instance of a <code>SAXParserFactory</code>. This * Obtain a new instance of a {@code SAXParserFactory}. This
* static method creates a new factory instance * static method creates a new factory instance
* This method uses the following ordered lookup procedure to determine * This method uses the following ordered lookup procedure to determine
* the <code>SAXParserFactory</code> implementation class to * the {@code SAXParserFactory} implementation class to
* load: * load:
* <p>
* <ul> * <ul>
* <li> * <li>
* Use the <code>javax.xml.parsers.SAXParserFactory</code> system * Use the {@code javax.xml.parsers.SAXParserFactory} system
* property. * property.
* </li> * </li>
* <li> * <li>
* Use the properties file "conf/jaxp.properties" in the JRE directory. * <p>
* This configuration file is in standard <code>java.util.Properties * Use the configuration file "jaxp.properties". The file is in standard
* </code> format and contains the fully qualified name of the * {@link java.util.Properties} format and typically located in the
* implementation class with the key being the system property defined * {@code conf} directory of the Java installation. It contains the fully qualified
* above. * name of the implementation class with the key being the system property
* * defined above.
* <p>
* The jaxp.properties file is read only once by the JAXP implementation * The jaxp.properties file is read only once by the JAXP implementation
* and it's values are then cached for future use. If the file does not exist * and its values are then cached for future use. If the file does not exist
* when the first attempt is made to read from it, no further attempts are * when the first attempt is made to read from it, no further attempts are
* made to check for its existence. It is not possible to change the value * made to check for its existence. It is not possible to change the value
* of any property in jaxp.properties after it has been read for the first time. * of any property in jaxp.properties after it has been read for the first time.
* </li> * </li>
* <li> * <li>
* Use the service-provider loading facilities, defined by the * <p>
* Use the service-provider loading facility, defined by the
* {@link java.util.ServiceLoader} class, to attempt to locate and load an * {@link java.util.ServiceLoader} class, to attempt to locate and load an
* implementation of the service using the {@linkplain * implementation of the service using the {@linkplain
* java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
@ -94,22 +97,26 @@ public abstract class SAXParserFactory {
* ClassLoader#getSystemClassLoader() system class loader} will be used. * ClassLoader#getSystemClassLoader() system class loader} will be used.
* </li> * </li>
* <li> * <li>
* <p>
* Otherwise the system-default implementation is returned. * Otherwise the system-default implementation is returned.
* </li> * </li>
* </ul> * </ul>
* *
* <p>
* Once an application has obtained a reference to a * Once an application has obtained a reference to a
* <code>SAXParserFactory</code> it can use the factory to * {@code SAXParserFactory} it can use the factory to
* configure and obtain parser instances. * configure and obtain parser instances.
* *
* *
* *
* <h2>Tip for Trouble-shooting</h2> * <h2>Tip for Trouble-shooting</h2>
* <p>Setting the <code>jaxp.debug</code> system property will cause * <p>
* Setting the {@code jaxp.debug} system property will cause
* this method to print a lot of debug messages * this method to print a lot of debug messages
* to <code>System.err</code> about what it is doing and where it is looking at.</p> * to {@code System.err} about what it is doing and where it is looking at.
* *
* <p> If you have problems loading {@link SAXParser}s, try:</p> * <p>
* If you have problems loading {@link SAXParser}s, try:
* <pre> * <pre>
* java -Djaxp.debug=1 YourProgram .... * java -Djaxp.debug=1 YourProgram ....
* </pre> * </pre>
@ -131,31 +138,32 @@ public abstract class SAXParserFactory {
} }
/** /**
* <p>Obtain a new instance of a <code>SAXParserFactory</code> from class name. * <p>Obtain a new instance of a {@code SAXParserFactory} from class name.
* This function is useful when there are multiple providers in the classpath. * This function is useful when there are multiple providers in the classpath.
* It gives more control to the application as it can specify which provider * It gives more control to the application as it can specify which provider
* should be loaded.</p> * should be loaded.</p>
* *
* <p>Once an application has obtained a reference to a <code>SAXParserFactory</code> * <p>Once an application has obtained a reference to a {@code SAXParserFactory}
* it can use the factory to configure and obtain parser instances.</p> * it can use the factory to configure and obtain parser instances.</p>
* *
* *
* <h2>Tip for Trouble-shooting</h2> * <h2>Tip for Trouble-shooting</h2>
* <p>Setting the <code>jaxp.debug</code> system property will cause * <p>Setting the {@code jaxp.debug} system property will cause
* this method to print a lot of debug messages * this method to print a lot of debug messages
* to <code>System.err</code> about what it is doing and where it is looking at.</p> * to {@code System.err} about what it is doing and where it is looking at.</p>
* *
* <p> If you have problems, try:</p> * <p>
* If you have problems, try:
* <pre> * <pre>
* java -Djaxp.debug=1 YourProgram .... * java -Djaxp.debug=1 YourProgram ....
* </pre> * </pre>
* *
* @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.parsers.SAXParserFactory</code>. * @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.parsers.SAXParserFactory}.
* *
* @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code> * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
* current <code>Thread</code>'s context classLoader is used to load the factory class. * current <code>Thread</code>'s context classLoader is used to load the factory class.
* *
* @return New instance of a <code>SAXParserFactory</code> * @return New instance of a {@code SAXParserFactory}
* *
* @throws FactoryConfigurationError if <code>factoryClassName</code> is <code>null</code>, or * @throws FactoryConfigurationError if <code>factoryClassName</code> is <code>null</code>, or
* the factory class cannot be loaded, instantiated. * the factory class cannot be loaded, instantiated.

62
jaxp/src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java
View file

@ -23,7 +23,7 @@
*/ */
/* /*
* Copyright (c) 2009, 2013, by Oracle Corporation. All Rights Reserved. * Copyright (c) 2009, 2015, by Oracle Corporation. All Rights Reserved.
*/ */
package javax.xml.stream; package javax.xml.stream;
@ -70,19 +70,34 @@ public abstract class XMLEventFactory {
* This static method creates a new factory instance. * This static method creates a new factory instance.
* This method uses the following ordered lookup procedure to determine * This method uses the following ordered lookup procedure to determine
* the XMLEventFactory implementation class to load: * the XMLEventFactory implementation class to load:
* </p> * <p>
* <ul> * <ul>
* <li> * <li>
* Use the javax.xml.stream.XMLEventFactory system property. * Use the javax.xml.stream.XMLEventFactory system property.
* </li> * </li>
* <li> * <li>
* Use the properties file "lib/stax.properties" in the JRE directory. * <p>
* This configuration file is in standard java.util.Properties format * Use the configuration file "stax.properties". The file is in standard
* and contains the fully qualified name of the implementation class * {@link java.util.Properties} format and typically located in the
* with the key being the system property defined above. * {@code conf} directory of the Java installation. It contains the fully qualified
* name of the implementation class with the key being the system property
* defined above.
*
* <p>
* The stax.properties file is read only once by the implementation
* and its values are then cached for future use. If the file does not exist
* when the first attempt is made to read from it, no further attempts are
* made to check for its existence. It is not possible to change the value
* of any property in stax.properties after it has been read for the first time.
*
* <p>
* Use the jaxp configuration file "jaxp.properties". The file is in the same
* format as stax.properties and will only be read if stax.properties does
* not exist.
* </li> * </li>
* <li> * <li>
* Use the service-provider loading facilities, defined by the * <p>
* Use the service-provider loading facility, defined by the
* {@link java.util.ServiceLoader} class, to attempt to locate and load an * {@link java.util.ServiceLoader} class, to attempt to locate and load an
* implementation of the service using the {@linkplain * implementation of the service using the {@linkplain
* java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
@ -93,18 +108,18 @@ public abstract class XMLEventFactory {
* ClassLoader#getSystemClassLoader() system class loader} will be used. * ClassLoader#getSystemClassLoader() system class loader} will be used.
* </li> * </li>
* <li> * <li>
* <p>
* Otherwise, the system-default implementation is returned. * Otherwise, the system-default implementation is returned.
* </li> * </li>
* </ul> * </ul>
* <p> * <p>
* Once an application has obtained a reference to a XMLEventFactory it * Once an application has obtained a reference to a XMLEventFactory it
* can use the factory to configure and obtain stream instances. * can use the factory to configure and obtain stream instances.
* </p>
* <p> * <p>
* Note that this is a new method that replaces the deprecated newInstance() method. * Note that this is a new method that replaces the deprecated newInstance() method.
* No changes in behavior are defined by this replacement method relative to * No changes in behavior are defined by this replacement method relative to
* the deprecated method. * the deprecated method.
* </p> *
* @throws FactoryConfigurationError in case of {@linkplain * @throws FactoryConfigurationError in case of {@linkplain
* java.util.ServiceConfigurationError service configuration error} or if * java.util.ServiceConfigurationError service configuration error} or if
* the implementation is not available or cannot be instantiated. * the implementation is not available or cannot be instantiated.
@ -143,20 +158,35 @@ public abstract class XMLEventFactory {
* <p> * <p>
* This method uses the following ordered lookup procedure to determine * This method uses the following ordered lookup procedure to determine
* the XMLEventFactory implementation class to load: * the XMLEventFactory implementation class to load:
* </p> * <p>
* <ul> * <ul>
* <li> * <li>
* Use the value of the system property identified by {@code factoryId}. * Use the value of the system property identified by {@code factoryId}.
* </li> * </li>
* <li> * <li>
* Use the properties file "lib/stax.properties" in the JRE directory. * <p>
* This configuration file is in standard java.util.Properties format * Use the configuration file "stax.properties". The file is in standard
* and contains the fully qualified name of the implementation class * {@link java.util.Properties} format and typically located in the
* with the key being the given {@code factoryId}. * conf directory of the Java installation. It contains the fully qualified
* name of the implementation class with the key being the system property
* defined above.
*
* <p>
* The stax.properties file is read only once by the implementation
* and its values are then cached for future use. If the file does not exist
* when the first attempt is made to read from it, no further attempts are
* made to check for its existence. It is not possible to change the value
* of any property in stax.properties after it has been read for the first time.
*
* <p>
* Use the jaxp configuration file "jaxp.properties". The file is in the same
* format as stax.properties and will only be read if stax.properties does
* not exist.
* </li> * </li>
* <li> * <li>
* <p>
* If {@code factoryId} is "javax.xml.stream.XMLEventFactory", * If {@code factoryId} is "javax.xml.stream.XMLEventFactory",
* use the service-provider loading facilities, defined by the * use the service-provider loading facility, defined by the
* {@link java.util.ServiceLoader} class, to attempt to {@linkplain * {@link java.util.ServiceLoader} class, to attempt to {@linkplain
* java.util.ServiceLoader#load(java.lang.Class, java.lang.ClassLoader) locate and load} * java.util.ServiceLoader#load(java.lang.Class, java.lang.ClassLoader) locate and load}
* an implementation of the service using the specified {@code ClassLoader}. * an implementation of the service using the specified {@code ClassLoader}.
@ -169,6 +199,7 @@ public abstract class XMLEventFactory {
* ClassLoader#getSystemClassLoader() system class loader} will be used. * ClassLoader#getSystemClassLoader() system class loader} will be used.
* </li> * </li>
* <li> * <li>
* <p>
* Otherwise, throws a {@link FactoryConfigurationError}. * Otherwise, throws a {@link FactoryConfigurationError}.
* </li> * </li>
* </ul> * </ul>
@ -179,7 +210,6 @@ public abstract class XMLEventFactory {
* newInstance(String factoryId, ClassLoader classLoader)} method. * newInstance(String factoryId, ClassLoader classLoader)} method.
* No changes in behavior are defined by this replacement method relative * No changes in behavior are defined by this replacement method relative
* to the deprecated method. * to the deprecated method.
* </p>
* *
* @apiNote The parameter factoryId defined here is inconsistent with that * @apiNote The parameter factoryId defined here is inconsistent with that
* of other JAXP factories where the first parameter is fully qualified * of other JAXP factories where the first parameter is fully qualified

59
jaxp/src/java.xml/share/classes/javax/xml/stream/XMLInputFactory.java
View file

@ -68,7 +68,7 @@ import javax.xml.transform.Source;
* *
* *
* @version 1.2 * @version 1.2
* @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. * @author Copyright (c) 2009, 2015 by Oracle Corporation. All Rights Reserved.
* @see XMLOutputFactory * @see XMLOutputFactory
* @see XMLEventReader * @see XMLEventReader
* @see XMLStreamReader * @see XMLStreamReader
@ -163,16 +163,28 @@ public abstract class XMLInputFactory {
* </p> * </p>
* <ul> * <ul>
* <li> * <li>
* Use the javax.xml.stream.XMLInputFactory system property. * <p>Use the javax.xml.stream.XMLInputFactory system property.
* </li> * </li>
* <li> * <li>
* Use the properties file "lib/stax.properties" in the JRE directory. * <p>Use the configuration file "stax.properties". The file is in standard
* This configuration file is in standard java.util.Properties format * {@link java.util.Properties} format and typically located in the
* and contains the fully qualified name of the implementation class * {@code conf} directory of the Java installation. It contains the fully qualified
* with the key being the system property defined above. * name of the implementation class with the key being the system property
* defined above.
*
* <p>The stax.properties file is read only once by the implementation
* and its values are then cached for future use. If the file does not exist
* when the first attempt is made to read from it, no further attempts are
* made to check for its existence. It is not possible to change the value
* of any property in stax.properties after it has been read for the first time.
*
* <p>
* Use the jaxp configuration file "jaxp.properties". The file is in the same
* format as stax.properties and will only be read if stax.properties does
* not exist.
* </li> * </li>
* <li> * <li>
* Use the service-provider loading facilities, defined by the * <p>Use the service-provider loading facility, defined by the
* {@link java.util.ServiceLoader} class, to attempt to locate and load an * {@link java.util.ServiceLoader} class, to attempt to locate and load an
* implementation of the service using the {@linkplain * implementation of the service using the {@linkplain
* java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
@ -183,7 +195,7 @@ public abstract class XMLInputFactory {
* ClassLoader#getSystemClassLoader() system class loader} will be used. * ClassLoader#getSystemClassLoader() system class loader} will be used.
* </li> * </li>
* <li> * <li>
* Otherwise, the system-default implementation is returned. * <p>Otherwise, the system-default implementation is returned.
* </li> * </li>
* </ul> * </ul>
* <p> * <p>
@ -233,20 +245,36 @@ public abstract class XMLInputFactory {
* <p> * <p>
* This method uses the following ordered lookup procedure to determine * This method uses the following ordered lookup procedure to determine
* the XMLInputFactory implementation class to load: * the XMLInputFactory implementation class to load:
* </p> * <p>
* <ul> * <ul>
* <li> * <li>
* <p>
* Use the value of the system property identified by {@code factoryId}. * Use the value of the system property identified by {@code factoryId}.
* </li> * </li>
* <li> * <li>
* Use the properties file "lib/stax.properties" in the JRE directory. * <p>
* This configuration file is in standard java.util.Properties format * Use the configuration file "stax.properties". The file is in standard
* and contains the fully qualified name of the implementation class * {@link java.util.Properties} format and typically located in the
* with the key being the given {@code factoryId}. * {@code conf} directory of the Java installation. It contains the fully qualified
* name of the implementation class with the key being the system property
* defined above.
*
* <p>
* The stax.properties file is read only once by the implementation
* and its values are then cached for future use. If the file does not exist
* when the first attempt is made to read from it, no further attempts are
* made to check for its existence. It is not possible to change the value
* of any property in stax.properties after it has been read for the first time.
*
* <p>
* Use the jaxp configuration file "jaxp.properties". The file is in the same
* format as stax.properties and will only be read if stax.properties does
* not exist.
* </li> * </li>
* <li> * <li>
* <p>
* If {@code factoryId} is "javax.xml.stream.XMLInputFactory", * If {@code factoryId} is "javax.xml.stream.XMLInputFactory",
* use the service-provider loading facilities, defined by the * use the service-provider loading facility, defined by the
* {@link java.util.ServiceLoader} class, to attempt to {@linkplain * {@link java.util.ServiceLoader} class, to attempt to {@linkplain
* java.util.ServiceLoader#load(java.lang.Class, java.lang.ClassLoader) locate and load} * java.util.ServiceLoader#load(java.lang.Class, java.lang.ClassLoader) locate and load}
* an implementation of the service using the specified {@code ClassLoader}. * an implementation of the service using the specified {@code ClassLoader}.
@ -259,6 +287,7 @@ public abstract class XMLInputFactory {
* ClassLoader#getSystemClassLoader() system class loader} will be used. * ClassLoader#getSystemClassLoader() system class loader} will be used.
* </li> * </li>
* <li> * <li>
* <p>
* Otherwise, throws a {@link FactoryConfigurationError}. * Otherwise, throws a {@link FactoryConfigurationError}.
* </li> * </li>
* </ul> * </ul>
@ -269,7 +298,7 @@ public abstract class XMLInputFactory {
* newInstance(String factoryId, ClassLoader classLoader)} method. * newInstance(String factoryId, ClassLoader classLoader)} method.
* No changes in behavior are defined by this replacement method relative * No changes in behavior are defined by this replacement method relative
* to the deprecated method. * to the deprecated method.
* </p> *
* *
* @apiNote The parameter factoryId defined here is inconsistent with that * @apiNote The parameter factoryId defined here is inconsistent with that
* of other JAXP factories where the first parameter is fully qualified * of other JAXP factories where the first parameter is fully qualified

63
jaxp/src/java.xml/share/classes/javax/xml/stream/XMLOutputFactory.java
View file

@ -102,7 +102,7 @@ import javax.xml.transform.Result;
* namespace URI of the element or attribute using that prefix.</p> * namespace URI of the element or attribute using that prefix.</p>
* *
* @version 1.2 * @version 1.2
* @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. * @author Copyright (c) 2009, 2015 by Oracle Corporation. All Rights Reserved.
* @see XMLInputFactory * @see XMLInputFactory
* @see XMLEventWriter * @see XMLEventWriter
* @see XMLStreamWriter * @see XMLStreamWriter
@ -136,19 +136,34 @@ public abstract class XMLOutputFactory {
* This static method creates a new factory instance. This method uses the * This static method creates a new factory instance. This method uses the
* following ordered lookup procedure to determine the XMLOutputFactory * following ordered lookup procedure to determine the XMLOutputFactory
* implementation class to load: * implementation class to load:
* </p> * <p>
* <ul> * <ul>
* <li> * <li>
* Use the javax.xml.stream.XMLOutputFactory system property. * Use the javax.xml.stream.XMLOutputFactory system property.
* </li> * </li>
* <li> * <li>
* Use the properties file "lib/stax.properties" in the JRE directory. * <p>
* This configuration file is in standard java.util.Properties format * Use the configuration file "stax.properties". The file is in standard
* and contains the fully qualified name of the implementation class * {@link java.util.Properties} format and typically located in the
* with the key being the system property defined above. * {@code conf} directory of the Java installation. It contains the fully qualified
* name of the implementation class with the key being the system property
* defined above.
*
* <p>
* The stax.properties file is read only once by the implementation
* and its values are then cached for future use. If the file does not exist
* when the first attempt is made to read from it, no further attempts are
* made to check for its existence. It is not possible to change the value
* of any property in stax.properties after it has been read for the first time.
*
* <p>
* Use the jaxp configuration file "jaxp.properties". The file is in the same
* format as stax.properties and will only be read if stax.properties does
* not exist.
* </li> * </li>
* <li> * <li>
* Use the service-provider loading facilities, defined by the * <p>
* Use the service-provider loading facility, defined by the
* {@link java.util.ServiceLoader} class, to attempt to locate and load an * {@link java.util.ServiceLoader} class, to attempt to locate and load an
* implementation of the service using the {@linkplain * implementation of the service using the {@linkplain
* java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
@ -159,17 +174,17 @@ public abstract class XMLOutputFactory {
* ClassLoader#getSystemClassLoader() system class loader} will be used. * ClassLoader#getSystemClassLoader() system class loader} will be used.
* </li> * </li>
* <li> * <li>
* <p>
* Otherwise, the system-default implementation is returned. * Otherwise, the system-default implementation is returned.
* </li> * </li>
* <p> * <p>
* Once an application has obtained a reference to a XMLOutputFactory it * Once an application has obtained a reference to a XMLOutputFactory it
* can use the factory to configure and obtain stream instances. * can use the factory to configure and obtain stream instances.
* </p>
* <p> * <p>
* Note that this is a new method that replaces the deprecated newInstance() method. * Note that this is a new method that replaces the deprecated newInstance() method.
* No changes in behavior are defined by this replacement method relative to the * No changes in behavior are defined by this replacement method relative to the
* deprecated method. * deprecated method.
* </p> *
* @throws FactoryConfigurationError in case of {@linkplain * @throws FactoryConfigurationError in case of {@linkplain
* java.util.ServiceConfigurationError service configuration error} or if * java.util.ServiceConfigurationError service configuration error} or if
* the implementation is not available or cannot be instantiated. * the implementation is not available or cannot be instantiated.
@ -207,20 +222,35 @@ public abstract class XMLOutputFactory {
* <p> * <p>
* This method uses the following ordered lookup procedure to determine * This method uses the following ordered lookup procedure to determine
* the XMLOutputFactory implementation class to load: * the XMLOutputFactory implementation class to load:
* </p> * <p>
* <ul> * <ul>
* <li> * <li>
* Use the value of the system property identified by {@code factoryId}. * Use the value of the system property identified by {@code factoryId}.
* </li> * </li>
* <li> * <li>
* Use the properties file "lib/stax.properties" in the JRE directory. * <p>
* This configuration file is in standard java.util.Properties format * Use the configuration file "stax.properties". The file is in standard
* and contains the fully qualified name of the implementation class * {@link java.util.Properties} format and typically located in the
* with the key being the given {@code factoryId}. * {@code conf} directory of the Java installation. It contains the fully qualified
* name of the implementation class with the key being the system property
* defined above.
*
* <p>
* The stax.properties file is read only once by the implementation
* and its values are then cached for future use. If the file does not exist
* when the first attempt is made to read from it, no further attempts are
* made to check for its existence. It is not possible to change the value
* of any property in stax.properties after it has been read for the first time.
*
* <p>
* Use the jaxp configuration file "jaxp.properties". The file is in the same
* format as stax.properties and will only be read if stax.properties does
* not exist.
* </li> * </li>
* <li> * <li>
* <p>
* If {@code factoryId} is "javax.xml.stream.XMLOutputFactory", * If {@code factoryId} is "javax.xml.stream.XMLOutputFactory",
* use the service-provider loading facilities, defined by the * use the service-provider loading facility, defined by the
* {@link java.util.ServiceLoader} class, to attempt to {@linkplain * {@link java.util.ServiceLoader} class, to attempt to {@linkplain
* java.util.ServiceLoader#load(java.lang.Class, java.lang.ClassLoader) locate and load} * java.util.ServiceLoader#load(java.lang.Class, java.lang.ClassLoader) locate and load}
* an implementation of the service using the specified {@code ClassLoader}. * an implementation of the service using the specified {@code ClassLoader}.
@ -233,6 +263,7 @@ public abstract class XMLOutputFactory {
* ClassLoader#getSystemClassLoader() system class loader} will be used. * ClassLoader#getSystemClassLoader() system class loader} will be used.
* </li> * </li>
* <li> * <li>
* <p>
* Otherwise, throws a {@link FactoryConfigurationError}. * Otherwise, throws a {@link FactoryConfigurationError}.
* </li> * </li>
* </ul> * </ul>
@ -246,7 +277,7 @@ public abstract class XMLOutputFactory {
* {@link #newInstance(java.lang.String, java.lang.ClassLoader) * {@link #newInstance(java.lang.String, java.lang.ClassLoader)
* newInstance(String factoryId, ClassLoader classLoader)} method. * newInstance(String factoryId, ClassLoader classLoader)} method.
* The original method was incorrectly defined to return XMLInputFactory. * The original method was incorrectly defined to return XMLInputFactory.
* </p> *
* *
* @param factoryId Name of the factory to find, same as * @param factoryId Name of the factory to find, same as
* a property name * a property name

67
jaxp/src/java.xml/share/classes/javax/xml/transform/TransformerFactory.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -33,7 +33,7 @@ package javax.xml.transform;
* <p>The system property that determines which Factory implementation * <p>The system property that determines which Factory implementation
* to create is named <code>"javax.xml.transform.TransformerFactory"</code>. * to create is named <code>"javax.xml.transform.TransformerFactory"</code>.
* This property names a concrete subclass of the * This property names a concrete subclass of the
* <code>TransformerFactory</code> abstract class. If the property is not * {@code TransformerFactory} abstract class. If the property is not
* defined, a platform default is be used.</p> * defined, a platform default is be used.</p>
* *
* @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
@ -51,31 +51,36 @@ public abstract class TransformerFactory {
/** /**
* <p>Obtain a new instance of a <code>TransformerFactory</code>. * <p>
* This static method creates a new factory instance.</p> * Obtain a new instance of a {@code TransformerFactory}.
* <p>This method uses the following ordered lookup procedure to determine * This static method creates a new factory instance.
* the <code>TransformerFactory</code> implementation class to * <p>
* load:</p> * This method uses the following ordered lookup procedure to determine
* the {@code TransformerFactory} implementation class to
* load:
* <p>
* <ul> * <ul>
* <li> * <li>
* Use the <code>javax.xml.transform.TransformerFactory</code> system * Use the {@code javax.xml.transform.TransformerFactory} system
* property. * property.
* </li> * </li>
* <li> * <li>
* Use the properties file "conf/jaxp.properties" in the JRE directory. * <p>
* This configuration file is in standard <code>java.util.Properties * Use the configuration file "jaxp.properties". The file is in standard
* </code> format and contains the fully qualified name of the * {@link java.util.Properties} format and typically located in the
* implementation class with the key being the system property defined * {@code conf} directory of the Java installation. It contains the fully qualified
* above. * name of the implementation class with the key being the system property
* <br> * defined above.
* <p>
* The jaxp.properties file is read only once by the JAXP implementation * The jaxp.properties file is read only once by the JAXP implementation
* and it's values are then cached for future use. If the file does not exist * and its values are then cached for future use. If the file does not exist
* when the first attempt is made to read from it, no further attempts are * when the first attempt is made to read from it, no further attempts are
* made to check for its existence. It is not possible to change the value * made to check for its existence. It is not possible to change the value
* of any property in jaxp.properties after it has been read for the first time. * of any property in jaxp.properties after it has been read for the first time.
* </li> * </li>
* <li> * <li>
* Use the service-provider loading facilities, defined by the * <p>
* Use the service-provider loading facility, defined by the
* {@link java.util.ServiceLoader} class, to attempt to locate and load an * {@link java.util.ServiceLoader} class, to attempt to locate and load an
* implementation of the service using the {@linkplain * implementation of the service using the {@linkplain
* java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
@ -86,13 +91,15 @@ public abstract class TransformerFactory {
* ClassLoader#getSystemClassLoader() system class loader} will be used. * ClassLoader#getSystemClassLoader() system class loader} will be used.
* </li> * </li>
* <li> * <li>
* <p>
* Otherwise, the system-default implementation is returned. * Otherwise, the system-default implementation is returned.
* </li> * </li>
* </ul> * </ul>
* *
* <p>Once an application has obtained a reference to a <code> * <p>
* TransformerFactory</code> it can use the factory to configure * Once an application has obtained a reference to a
* and obtain transformer instances.</p> * {@code TransformerFactory} it can use the factory to configure
* and obtain transformer instances.
* *
* @return new TransformerFactory instance, never null. * @return new TransformerFactory instance, never null.
* *
@ -111,13 +118,13 @@ public abstract class TransformerFactory {
} }
/** /**
* <p>Obtain a new instance of a <code>TransformerFactory</code> from factory class name. * <p>Obtain a new instance of a {@code TransformerFactory} from factory class name.
* This function is useful when there are multiple providers in the classpath. * This function is useful when there are multiple providers in the classpath.
* It gives more control to the application as it can specify which provider * It gives more control to the application as it can specify which provider
* should be loaded.</p> * should be loaded.</p>
* *
* <p>Once an application has obtained a reference to a <code> * <p>Once an application has obtained a reference to a
* TransformerFactory</code> it can use the factory to configure * {@code TransformerFactory} it can use the factory to configure
* and obtain transformer instances.</p> * and obtain transformer instances.</p>
* *
* <h2>Tip for Trouble-shooting</h2> * <h2>Tip for Trouble-shooting</h2>
@ -130,7 +137,7 @@ public abstract class TransformerFactory {
* java -Djaxp.debug=1 YourProgram .... * java -Djaxp.debug=1 YourProgram ....
* </pre> * </pre>
* *
* @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.transform.TransformerFactory</code>. * @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.transform.TransformerFactory}.
* *
* @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code> * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
* current <code>Thread</code>'s context classLoader is used to load the factory class. * current <code>Thread</code>'s context classLoader is used to load the factory class.
@ -232,7 +239,7 @@ public abstract class TransformerFactory {
* @param charset The value of the charset attribute to match. May be null. * @param charset The value of the charset attribute to match. May be null.
* *
* @return A <code>Source</code> <code>Object</code> suitable for passing * @return A <code>Source</code> <code>Object</code> suitable for passing
* to the <code>TransformerFactory</code>. * to the {@code TransformerFactory}.
* *
* @throws TransformerConfigurationException An <code>Exception</code> * @throws TransformerConfigurationException An <code>Exception</code>
* is thrown if an error occurings during parsing of the * is thrown if an error occurings during parsing of the
@ -268,15 +275,15 @@ public abstract class TransformerFactory {
//======= CONFIGURATION METHODS ======= //======= CONFIGURATION METHODS =======
/** /**
* <p>Set a feature for this <code>TransformerFactory</code> and <code>Transformer</code>s * <p>Set a feature for this {@code TransformerFactory} and <code>Transformer</code>s
* or <code>Template</code>s created by this factory.</p> * or <code>Template</code>s created by this factory.</p>
* *
* <p> * <p>
* Feature names are fully qualified {@link java.net.URI}s. * Feature names are fully qualified {@link java.net.URI}s.
* Implementations may define their own features. * Implementations may define their own features.
* An {@link TransformerConfigurationException} is thrown if this <code>TransformerFactory</code> or the * An {@link TransformerConfigurationException} is thrown if this {@code TransformerFactory} or the
* <code>Transformer</code>s or <code>Template</code>s it creates cannot support the feature. * <code>Transformer</code>s or <code>Template</code>s it creates cannot support the feature.
* It is possible for an <code>TransformerFactory</code> to expose a feature value but be unable to change its state. * It is possible for an {@code TransformerFactory} to expose a feature value but be unable to change its state.
* </p> * </p>
* *
* <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature. * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
@ -299,7 +306,7 @@ public abstract class TransformerFactory {
* @param name Feature name. * @param name Feature name.
* @param value Is feature state <code>true</code> or <code>false</code>. * @param value Is feature state <code>true</code> or <code>false</code>.
* *
* @throws TransformerConfigurationException if this <code>TransformerFactory</code> * @throws TransformerConfigurationException if this {@code TransformerFactory}
* or the <code>Transformer</code>s or <code>Template</code>s it creates cannot support this feature. * or the <code>Transformer</code>s or <code>Template</code>s it creates cannot support this feature.
* @throws NullPointerException If the <code>name</code> parameter is null. * @throws NullPointerException If the <code>name</code> parameter is null.
*/ */
@ -312,9 +319,9 @@ public abstract class TransformerFactory {
* <p> * <p>
* Feature names are fully qualified {@link java.net.URI}s. * Feature names are fully qualified {@link java.net.URI}s.
* Implementations may define their own features. * Implementations may define their own features.
* <code>false</code> is returned if this <code>TransformerFactory</code> or the * <code>false</code> is returned if this {@code TransformerFactory} or the
* <code>Transformer</code>s or <code>Template</code>s it creates cannot support the feature. * <code>Transformer</code>s or <code>Template</code>s it creates cannot support the feature.
* It is possible for an <code>TransformerFactory</code> to expose a feature value but be unable to change its state. * It is possible for an {@code TransformerFactory} to expose a feature value but be unable to change its state.
* </p> * </p>
* *
* @param name Feature name. * @param name Feature name.

30
jaxp/src/java.xml/share/classes/javax/xml/validation/SchemaFactory.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -132,8 +132,9 @@ public abstract class SchemaFactory {
* where "the class loader" refers to the context class loader:</p> * where "the class loader" refers to the context class loader:</p>
* <ol> * <ol>
* <li> * <li>
* <p>
* If the system property * If the system property
* <code>"javax.xml.validation.SchemaFactory:<i>schemaLanguage</i>"</code> * {@code "javax.xml.validation.SchemaFactory:<i>schemaLanguage</i>"}
* is present (where <i>schemaLanguage</i> is the parameter * is present (where <i>schemaLanguage</i> is the parameter
* to this method), then its value is read * to this method), then its value is read
* as a class name. The method will try to * as a class name. The method will try to
@ -141,12 +142,22 @@ public abstract class SchemaFactory {
* and returns it if it is successfully created. * and returns it if it is successfully created.
* </li> * </li>
* <li> * <li>
* <code>$java.home/conf/jaxp.properties</code> is read and * <p>
* the value associated with the key being the system property above * Use the configuration file "jaxp.properties". The file is in standard
* is looked for. If present, the value is processed just like above. * {@link java.util.Properties} format and typically located in the
* conf directory of the Java installation. It contains the fully qualified
* name of the implementation class with the key being the system property
* defined above.
* <p>
* The jaxp.properties file is read only once by the JAXP implementation
* and its values are then cached for future use. If the file does not exist
* when the first attempt is made to read from it, no further attempts are
* made to check for its existence. It is not possible to change the value
* of any property in jaxp.properties after it has been read for the first time.
* </li> * </li>
* <li> * <li>
* Use the service-provider loading facilities, defined by the * <p>
* Use the service-provider loading facility, defined by the
* {@link java.util.ServiceLoader} class, to attempt to locate and load an * {@link java.util.ServiceLoader} class, to attempt to locate and load an
* implementation of the service using the {@linkplain * implementation of the service using the {@linkplain
* java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
@ -166,19 +177,20 @@ public abstract class SchemaFactory {
* {@link SchemaFactoryConfigurationError} will be thrown. * {@link SchemaFactoryConfigurationError} will be thrown.
* </li> * </li>
* <li> * <li>
* <p>
* Platform default <code>SchemaFactory</code> is located * Platform default <code>SchemaFactory</code> is located
* in a implementation specific way. There must be a platform default * in a implementation specific way. There must be a platform default
* <code>SchemaFactory</code> for W3C XML Schema. * <code>SchemaFactory</code> for W3C XML Schema.
* </li> * </li>
* </ol> * </ol>
* *
* <p>If everything fails, {@link IllegalArgumentException} will be thrown.</p> * <p>If everything fails, {@link IllegalArgumentException} will be thrown.
* *
* <p><strong>Tip for Trouble-shooting:</strong></p> * <p><strong>Tip for Trouble-shooting:</strong>
* <p>See {@link java.util.Properties#load(java.io.InputStream)} for * <p>See {@link java.util.Properties#load(java.io.InputStream)} for
* exactly how a property file is parsed. In particular, colons ':' * exactly how a property file is parsed. In particular, colons ':'
* need to be escaped in a property file, so make sure schema language * need to be escaped in a property file, so make sure schema language
* URIs are properly escaped in it. For example:</p> * URIs are properly escaped in it. For example:
* <pre> * <pre>
* http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory * http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory
* </pre> * </pre>

71
jaxp/src/java.xml/share/classes/javax/xml/xpath/XPathFactory.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -26,7 +26,7 @@
package javax.xml.xpath; package javax.xml.xpath;
/** /**
* <p>An <code>XPathFactory</code> instance can be used to create * <p>An {@code XPathFactory} instance can be used to create
* {@link javax.xml.xpath.XPath} objects.</p> * {@link javax.xml.xpath.XPath} objects.</p>
* *
*<p>See {@link #newInstance(String uri)} for lookup mechanism.</p> *<p>See {@link #newInstance(String uri)} for lookup mechanism.</p>
@ -68,13 +68,13 @@ public abstract class XPathFactory {
/** /**
* <p>Protected constructor as {@link #newInstance()} or {@link #newInstance(String uri)} * <p>Protected constructor as {@link #newInstance()} or {@link #newInstance(String uri)}
* or {@link #newInstance(String uri, String factoryClassName, ClassLoader classLoader)} * or {@link #newInstance(String uri, String factoryClassName, ClassLoader classLoader)}
* should be used to create a new instance of an <code>XPathFactory</code>.</p> * should be used to create a new instance of an {@code XPathFactory}.</p>
*/ */
protected XPathFactory() { protected XPathFactory() {
} }
/** /**
* <p>Get a new <code>XPathFactory</code> instance using the default object model, * <p>Get a new {@code XPathFactory} instance using the default object model,
* {@link #DEFAULT_OBJECT_MODEL_URI}, * {@link #DEFAULT_OBJECT_MODEL_URI},
* the W3C DOM.</p> * the W3C DOM.</p>
* *
@ -85,10 +85,10 @@ public abstract class XPathFactory {
* *
* <p>Since the implementation for the W3C DOM is always available, this method will never fail.</p> * <p>Since the implementation for the W3C DOM is always available, this method will never fail.</p>
* *
* @return Instance of an <code>XPathFactory</code>. * @return Instance of an {@code XPathFactory}.
* *
* @throws RuntimeException When there is a failure in creating an * @throws RuntimeException When there is a failure in creating an
* <code>XPathFactory</code> for the default object model. * {@code XPathFactory} for the default object model.
*/ */
public static XPathFactory newInstance() { public static XPathFactory newInstance() {
@ -105,23 +105,35 @@ public abstract class XPathFactory {
} }
/** /**
* <p>Get a new <code>XPathFactory</code> instance using the specified object model.</p> * <p>Get a new {@code XPathFactory} instance using the specified object model.</p>
* *
* <p>To find a <code>XPathFactory</code> object, * <p>To find a {@code XPathFactory} object,
* this method looks the following places in the following order where "the class loader" refers to the context class loader:</p> * this method looks the following places in the following order where "the class loader" refers to the context class loader:</p>
* <ol> * <ol>
* <li> * <li>
* <p>
* If the system property {@link #DEFAULT_PROPERTY_NAME} + ":uri" is present, * If the system property {@link #DEFAULT_PROPERTY_NAME} + ":uri" is present,
* where uri is the parameter to this method, then its value is read as a class name. * where uri is the parameter to this method, then its value is read as a class name.
* The method will try to create a new instance of this class by using the class loader, * The method will try to create a new instance of this class by using the class loader,
* and returns it if it is successfully created. * and returns it if it is successfully created.
* </li> * </li>
* <li> * <li>
* ${java.home}/lib/jaxp.properties is read and the value associated with the key being the system property above is looked for. * <p>
* If present, the value is processed just like above. * Use the configuration file "jaxp.properties". The file is in standard
* {@link java.util.Properties} format and typically located in the
* conf directory of the Java installation. It contains the fully qualified
* name of the implementation class with the key being the system property
* defined above.
* <p>
* The jaxp.properties file is read only once by the JAXP implementation
* and its values are then cached for future use. If the file does not exist
* when the first attempt is made to read from it, no further attempts are
* made to check for its existence. It is not possible to change the value
* of any property in jaxp.properties after it has been read for the first time.
* </li> * </li>
* <li> * <li>
* Use the service-provider loading facilities, defined by the * <p>
* Use the service-provider loading facility, defined by the
* {@link java.util.ServiceLoader} class, to attempt to locate and load an * {@link java.util.ServiceLoader} class, to attempt to locate and load an
* implementation of the service using the {@linkplain * implementation of the service using the {@linkplain
* java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
@ -140,16 +152,17 @@ public abstract class XPathFactory {
* {@link XPathFactoryConfigurationException} will be thrown. * {@link XPathFactoryConfigurationException} will be thrown.
* </li> * </li>
* <li> * <li>
* Platform default <code>XPathFactory</code> is located in a platform specific way. * <p>
* Platform default {@code XPathFactory} is located in a platform specific way.
* There must be a platform default XPathFactory for the W3C DOM, i.e. {@link #DEFAULT_OBJECT_MODEL_URI}. * There must be a platform default XPathFactory for the W3C DOM, i.e. {@link #DEFAULT_OBJECT_MODEL_URI}.
* </li> * </li>
* </ol> * </ol>
* <p>If everything fails, an <code>XPathFactoryConfigurationException</code> will be thrown.</p> * <p>If everything fails, an {@code XPathFactoryConfigurationException} will be thrown.
* *
* <p>Tip for Trouble-shooting:</p> * <p>Tip for Trouble-shooting:
* <p>See {@link java.util.Properties#load(java.io.InputStream)} for exactly how a property file is parsed. * <p>See {@link java.util.Properties#load(java.io.InputStream)} for exactly how a property file is parsed.
* In particular, colons ':' need to be escaped in a property file, so make sure the URIs are properly escaped in it. * In particular, colons ':' need to be escaped in a property file, so make sure the URIs are properly escaped in it.
* For example:</p> * For example:
* <pre> * <pre>
* http\://java.sun.com/jaxp/xpath/dom=org.acme.DomXPathFactory * http\://java.sun.com/jaxp/xpath/dom=org.acme.DomXPathFactory
* </pre> * </pre>
@ -159,7 +172,7 @@ public abstract class XPathFactory {
* <code>http://java.sun.com/jaxp/xpath/dom</code> for the W3C DOM, * <code>http://java.sun.com/jaxp/xpath/dom</code> for the W3C DOM,
* the org.w3c.dom package, and implementations are free to introduce other URIs for other object models. * the org.w3c.dom package, and implementations are free to introduce other URIs for other object models.
* *
* @return Instance of an <code>XPathFactory</code>. * @return Instance of an {@code XPathFactory}.
* *
* @throws XPathFactoryConfigurationException If the specified object model * @throws XPathFactoryConfigurationException If the specified object model
* is unavailable, or if there is a configuration error. * is unavailable, or if there is a configuration error.
@ -199,7 +212,7 @@ public abstract class XPathFactory {
} }
/** /**
* <p>Obtain a new instance of a <code>XPathFactory</code> from a factory class name. <code>XPathFactory</code> * <p>Obtain a new instance of a {@code XPathFactory} from a factory class name. {@code XPathFactory}
* is returned if specified factory class supports the specified object model. * is returned if specified factory class supports the specified object model.
* This function is useful when there are multiple providers in the classpath. * This function is useful when there are multiple providers in the classpath.
* It gives more control to the application as it can specify which provider * It gives more control to the application as it can specify which provider
@ -227,7 +240,7 @@ public abstract class XPathFactory {
* current <code>Thread</code>'s context classLoader is used to load the factory class. * current <code>Thread</code>'s context classLoader is used to load the factory class.
* *
* *
* @return New instance of a <code>XPathFactory</code> * @return New instance of a {@code XPathFactory}
* *
* @throws XPathFactoryConfigurationException * @throws XPathFactoryConfigurationException
* if <code>factoryClassName</code> is <code>null</code>, or * if <code>factoryClassName</code> is <code>null</code>, or
@ -281,11 +294,11 @@ public abstract class XPathFactory {
} }
/** /**
* <p>Is specified object model supported by this <code>XPathFactory</code>?</p> * <p>Is specified object model supported by this {@code XPathFactory}?</p>
* *
* @param objectModel Specifies the object model which the returned <code>XPathFactory</code> will understand. * @param objectModel Specifies the object model which the returned {@code XPathFactory} will understand.
* *
* @return <code>true</code> if <code>XPathFactory</code> supports <code>objectModel</code>, else <code>false</code>. * @return <code>true</code> if {@code XPathFactory} supports <code>objectModel</code>, else <code>false</code>.
* *
* @throws NullPointerException If <code>objectModel</code> is <code>null</code>. * @throws NullPointerException If <code>objectModel</code> is <code>null</code>.
* @throws IllegalArgumentException If <code>objectModel.length() == 0</code>. * @throws IllegalArgumentException If <code>objectModel.length() == 0</code>.
@ -293,16 +306,16 @@ public abstract class XPathFactory {
public abstract boolean isObjectModelSupported(String objectModel); public abstract boolean isObjectModelSupported(String objectModel);
/** /**
* <p>Set a feature for this <code>XPathFactory</code> and * <p>Set a feature for this {@code XPathFactory} and
* <code>XPath</code>s created by this factory.</p> * <code>XPath</code>s created by this factory.</p>
* *
* <p> * <p>
* Feature names are fully qualified {@link java.net.URI}s. * Feature names are fully qualified {@link java.net.URI}s.
* Implementations may define their own features. * Implementations may define their own features.
* An {@link XPathFactoryConfigurationException} is thrown if this * An {@link XPathFactoryConfigurationException} is thrown if this
* <code>XPathFactory</code> or the <code>XPath</code>s * {@code XPathFactory} or the <code>XPath</code>s
* it creates cannot support the feature. * it creates cannot support the feature.
* It is possible for an <code>XPathFactory</code> to expose a feature value * It is possible for an {@code XPathFactory} to expose a feature value
* but be unable to change its state. * but be unable to change its state.
* </p> * </p>
* *
@ -316,7 +329,7 @@ public abstract class XPathFactory {
* @param name Feature name. * @param name Feature name.
* @param value Is feature state <code>true</code> or <code>false</code>. * @param value Is feature state <code>true</code> or <code>false</code>.
* *
* @throws XPathFactoryConfigurationException if this <code>XPathFactory</code> or the <code>XPath</code>s * @throws XPathFactoryConfigurationException if this {@code XPathFactory} or the <code>XPath</code>s
* it creates cannot support this feature. * it creates cannot support this feature.
* @throws NullPointerException if <code>name</code> is <code>null</code>. * @throws NullPointerException if <code>name</code> is <code>null</code>.
*/ */
@ -330,9 +343,9 @@ public abstract class XPathFactory {
* Feature names are fully qualified {@link java.net.URI}s. * Feature names are fully qualified {@link java.net.URI}s.
* Implementations may define their own features. * Implementations may define their own features.
* An {@link XPathFactoryConfigurationException} is thrown if this * An {@link XPathFactoryConfigurationException} is thrown if this
* <code>XPathFactory</code> or the <code>XPath</code>s * {@code XPathFactory} or the <code>XPath</code>s
* it creates cannot support the feature. * it creates cannot support the feature.
* It is possible for an <code>XPathFactory</code> to expose a feature value * It is possible for an {@code XPathFactory} to expose a feature value
* but be unable to change its state. * but be unable to change its state.
* </p> * </p>
* *
@ -341,7 +354,7 @@ public abstract class XPathFactory {
* @return State of the named feature. * @return State of the named feature.
* *
* @throws XPathFactoryConfigurationException if this * @throws XPathFactoryConfigurationException if this
* <code>XPathFactory</code> or the <code>XPath</code>s * {@code XPathFactory} or the <code>XPath</code>s
* it creates cannot support this feature. * it creates cannot support this feature.
* @throws NullPointerException if <code>name</code> is <code>null</code>. * @throws NullPointerException if <code>name</code> is <code>null</code>.
*/ */
@ -382,7 +395,7 @@ public abstract class XPathFactory {
/** /**
* <p>Return a new <code>XPath</code> using the underlying object * <p>Return a new <code>XPath</code> using the underlying object
* model determined when the <code>XPathFactory</code> was instantiated.</p> * model determined when the {@code XPathFactory} was instantiated.</p>
* *
* @return New instance of an <code>XPath</code>. * @return New instance of an <code>XPath</code>.
*/ */