You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by dl...@locus.apache.org on 2000/11/14 18:02:40 UTC
cvs commit: xml-xalan/java/src/javax/xml/transform ErrorListener.java Features.java OutputKeys.java Result.java Source.java SourceLocator.java Templates.java Transformer.java TransformerFactory.java URIResolver.java
dleslie 00/11/14 09:02:40
Modified: java/src/javax/xml/transform ErrorListener.java
Features.java OutputKeys.java Result.java
Source.java SourceLocator.java Templates.java
Transformer.java TransformerFactory.java
URIResolver.java
Log:
Javadoc updates.
Revision Changes Path
1.2 +37 -41 xml-xalan/java/src/javax/xml/transform/ErrorListener.java
Index: ErrorListener.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/ErrorListener.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ErrorListener.java 2000/11/13 16:26:27 1.1
+++ ErrorListener.java 2000/11/14 17:02:39 1.2
@@ -57,47 +57,44 @@
package javax.xml.transform;
/**
- * <p>If a client of a transformation needs to implement customized error
- * handling, it must implement this interface and then register an
- * instance with the Transformer using the setErrorListener
- * method. The Transformer will then report all errors and warnings
- * through this interface.</p>
+ * <p>To provide customized error handling, implement this interface and
+ * use the setErrorListener method to register an instance of the implmeentation
+ * with the Transformer. The Transformer then reports all errors and warnings through this interface.</p>
*
* <p>If an application does <em>not</em>
- * register an ErrorListener, errors will be reported to System.err.</p>
+ * register an ErrorListener, errors are reported to System.err.</p>
*
- * <p>For transformation errors, a transformer must use this interface
- * instead of throwing an exception: it is up to the application
- * to decide whether to throw an exception for different types of
- * errors and warnings. Note, however, that there is no requirement that
- * the transformer continue with the transformation after a call to
- * fatalError.</p>
- *
- * <p>Transformers may use this mechanism to report XML parsing errors
- * as well as transformation errors</p>
+ * <p>For transformation errors, a Transformer must use this interface
+ * instead of throwing an exception: it is up to the application
+ * to decide whether to throw an exception for different types of
+ * errors and warnings. Note however that the Transformer is not required
+ * to continue with the transformation after a call to fatalError.</p>
+ *
+ * <p>Transformers may use this mechanism to report XML parsing errors
+ * as well as transformation errors.</p>
*/
public interface ErrorListener
{
- /**
- * Receive notification of a warning.
- *
- * <p>Transformers will use this method to report conditions that
- * are not errors or fatal errors. The default behaviour is to
- * take no action.</p>
- *
- * <p>The Transformer must continue to with the transformation
- * after invoking this method: it should still be possible for the
- * application to process the document through to the end.</p>
- *
- * @param exception The warning information encapsulated in a
- * transformer exception.
- *
- * @throws javax.xml.transform.TransformerException if the application
- * chooses to discontinue the transformation.
- *
- * @see javax.xml.transform.TransformerException
- */
+ /**
+ * Receive notification of a warning.
+ *
+ * <p>Transformers can use this method to report conditions that
+ * are not errors or fatal errors. The default behaviour is to
+ * take no action.</p>
+ *
+ * <p>After invoking this method, the Transformer must continue with
+ * the transformation. It should still be possible for the
+ * application to process the document through to the end.</p>
+ *
+ * @param exception The warning information encapsulated in a
+ * transformer exception.
+ *
+ * @throws javax.xml.transform.TransformerException if the application
+ * chooses to discontinue the transformation.
+ *
+ * @see javax.xml.transform.TransformerException
+ */
public abstract void warning (TransformerException exception)
throws TransformerException;
@@ -106,7 +103,7 @@
* Receive notification of a recoverable error.
*
* <p>The transformer must continue to provide normal parsing events
- * after invoking this method: it should still be possible for the
+ * after invoking this method. It should still be possible for the
* application to process the document through to the end.</p>
*
* @param exception The error information encapsulated in a
@@ -124,12 +121,11 @@
/**
* Receive notification of a non-recoverable error.
*
- * <p>The application must assume that the transformation can
- * not continue after the transformer has invoked this method,
- * and should continue (if at all) only for the sake of collecting
- * addition error messages: in fact, transformers are free
- * to stop reporting any other events once this method has
- * been invoked.</p>
+ * <p>The application must assume that the transformation cannot
+ * continue after the Transformer has invoked this method,
+ * and should continue (if at all) only to collect
+ * addition error messages. In fact, Transformers are free
+ * to stop reporting events once this method has been invoked.</p>
*
* @param exception The error information encapsulated in a
* transformer exception.
1.3 +9 -7 xml-xalan/java/src/javax/xml/transform/Features.java
Index: Features.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/Features.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- Features.java 2000/11/14 16:51:47 1.2
+++ Features.java 2000/11/14 17:02:39 1.3
@@ -57,29 +57,31 @@
package javax.xml.transform;
/**
- * This class defines feature URLs that are supported by
- * the TrAX subpackages, such as sax, dom, etc.
+ * Defines feature URIs that are supported by the various
+ * TrAX subpackages, such as sax, dom, etc. A Transformer can use
+ * these values to do an identity comparison instead of a lexical
+ * comparison, which can greatly improve the performance of
+ * TransformerFactory#getFeature.
*/
public class Features
{
- /**
- * If TransformerFactory#getFeature returns true with this value
- * passed as a parameter, the transformer supports the interfaces
+ /* If TransformerFactory#getFeature returns true with this value
+ * passed as the parameter, the Transformer supports the interfaces
* found in the javax.xml.transform.sax package.
*/
public static final String SAX = "http://xml.org/trax/features/sax";
/**
* If TransformerFactory#getFeature returns true with this value
- * passed as a parameter, the transformer supports the interfaces
+ * passed as the parameter, the Transformer supports the interfaces
* found in the javax.xml.transform.dom package.
*/
public static final String DOM = "http://xml.org/trax/features/dom";
/**
* If TransformerFactory#getFeature returns true with this value
- * passed as a parameter, the transformer supports the interfaces
+ * passed as the parameter, the Transformer supports the interfaces
* found in the javax.xml.transform.stream package.
*/
public static final String STREAM = "http://xml.org/trax/features/stream";
1.2 +10 -10 xml-xalan/java/src/javax/xml/transform/OutputKeys.java
Index: OutputKeys.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/OutputKeys.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- OutputKeys.java 2000/11/13 16:26:27 1.1
+++ OutputKeys.java 2000/11/14 17:02:39 1.2
@@ -57,9 +57,9 @@
package javax.xml.transform;
/**
- * Class OutputKeys provides string constants that can be used to set
- * output properties on the Transformer class, or to retrieve
- * output properties on either Transformer or Templates instances.
+ * Provides string constants that can be used to set
+ * output properties for a Transformer, or to retrieve
+ * output properties from a Transformer or Templates object.
*
* @see <a href="http://www.w3.org/TR/xslt#output">section 16 of the
* XSL Transformations (XSLT) W3C Recommendation</a>
@@ -91,10 +91,10 @@
* encoding = <var>string</var>.
*
* <p><code>encoding</code> specifies the preferred character
- * encoding that the XSLT processor should use to encode sequences of
- * characters as sequences of bytes; the value of the attribute should be
- * treated case-insensitively; the value must contain only characters in
- * the range #x21 to #x7E (i.e. printable ASCII characters); the value
+ * encoding that the Transformer should use to encode sequences of
+ * characters as sequences of bytes. The value of the attribute should be
+ * treated case-insensitively. The value must only contain characters in
+ * the range #x21 to #x7E (i.e., printable ASCII characters). The value
* should either be a <code>charset</code> registered with the Internet
* Assigned Numbers Authority <a href="#IANA">[IANA]</a>,
* <a href="#RFC2278">[RFC2278]</a> or start with <code>X-</code>.</p>
@@ -117,7 +117,7 @@
/**
* standalone = "yes" | "no".
*
- * <p><code>standalone</code> specifies whether the XSLT processor
+ * <p><code>standalone</code> specifies whether the Transformer
* should output a standalone document declaration; the value must be
* <code>yes</code> or <code>no</code>.</p>
* @see <a href="http://www.w3.org/TR/xslt#output">section 16 of the
@@ -161,7 +161,7 @@
/**
* indent = "yes" | "no".
*
- * <p><code>indent</code> specifies whether the XSLT processor may
+ * <p><code>indent</code> specifies whether the Transformer may
* add additional whitespace when outputting the result tree; the value
* must be <code>yes</code> or <code>no</code>. </p>
* @see <a href="http://www.w3.org/TR/xslt#output">section 16 of the
@@ -174,7 +174,7 @@
*
* <p><code>media-type</code> specifies the media type (MIME
* content type) of the data that results from outputting the result
- * tree; the <code>charset</code> parameter should not be specified
+ * tree. The <code>charset</code> parameter should not be specified
* explicitly; instead, when the top-level media type is
* <code>text</code>, a <code>charset</code> parameter should be added
* according to the character encoding actually used by the output
1.3 +16 -18 xml-xalan/java/src/javax/xml/transform/Result.java
Index: Result.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/Result.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- Result.java 2000/11/13 16:26:28 1.2
+++ Result.java 2000/11/14 17:02:39 1.3
@@ -63,24 +63,23 @@
/**
* An object that implements this interface contains the information
- * needed to build a result tree for a transformation.
+ * needed to build a transformation result tree.
*/
public interface Result
{
/**
- * The name of a processing instruction that will be sent
- * if the result tree should switch to disabling output escaping mode.
+ * The name of the processing instruction that is sent if the
+ * result tree disables output escaping.
*
* <p>Normally, result tree serialization escapes & and < (and
* possibly other characters) when outputting text nodes.
* This ensures that the output is well-formed XML. However,
* it is sometimes convenient to be able to produce output that is
* almost, but not quite well-formed XML; for example,
- * the output may include ill-formed sections which are
- * intended to be transformed into well-formed XML by a
- * subsequent non-XML aware process. If a processing instruction is
- * sent with this name, serialization should be output
- * without any escaping. </p>
+ * the output may include ill-formed sections that will
+ * be transformed into well-formed XML by a subsequent non-XML aware
+ * process. If a processing instruction is sent with this name,
+ * serialization should be output without any escaping. </p>
*
* <p>Result DOM trees may also have PI_DISABLE_OUTPUT_ESCAPING and
* PI_ENABLE_OUTPUT_ESCAPING inserted into the tree.</p>
@@ -90,9 +89,9 @@
public static final String PI_DISABLE_OUTPUT_ESCAPING = "javax.xml.transform.disable-output-escaping";
/**
- * The name of a processing instruction that will be sent
- * if the result tree should switch to enabling output escaping mode,
- * following a PI_DISABLE_OUTPUT_ESCAPING processing instruction.
+ * The name of the processing instruction that is sent
+ * if the result tree enables output escaping at some point after having
+ * received a PI_DISABLE_OUTPUT_ESCAPING processing instruction.
*
* @see <a href="http://www.w3.org/TR/xslt#disable-output-escaping">disable-output-escaping in XSLT Specification</a>
*/
@@ -101,19 +100,18 @@
/**
* Set the system identifier for this Result.
*
- * <p>The system identifier is optional if the result is not
- * a system identifier, but it is still useful to provide one,
- * since the application can use it to resolve relative output identifiers,
- * and can include it in error messages and warnings.</p>
+ * <p>If the Result is not to be written to a file, the system identifier is optional.
+ * The application may still want to provide one, however, for use in error messages
+ * and warnings, or to resolve relative output identifiers.</p>
*
- * @param systemId The system identifier as a URL string.
+ * @param systemId The system identifier as a URI string.
*/
public void setSystemId(String systemId);
/**
* Get the system identifier that was set with setSystemId.
*
- * @return The system identifier that was set with setSystemId, or null
- * if setSystemId was not called.
+ * @return The system identifier that was set with setSystemId,
+ * or null if setSystemId was not called.
*/
public String getSystemId();}
1.3 +4 -4 xml-xalan/java/src/javax/xml/transform/Source.java
Index: Source.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/Source.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- Source.java 2000/11/13 16:26:28 1.2
+++ Source.java 2000/11/14 17:02:39 1.3
@@ -63,7 +63,7 @@
/**
* An object that implements this interface contains the information
- * needed to act as source input.
+ * needed to act as source input (XML source or transformation instructions).
*/
public interface Source
{
@@ -71,9 +71,9 @@
* Set the system identifier for this Source.
*
* <p>The system identifier is optional if the source does not
- * get it's data from a URL, but it is still useful to provide one,
- * since the application can use it to resolve relative URIs
- * and can include it in error messages and warnings.</p>
+ * get its data from a URL, but it may still be useful to provide one.
+ * The application can use a system identifier, for example, to resolve
+ * relative URIs and to include in error messages and warnings.</p>
*
* @param systemId The system identifier as a URL string.
*/
1.3 +7 -7 xml-xalan/java/src/javax/xml/transform/SourceLocator.java
Index: SourceLocator.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/SourceLocator.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- SourceLocator.java 2000/11/13 16:26:28 1.2
+++ SourceLocator.java 2000/11/14 17:02:39 1.3
@@ -58,7 +58,7 @@
/**
* This interface is primarily for the purposes of reporting where
- * an error occured in the source or transformation instructions.
+ * an error occurred in the XML source or transformation instructions.
*/
public interface SourceLocator
{
@@ -67,8 +67,8 @@
* Return the public identifier for the current document event.
*
* <p>The return value is the public identifier of the document
- * entity or of the external parsed entity in which the markup
- * triggering the event appears.</p>
+ * entity or of the external parsed entity in which the markup that
+ * triggered the event appears.</p>
*
* @return A string containing the public identifier, or
* null if none is available.
@@ -80,8 +80,8 @@
* Return the system identifier for the current document event.
*
* <p>The return value is the system identifier of the document
- * entity or of the external parsed entity in which the markup
- * triggering the event appears.</p>
+ * entity or of the external parsed entity in which the markup that
+ * triggered the event appears.</p>
*
* <p>If the system identifier is a URL, the parser must resolve it
* fully before passing it to the application.</p>
@@ -102,7 +102,7 @@
*
* <p>The return value is an approximation of the line number
* in the document entity or external parsed entity where the
- * markup triggering the event appears.</p>
+ * markup that triggered the event appears.</p>
*
* @return The line number, or -1 if none is available.
* @see #getColumnNumber
@@ -119,7 +119,7 @@
*
* <p>The return value is an approximation of the column number
* in the document entity or external parsed entity where the
- * markup triggering the event appears.</p>
+ * markup that triggered the event appears.</p>
*
* @return The column number, or -1 if none is available.
* @see #getLineNumber
1.3 +3 -3 xml-xalan/java/src/javax/xml/transform/Templates.java
Index: Templates.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/Templates.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- Templates.java 2000/11/13 16:26:28 1.2
+++ Templates.java 2000/11/14 17:02:39 1.3
@@ -61,11 +61,11 @@
import javax.xml.transform.TransformerException;
/**
- * The Templates object is the runtime representation of processed
+ * An object that implements this interface is the runtime representation of processed
* transformation instructions.
*
* <p>Templates must be threadsafe for a given instance
- * over multiple threads concurrently, and are generally meant to
+ * over multiple threads running concurrently, and may
* be used multiple times in a given session.</p>
*/
public interface Templates
@@ -82,7 +82,7 @@
/**
* Get the static properties for xsl:output. The object returned will
- * be a clone of the internal values, and thus it can be mutated
+ * be a clone of the internal values. Accordingly, it can be mutated
* without mutating the Templates object, and then handed in to
* the process method.
*
1.6 +34 -40 xml-xalan/java/src/javax/xml/transform/Transformer.java
Index: Transformer.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/Transformer.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- Transformer.java 2000/11/13 16:26:28 1.5
+++ Transformer.java 2000/11/14 17:02:39 1.6
@@ -59,15 +59,14 @@
import java.util.Properties;
/**
- * This object represents a Transformer, which can transform a
+ * An instace of this abstract class can transform a
* source tree into a result tree.
*
- * <p>An instance of this class can be obtained from the <code>
- * TransformerFactory.newTransformer</code> method. Once an instance
- * of this class is obtained, XML can be processed from a variety
- * of sources with the output from the transform being written
- * to a variety of sinks.</p>
* <p>An object of this class can not be used concurrently over
- * multiple threads.</p>
+ * <p>An instance of this class can be obtained with the <code>
+ * TransformerFactory.newTransformer</code> method. This instance may
+ * then be used to process XML from a variety of sources and write
+ * the transformation output to a variety of sink.</p>
* <p>An object of this class may not be used in multiple threads
+ * running concurrently.</p>
* <p>A Transformer may be used multiple times. Parameters and
* output properties are preserved across transformations.</p>
*/
@@ -77,7 +76,7 @@
/**
* Process the source tree to the output result.
* @param xmlSource The input for the source tree.
- * @param outputTarget The output source target.
+ * @param outputTarget The output target.
*
* @throws TransformerException If an unrecoverable error occurs
* during the course of the transformation.
@@ -88,23 +87,21 @@
/**
* Add a parameter for the transformation.
*
- * <p>In order to pass namespaced names, the name can be passed as
* a two-part string, with
- * the first part being the URL, the delimiter being the '{' for the start of the
- * URI and '}' signifies the end, with the local name following. If the qname has
- * a null URL, then the String object will only contain the local name. An
+ * <p>Pass a qualified name as a two-part string, the namespace URI
+ * enclosed in curly braces ({}), followed by the local name. If the
+ * name has a null URL, the String only contain the local name. An
* application can safely check for a non-null URI by testing to see if the first
* character of the name is a '{' character.</p>
* <p>For example, if a URI and local name were obtained from an element
* defined with <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>,
- * then the TrAX QName would be "{http://xyz.foo.com/yada/baz.html}foo". Note that
+ * then the TrAX name would be "{http://xyz.foo.com/yada/baz.html}foo". Note that
* no prefix is used.</p>
*
- * @param name The name of the parameter,
- * which may have a namespace URI.
- * @param value The value object. This can be any valid Java object
- * -- it's up to the processor to provide the proper
- * coersion to the object, or simply pass it on for use
- * in extensions.
+ * @param name The name of the parameter, which may begin with a namespace URI
+ * in curly braces ({}).
+ * @param value The value object. This can be any valid Java object. It is
+ * up to the processor to provide the proper object coersion or to simply
+ * pass the object on for use in an extension.
*/
public abstract void setParameter(String name, Object value);
@@ -112,11 +109,10 @@
* Get a parameter that was explicitly set with setParameter
* or setParameters.
*
- * <p>This does not return objects from default values of
- * parameters, since, among other reasons, these require a
- * node context to be evaluated, and thus can not be resolved
- * until the transformation is underway.</p>
- *
+ * <p>This method does not return a default parameter value, which
+ * cannot be determined until the node context is evaluated during
+ * the transformation process.
+ *
* @return A parameter that has been set with setParameter
* or setParameters.
*/
@@ -124,7 +120,7 @@
/**
* Set an object that will be used to resolve URIs used in
- * document(), etc.
+ * document(), xsl:import, or xsl:include.
*
* @param resolver An object that implements the URIResolver interface,
* or null.
@@ -142,28 +138,27 @@
/**
* Set the output properties for the transformation. These
- * properties will override properties set in the templates
+ * properties will override properties set in the Templates
* with xsl:output.
*
* <p>If argument to this function is null, any properties
- * previously set will be removed.</p>
+ * previously set are removed.</p>
*
- * <p>In order to pass namespaced names, the name can be passed as
* a two-part string, with
- * the first part being the URL, the delimiter being the '{' for the start of the
- * URI and '}' signifies the end, with the local name following. If the qname has
- * a null URL, then the String object will only contain the local name. An
+ * <p>Pass a qualified property key name as a two-part string, the namespace URI
+ * enclosed in curly braces ({}), followed by the local name. If the
+ * name has a null URL, the String only contain the local name. An
* application can safely check for a non-null URI by testing to see if the first
* character of the name is a '{' character.</p>
* <p>For example, if a URI and local name were obtained from an element
* defined with <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>,
- * then the TrAX QName would be "{http://xyz.foo.com/yada/baz.html}foo". Note that
+ * then the TrAX name would be "{http://xyz.foo.com/yada/baz.html}foo". Note that
* no prefix is used.</p>
*
* <p>If a given property is not supported, it will be silently ignored.</p>
*
* @param oformat A set of output properties that will be
* used to override any of the same properties in effect
- * for the transformation.
+ * for the transformation.
*
* @see javax.xml.transform.OutputKeys
* @see java.util.Properties
@@ -182,7 +177,7 @@
* setOutputProperties and setOutputProperty. Subsequent layers
* contain the properties set in the stylesheet and the
* default properties for the transformation type.
- * There is no guarantee on how the layers are structured passed the
+ * There is no guarantee on how the layers are ordered after the
* first layer. Thus, getOutputProperties().getProperty(String key) will obtain any
* property in effect for the stylesheet, while
* getOutputProperties().get(String key) will only retrieve properties
@@ -203,15 +198,14 @@
* Set an output property that will be in effect for the
* transformation.
*
- * <p>In order to pass namespaced names, the name can be passed as
* a two-part string, with
- * the first part being the URL, the delimiter being the '{' for the start of the
- * URI and '}' signifies the end, with the local name following. If the qname has
- * a null URL, then the String object will only contain the local name. An
+ * <p>Pass a qualified property name as a two-part string, the namespace URI
+ * enclosed in curly braces ({}), followed by the local name. If the
+ * name has a null URL, the String only contain the local name. An
* application can safely check for a non-null URI by testing to see if the first
* character of the name is a '{' character.</p>
* <p>For example, if a URI and local name were obtained from an element
* defined with <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>,
- * then the TrAX QName would be "{http://xyz.foo.com/yada/baz.html}foo". Note that
+ * then the TrAX name would be "{http://xyz.foo.com/yada/baz.html}foo". Note that
* no prefix is used.</p>
*
* @param name A non-null String that specifies an output
@@ -249,7 +243,7 @@
* Set the error event listener in effect for the transformation.
*
* @param listener The new error listener.
- * @throws IllegalArgumentException if
+ * @throws IllegalArgumentException if listener is null.
*/
public abstract void setErrorListener (ErrorListener listener)
throws IllegalArgumentException;
1.8 +45 -51 xml-xalan/java/src/javax/xml/transform/TransformerFactory.java
Index: TransformerFactory.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/TransformerFactory.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- TransformerFactory.java 2000/11/13 16:26:28 1.7
+++ TransformerFactory.java 2000/11/14 17:02:39 1.8
@@ -67,19 +67,18 @@
import java.util.Enumeration;
/**
- * A TransformerFactory instance creates Transformer and Template
+ * A TransformerFactory instance can be used to create Transformer and Template
* objects.
*
- * <p>The system property that controls which Factory implementation
+ * <p>The system property that determines which Factory implementation
* to create is named "javax.xml.transform.TransformerFactory". This
- * property names a class that is a concrete subclass of this
- * TransformerFactory abstract class. If no property is defined,
- * a platform default will be used.</p>
+ * property names a concrete subclass of the TransformerFactory abstract
+ * class. If the property is not defined, a platform default is be used.</p>
*/
public abstract class TransformerFactory
{
- /** The default property name according to the JAXP spec */
+ /** The default property name according to the JAXP spec. */
private static final String defaultPropName =
"javax.xml.transform.TransformerFactory";
@@ -91,14 +90,14 @@
/**
* Obtain a new instance of a <code>Transform Factory</code>.
* This static method creates a new factory instance based
- * on a system property setting or uses the platform default
- * if no property has been defined.<p>
+ * on a system property setting or (if this property is not defined)
+ * the platform default.<p>
*
- * The system property that controls which Factory implementation
- * to create is named "javax.xml.transform.TransformerFactory".
- * This property names a class that is a concrete subclass of this
- * abstract class. If no property is defined, a platform default
- * will be used.</p>
+ * The system property that determines which Factory implementation
+ * to create is named "javax.xml.transform.TransformerFactory".
+ * This property names a concrete subclass of the TransformerFactory
+ * abstract class. If hte property is not defined, a platform default
+ * is used.</p>
*
* Once an application has obtained a reference to a <code>
* TransformerFactory</code> it can use the factory to configure
@@ -147,17 +146,16 @@
}
/**
- * Process the source into a Transformer object. Care must
- * be given to know that this object can not be used concurrently
- * in multiple threads.
+ * Process the Source into a Transformer object. Care must
+ * be given not to use this object in multiple threads running concurrently.
*
- * @param source An object that holds a URL, input stream, etc.
+ * @param source An object that holds a URI, input stream, etc.
*
- * @return A Transformer object capable of
- * being used for transformation purposes in a single thread, never null.
+ * @return A Transformer object that may be used to perform a transformation
+ * in a single thread, never null.
*
- * @exception TransformerConfigurationException May throw this during the parse when it
- * is constructing the Templates object and fails.
+ * @exception TransformerConfigurationException May throw this during the parse
+ * when it is constructing the Templates object and fails.
*/
public abstract Transformer newTransformer(Source source)
throws TransformerConfigurationException;
@@ -166,20 +164,20 @@
* Create a new Transformer object that performs a copy
* of the source to the result.
*
- * @param source An object that holds a URL, input stream, etc.
+ * @param source An object that holds a URI, input stream, etc.
*
- * @return A Transformer object capable of
- * being used for transformation purposes in a single thread, never null.
+ * @return A Transformer object that may be used to perform a transformation
+ * in a single thread, never null.
*
* @exception TransformerConfigurationException May throw this during
* the parse when it is constructing the
- * Templates object and it fails.
+ * Templates object and fails.
*/
public abstract Transformer newTransformer()
throws TransformerConfigurationException;
/**
- * Process the source into a Templates object, which is likely
+ * Process the Source into a Templates object, which is a
* a compiled representation of the source. This Templates object
* may then be used concurrently across multiple threads. Creating
* a Templates object allows the TransformerFactory to do detailed
@@ -198,33 +196,31 @@
throws TransformerConfigurationException;
/**
- * Get InputSource specification(s) that are associated with the
- * given document specified in the source param,
- * via the xml-stylesheet processing instruction
- * (see http://www.w3.org/TR/xml-stylesheet/), and that matches
- * the given criteria. Note that it is possible to return several stylesheets
- * that match the criteria, in which case they are applied as if they were
+ * Get the stylesheet specification(s) associated
+ * via the xml-stylesheet processing instruction (see
+ * http://www.w3.org/TR/xml-stylesheet/) with the document
+ * document specified in the source parameter, and that match
+ * the given criteria. Note that it is possible to return several
+ * stylesheets, in which case they are applied as if they were
* a list of imports or cascades.
*
- * @param source
+ * @param source The XML source document.
* @param media The media attribute to be matched. May be null, in which
* case the prefered templates will be used (i.e. alternate = no).
* @param title The value of the title attribute to match. May be null.
* @param charset The value of the charset attribute to match. May be null.
- * @returns An array of InputSources that can be passed to processMultiple method.
*
* @return A Source object suitable for passing to the TransformerFactory.
*
- * @throws TransformerConfigurationException
+ * @throws TransformerConfigurationException.
*/
public abstract Source getAssociatedStylesheet(
Source source, String media, String title, String charset)
throws TransformerConfigurationException;
/**
- * Set an object that will be used to resolve URIs used in
- * xsl:import, etc. This will be used as the default for the
- * transformation.
+ * Set an object that is used by default during the transformation
+ * to resolve URIs used in document(), xsl:import, or xsl:include.
*
* @param resolver An object that implements the URIResolver interface,
* or null.
@@ -232,9 +228,8 @@
public abstract void setURIResolver(URIResolver resolver);
/**
- * Get the object that will be used to resolve URIs used in
- * xsl:import, etc. This will be used as the default for the
- * transformation.
+ * Get the object that is used by default during the transformation
+ * to resolve URIs used in document(), xsl:import, or xsl:include.
*
* @return The URIResolver that was set with setURIResolver.
*/
@@ -245,9 +240,8 @@
/**
* Look up the value of a feature.
*
- * <p>The feature name is any fully-qualified URI.</p>
- * @param name The feature name, which is a fully-qualified
- * URI.
+ * <p>The feature name is any absolute URI.</p>
+ * @param name The feature name, which is an absolute URI.
* @return The current state of the feature (true or false).
*/
public abstract boolean getFeature(String name);
@@ -277,8 +271,8 @@
throws IllegalArgumentException;
/**
- * Set the error event listener for the TransformerFactory. This
- * will be used for the processing of transformation instructions,
+ * Set the error event listener for the TransformerFactory, which
+ * is used for the processing of transformation instructions,
* and not for the transformation itself.
*
* @param listener The new error listener.
@@ -299,8 +293,8 @@
/**
* Avoid reading all the files when the findFactory
- * method is called the second time ( cache the result of
- * finding the default impl )
+ * method is called the second time (cache the result of
+ * finding the default impl).
*/
private static String foundFactory = null;
@@ -314,9 +308,9 @@
* Private implementation method - will find the implementation
* class in the specified order.
*
- * @param factoryId Name of the factory interface
- * @param xmlProperties Name of the properties file based on JAVA/lib
- * @param defaultFactory Default implementation, if nothing else is found
+ * @param factoryId Name of the factory interface.
+ * @param xmlProperties Name of the properties file based on JAVA/lib.
+ * @param defaultFactory Default implementation, if nothing else is found.
*
* @return The factory class name.
*/
1.3 +4 -4 xml-xalan/java/src/javax/xml/transform/URIResolver.java
Index: URIResolver.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/javax/xml/transform/URIResolver.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- URIResolver.java 2000/11/13 16:26:28 1.2
+++ URIResolver.java 2000/11/14 17:02:39 1.3
@@ -57,21 +57,21 @@
package javax.xml.transform;
/**
- * <p>An interface that can be called by the processor to for turning the
- * URIs used in document() and xsl:import etc into an Source object.
+ * <p>An object that implements this interface that can be called by the processor
+ * to turn a URI used in document(), xsl:import, or xsl:include into a Source object.
*/
public interface URIResolver
{
/**
- * This will be called by the processor when it encounters
+ * Called by the processor when it encounters
* an xsl:include, xsl:import, or document() function.
*
* @param href An href attribute, which may be relative or absolute.
* @param base The base URI in effect when the href attribute
* was encountered.
*
- * @return A Source object, or null if the href can not be resolved,
+ * @return A Source object, or null if the href cannot be resolved,
* and the processor should try to resolve the URI itself.
*
* @throws TransformerException if an error occurs when trying to