From 32b041f81d5f54e431e52f06fe31a96a4e2a98fa Mon Sep 17 00:00:00 2001
From: dleslie <dleslie@13f79535-47bb-0310-9956-ffa450edef68>
Date: Tue, 22 Jan 2002 20:45:17 +0000
Subject: [PATCH] Bugzilla 2230. Added clarification that newInstance,
 newTransformer(), and newTemplates() can in fact return null if an
 ErrorHandler is registered with the factory and what would otherwise be an
 Exception occurs.

git-svn-id: https://svn.apache.org/repos/asf/xml/commons/trunk@225949 13f79535-47bb-0310-9956-ffa450edef68
---
 .../javax/xml/transform/TransformerFactory.java  | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/java/external/src/javax/xml/transform/TransformerFactory.java b/java/external/src/javax/xml/transform/TransformerFactory.java
index e28b679..990b268 100644
--- a/java/external/src/javax/xml/transform/TransformerFactory.java
+++ b/java/external/src/javax/xml/transform/TransformerFactory.java
@@ -127,7 +127,9 @@ public abstract class TransformerFactory {
      * TransformerFactory</code> it can use the factory to configure
      * and obtain parser instances.
      *
-     * @return new TransformerFactory instance, never null.
+     * @return new TransformerFactory instance, never null (unless an {@link ErrorListener} 
+     * is registered with the TransformerFactory, in which case an exception error sends an 
+     * error message to the ErrorListener and returns null).
      *
      * @throws TransformerFactoryConfigurationError
      * if the implmentation is not available or cannot be instantiated.
@@ -156,7 +158,9 @@ public abstract class TransformerFactory {
      * @param source An object that holds a URI, input stream, etc.
      *
      * @return A Transformer object that may be used to perform a transformation
-     * in a single thread, never null.
+     * in a single thread, never null (unless an {@link ErrorListener} is registered with
+     * the TransformerFactory, in which case an exception error sends an error message to
+     * the ErrorListener and returns null).
      *
      * @exception TransformerConfigurationException May throw this during the parse
      *            when it is constructing the Templates object and fails.
@@ -171,7 +175,9 @@ public abstract class TransformerFactory {
      * @param source An object that holds a URI, input stream, etc.
      *
      * @return A Transformer object that may be used to perform a transformation
-     * in a single thread, never null.
+     * in a single thread, never null (unless an {@link ErrorListener} is registered with
+     * the TransformerFactory, in which case an exception error sends an error message to
+     * the ErrorListener and returns null).
      *
      * @exception TransformerConfigurationException May throw this during
      *            the parse when it is constructing the
@@ -191,7 +197,9 @@ public abstract class TransformerFactory {
      * @param source An object that holds a URL, input stream, etc.
      *
      * @return A Templates object capable of being used for transformation purposes,
-     * never null.
+     * never null (unless an {@link ErrorListener} is registered with
+     * the TransformerFactory, in which case an exception error sends an error message to
+     * the ErrorListener and returns null).
      *
      * @exception TransformerConfigurationException May throw this during the parse when it
      *            is constructing the Templates object and fails.