This is an automated email from the ASF dual-hosted git repository.
elharo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/xerces-j.git
The following commit(s) were added to refs/heads/main by this push:
new 8916da5b8 [XERCES-1781] part 1 (split out from #28) (#31)
8916da5b8 is described below
commit 8916da5b83f6ca25dbf632c247f4adbd7bb48265
Author: Samael <[email protected]>
AuthorDate: Mon Oct 20 12:06:37 2025 +0100
[XERCES-1781] part 1 (split out from #28) (#31)
---
build.xml | 4 +-
.../apache/xml/serialize/BaseMarkupSerializer.java | 129 ++++++++++++---------
src/org/apache/xml/serialize/DOMSerializer.java | 21 ++--
.../apache/xml/serialize/DOMSerializerImpl.java | 34 +++---
src/org/apache/xml/serialize/EncodingInfo.java | 21 +++-
src/org/apache/xml/serialize/Encodings.java | 2 +-
src/org/apache/xml/serialize/HTMLSerializer.java | 45 +++++--
src/org/apache/xml/serialize/HTMLdtd.java | 62 +++++-----
src/org/apache/xml/serialize/IndentPrinter.java | 2 +-
src/org/apache/xml/serialize/LineSeparator.java | 8 +-
src/org/apache/xml/serialize/ObjectFactory.java | 22 ++--
src/org/apache/xml/serialize/OutputFormat.java | 60 +++++-----
src/org/apache/xml/serialize/Printer.java | 25 +++-
src/org/apache/xml/serialize/Serializer.java | 26 ++++-
src/org/apache/xml/serialize/TextSerializer.java | 13 ++-
src/org/apache/xml/serialize/XHTMLSerializer.java | 12 +-
src/org/apache/xml/serialize/XML11Serializer.java | 20 ++--
src/org/apache/xml/serialize/XMLSerializer.java | 58 +++++----
18 files changed, 342 insertions(+), 222 deletions(-)
diff --git a/build.xml b/build.xml
index b14de4017..3804be69e 100644
--- a/build.xml
+++ b/build.xml
@@ -446,11 +446,11 @@ Authors:
<target name="javadoc-replace" unless="additional.param">
<replace token="@xerces.internal" dir="${build.src}">
- <replacevalue><![CDATA[<DL><DT><H1
style="font-size:110%">INTERNAL:</H1><DD>Usage of this class is not supported.
It may be altered or removed at any time.</DD></DT></DL>]]></replacevalue>
+ <replacevalue><![CDATA[<dl><dt><strong>INTERNAL:</strong></dt><dd>Usage
of this class is not supported. It may be altered or removed at any
time.</dd></dl>]]></replacevalue>
</replace>
<replace token="@xerces.experimental" dir="${build.src}">
- <replacevalue><![CDATA[<DL><DT><H1
style="font-size:150%">EXPERIMENTAL:</H1><DD>This class should not be
considered stable. It is likely to be altered or replaced in the
future.</DD></DT></DL>]]></replacevalue>
+
<replacevalue><![CDATA[<dl><dt><strong>EXPERIMENTAL:</strong></dt><dd>This
class should not be considered stable. It is likely to be altered or replaced
in the future.</dd></dl>]]></replacevalue>
</replace>
</target>
diff --git a/src/org/apache/xml/serialize/BaseMarkupSerializer.java
b/src/org/apache/xml/serialize/BaseMarkupSerializer.java
index 32527551c..715c78a6d 100644
--- a/src/org/apache/xml/serialize/BaseMarkupSerializer.java
+++ b/src/org/apache/xml/serialize/BaseMarkupSerializer.java
@@ -79,36 +79,43 @@ import org.xml.sax.ext.LexicalHandler;
* output format before it can be used by calling {@link #setOutputCharStream}
* or {@link #setOutputByteStream} for the writer and {@link #setOutputFormat}
* for the output format.
+ * </p>
* <p>
* The serializer can be reused any number of times, but cannot
* be used concurrently by two threads.
+ * </p>
* <p>
* If an output stream is used, the encoding is taken from the
- * output format (defaults to <tt>UTF-8</tt>). If a writer is
+ * output format (defaults to UTF-8). If a writer is
* used, make sure the writer uses the same encoding (if applies)
* as specified in the output format.
+ * </p>
* <p>
* The serializer supports both DOM and SAX. DOM serializing is done
* by calling {@link #serialize(Document)} and SAX serializing is done by
firing
* SAX events and using the serializer as a document handler.
* This also applies to derived class.
+ * </p>
* <p>
* If an I/O exception occurs while serializing, the serializer
* will not throw an exception directly, but only throw it
* at the end of serializing (either DOM or SAX's {@link
* org.xml.sax.DocumentHandler#endDocument}.
+ * </p>
* <p>
* For elements that are not specified as whitespace preserving,
* the serializer will potentially break long text lines at space
* boundaries, indent lines, and serialize elements on separate
* lines. Line terminators will be regarded as spaces, and
* spaces at beginning of line will be stripped.
+ * </p>
* <p>
* When indenting, the serializer is capable of detecting seemingly
* element content, and serializing these elements indented on separate
* lines. An element is serialized indented when it is the first or
* last child of an element, or immediate following or preceding
* another element.
+ * </p>
*
* @deprecated This class was deprecated in Xerces 2.9.0. It is recommended
* that new applications use the DOM Level 3 LSSerializer or JAXP's
Transformation
@@ -242,8 +249,9 @@ public abstract class BaseMarkupSerializer
/**
* Protected constructor can only be used by derived class.
* Must initialize the serializer before serializing any document,
- * by calling {@link #setOutputCharStream} or {@link #setOutputByteStream}
- * first
+ * by calling {@link #setOutputCharStream} or {@link #setOutputByteStream}
first
+ *
+ * @param format the output format associated with this serializer
*/
protected BaseMarkupSerializer( OutputFormat format )
{
@@ -394,11 +402,10 @@ public abstract class BaseMarkupSerializer
/**
* Serializes the DOM element using the previously specified
* writer and output format. Throws an exception only if
- * an I/O exception occured while serializing.
+ * an I/O exception occurred while serializing.
*
- * @param elem The element to serialize
- * @throws IOException An I/O exception occured while
- * serializing
+ * @param elem the element to serialize
+ * @throws IOException if an I/O exception occurs while serializing
*/
public void serialize( Element elem )
throws IOException
@@ -414,13 +421,12 @@ public abstract class BaseMarkupSerializer
/**
- * Serializes the DOM document fragmnt using the previously specified
+ * Serializes the DOM document fragment using the previously specified
* writer and output format. Throws an exception only if
- * an I/O exception occured while serializing.
+ * an I/O exception occurred while serializing.
*
- * @param frag The document fragment to serialize
- * @throws IOException An I/O exception occured while
- * serializing
+ * @param frag the document fragment to serialize
+ * @throws IOException if an I/O exception occurs while serializing
*/
public void serialize( DocumentFragment frag )
throws IOException
@@ -438,11 +444,10 @@ public abstract class BaseMarkupSerializer
/**
* Serializes the DOM document using the previously specified
* writer and output format. Throws an exception only if
- * an I/O exception occured while serializing.
+ * an I/O exception occurred while serializing.
*
- * @param doc The document to serialize
- * @throws IOException An I/O exception occured while
- * serializing
+ * @param doc the document to serialize
+ * @throws IOException if an I/O exception occurs while serializing
*/
public void serialize( Document doc )
throws IOException
@@ -741,10 +746,9 @@ public abstract class BaseMarkupSerializer
/**
* Called at the end of the document to wrap it up.
* Will flush the output stream and throw an exception
- * if any I/O error occured while serializing.
+ * if any I/O error occurs during serialization.
*
- * @throws SAXException An I/O exception occured during
- * serializing
+ * @throws SAXException if an I/O exception occurs while serializing
*/
public void endDocument()
throws SAXException
@@ -987,10 +991,9 @@ public abstract class BaseMarkupSerializer
* serializers and the differences are masked out in a separate {@link
* #serializeElement}.
*
- * @param node The node to serialize
+ * @param node the node to serialize
* @see #serializeElement
- * @throws IOException An I/O exception occured while
- * serializing
+ * @throws IOException if an I/O exception occurs while serializing
*/
protected void serializeNode( Node node )
throws IOException
@@ -1249,11 +1252,10 @@ public abstract class BaseMarkupSerializer
* Must be called by a method about to print any type of content.
* If the element was just opened, the opening tag is closed and
* will be matched to a closing tag. Returns the current element
- * state with <tt>empty</tt> and <tt>afterElement</tt> set to false.
+ * state with <code>empty</code> and <code>afterElement</code> set to
false.
*
- * @return The current element state
- * @throws IOException An I/O exception occurred while
- * serializing
+ * @return the current element state
+ * @throws IOException if an I/O exception occurs while serializing
*/
protected ElementState content()
throws IOException
@@ -1294,9 +1296,8 @@ public abstract class BaseMarkupSerializer
* current element state. In addition, the output format can dictate
* whether the text is printed as CDATA or unescaped.
*
- * @param text The text to print
- * @throws IOException An I/O exception occured while
- * serializing
+ * @param text the text to print
+ * @throws IOException an I/O exception occurred while serializing
*/
protected void characters( String text )
throws IOException
@@ -1343,22 +1344,21 @@ public abstract class BaseMarkupSerializer
/**
* Returns the suitable entity reference for this character value,
- * or null if no such entity exists. Calling this method with
<tt>'&'</tt>
- * will return <tt>"&amp;"</tt>.
+ * or null if no such entity exists. Calling this method with
<code>'&'</code>
+ * will return <code>"&amp;"</code>.
*
- * @param ch Character value
+ * @param ch character value
* @return Character entity name, or null
*/
protected abstract String getEntityRef( int ch );
/**
- * Called to serializee the DOM element. The element is serialized based on
+ * Called to serialize the DOM element. The element is serialized based on
* the serializer's method (XML, HTML, XHTML).
*
- * @param elem The element to serialize
- * @throws IOException An I/O exception occured while
- * serializing
+ * @param elem the element to serialize
+ * @throws IOException an I/O exception occurred while serializing
*/
protected abstract void serializeElement( Element elem )
throws IOException;
@@ -1372,8 +1372,7 @@ public abstract class BaseMarkupSerializer
* method. Will be called when the root element is serialized
* and when the document finished serializing.
*
- * @throws IOException An I/O exception occured while
- * serializing
+ * @throws IOException if an I/O error occurred while serializing
*/
protected void serializePreRoot()
throws IOException
@@ -1504,14 +1503,15 @@ public abstract class BaseMarkupSerializer
* {@link #printText(String,boolean,boolean)} with a call to {@link
Printer#breakLine}
* for each new line. If spaces are not preserved, the text is
* broken at space boundaries if longer than the line width;
- * Multiple spaces are printed as such, but spaces at beginning
- * of line are removed.
+ * Multiple spaces are printed as such, but spaces at the beginning
+ * of a line are removed.
*
- * @param chars The text to print
- * @param start The start offset
- * @param length The number of characters
- * @param preserveSpace Space preserving flag
- * @param unescaped Print unescaped
+ * @param chars the text to print
+ * @param start the start offset
+ * @param length the number of characters
+ * @param preserveSpace space preserving flag
+ * @param unescaped print unescaped
+ * @throws IOException if an I/O exception occurs while printing
*/
protected void printText( char[] chars, int start, int length,
boolean preserveSpace, boolean unescaped )
@@ -1555,7 +1555,14 @@ public abstract class BaseMarkupSerializer
}
}
-
+ /**
+ * Called to print additional text with whitespace handling.
+ *
+ * @param text the text to print
+ * @param preserveSpace space preserving flag
+ * @param unescaped print unescaped
+ * @throws IOException if an I/O exception occurs while printing
+ */
protected void printText( String text, boolean preserveSpace, boolean
unescaped )
throws IOException
{
@@ -1602,6 +1609,7 @@ public abstract class BaseMarkupSerializer
* characters and print it equivalent to {@link #printText}.
*
* @param url The document type url to print
+ * @throws IOException if an I/O exception occurs while printing
*/
protected void printDoctypeURL( String url )
throws IOException
@@ -1661,11 +1669,12 @@ public abstract class BaseMarkupSerializer
/**
* Escapes a string so it may be printed as text content or attribute
- * value. Non printable characters are escaped using character references.
- * Where the format specifies a deault entity reference, that reference
- * is used (e.g. <tt>&lt;</tt>).
+ * value. Non-printable characters are escaped using character references.
+ * Where the format specifies a default entity reference, that reference
+ * is used (e.g. <code>&lt;</code>).
*
* @param source The string to escape
+ * @throws IOException if an I/O exception occurs while printing
*/
protected void printEscaped( String source )
throws IOException
@@ -1705,7 +1714,11 @@ public abstract class BaseMarkupSerializer
* Tag name and space preserving is specified, element
* state is initially empty.
*
- * @return Current element state, or null
+ * @param namespaceURI the namespace URI of the <code>ElementState</code>
+ * @param localName the local name of the <code>ElementState</code>
+ * @param rawName the raw name of the <code>ElementState</code>
+ * @param preserveSpace space preserving flag
+ * @return the current element state, or <code>null</code>
*/
protected ElementState enterElementState( String namespaceURI, String
localName,
String rawName, boolean
preserveSpace )
@@ -1786,7 +1799,7 @@ public abstract class BaseMarkupSerializer
* prefix, otherwise returns null.
*
* @param namespaceURI The namespace URI
- * @return The namespace prefix if known, or null
+ * @return The namespace prefix if known, or <code>null</code>
*/
protected String getPrefix( String namespaceURI )
{
@@ -1811,12 +1824,13 @@ public abstract class BaseMarkupSerializer
}
/**
- * The method modifies global DOM error object
+ * The method modifies global DOM error object.
*
- * @param message
- * @param severity
- * @param type
- * @return a DOMError
+ * @param message string describing the error that occurred
+ * @param severity the severity of the error, either {@link
DOMError#SEVERITY_WARNING}, {@link DOMError#SEVERITY_ERROR}, or {@link
DOMError#SEVERITY_FATAL_ERROR}
+ * @param type a string representing the error type or <code>null</code>
if not required
+ * @param node the node to use as related data in the {@link
DOMLocatorImpl}
+ * @return the serializer's DOMError with the new values assigned
*/
protected DOMError modifyDOMError(String message, short severity, String
type, Node node){
fDOMError.reset();
@@ -1843,7 +1857,8 @@ public abstract class BaseMarkupSerializer
* DOM level 3:
* Check a node to determine if it contains unbound namespace prefixes.
*
- * @param node The node to check for unbound namespace prefices
+ * @param node the node to check for unbound namespace prefixes
+ * @throws IOException thrown on i/o error
*/
protected void checkUnboundNamespacePrefixedNode (Node node) throws
IOException{
diff --git a/src/org/apache/xml/serialize/DOMSerializer.java
b/src/org/apache/xml/serialize/DOMSerializer.java
index 343fba0ed..4ff75ab68 100644
--- a/src/org/apache/xml/serialize/DOMSerializer.java
+++ b/src/org/apache/xml/serialize/DOMSerializer.java
@@ -45,11 +45,10 @@ public interface DOMSerializer
/**
* Serialized the DOM element. Throws an exception only if
- * an I/O exception occured while serializing.
+ * an I/O exception occurred while serializing.
*
- * @param elem The element to serialize
- * @throws IOException An I/O exception occured while
- * serializing
+ * @param elem the element to serialize
+ * @throws IOException an I/O exception occurred while serializing
*/
public void serialize( Element elem )
throws IOException;
@@ -57,11 +56,10 @@ public interface DOMSerializer
/**
* Serializes the DOM document. Throws an exception only if
- * an I/O exception occured while serializing.
+ * an I/O exception occurred while serializing.
*
- * @param doc The document to serialize
- * @throws IOException An I/O exception occured while
- * serializing
+ * @param doc the document to serialize
+ * @throws IOException an I/O exception occurred while serializing
*/
public void serialize( Document doc )
throws IOException;
@@ -69,11 +67,10 @@ public interface DOMSerializer
/**
* Serializes the DOM document fragment. Throws an exception
- * only if an I/O exception occured while serializing.
+ * only if an I/O exception occurred while serializing.
*
- * @param frag The document fragment to serialize
- * @throws IOException An I/O exception occured while
- * serializing
+ * @param frag the document fragment to serialize
+ * @throws IOException an I/O exception occurred while serializing
*/
public void serialize( DocumentFragment frag )
throws IOException;
diff --git a/src/org/apache/xml/serialize/DOMSerializerImpl.java
b/src/org/apache/xml/serialize/DOMSerializerImpl.java
index 7b37d02c5..52fa1f7de 100644
--- a/src/org/apache/xml/serialize/DOMSerializerImpl.java
+++ b/src/org/apache/xml/serialize/DOMSerializerImpl.java
@@ -58,7 +58,7 @@ import org.w3c.dom.ls.LSSerializerFilter;
/**
* EXPERIMENTAL: Implemenatation of DOM Level 3 org.w3c.ls.LSSerializer by
delegating serialization
- * calls to <CODE>XMLSerializer</CODE>.
+ * calls to <code>XMLSerializer</code>.
* LSSerializer provides an API for serializing (writing) a DOM document out
in an
* XML document. The XML data is written to an output stream.
* During serialization of XML data, namespace fixup is done when possible as
@@ -448,16 +448,17 @@ public class DOMSerializerImpl implements LSSerializer,
DOMConfiguration {
* Serialize the specified node as described above in the description of
* <code>LSSerializer</code>. The result of serializing the node is
* returned as a string. Writing a Document or Entity node produces a
- * serialized form that is well formed XML. Writing other node types
+ * serialized form that is well-formed XML. Writing other node types
* produces a fragment of text in a form that is not fully defined by
* this document, but that should be useful to a human for debugging or
* diagnostic purposes.
- * @param wnode The node to be written.
- * @return Returns the serialized data
- * @exception DOMException
+ *
+ * @param wnode the node to be written
+ * @return returns the serialized data
+ * @throws DOMException
* DOMSTRING_SIZE_ERR: The resulting string is too long to fit in a
* <code>DOMString</code>.
- * @exception LSException
+ * @throws LSException
* SERIALIZE_ERR: Unable to serialize the node. DOM applications should
* attach a <code>DOMErrorHandler</code> using the parameter
* "<i>error-handler</i>" to get details on error.
@@ -652,11 +653,12 @@ public class DOMSerializerImpl implements LSSerializer,
DOMConfiguration {
* "unsupported-encoding" error is raised.
* <br> If no output is specified in the <code>LSOutput</code>, a
* "no-output-specified" error is raised.
- * @param node The node to serialize.
- * @param destination The destination for the serialized DOM.
- * @return Returns <code>true</code> if <code>node</code> was
- * successfully serialized and <code>false</code> in case the node
- * couldn't be serialized.
+ *
+ * @param node the node to serialize
+ * @param destination the destination for the serialized DOM
+ * @return <code>true</code> if <code>node</code> was successfully
serialized
+ * and <code>false</code> in case the node couldn't be serialized
+ * @throws LSException SERIALIZE_ERR: if unable to serialize the node
*/
public boolean write(Node node, LSOutput destination) throws LSException{
@@ -796,11 +798,11 @@ public class DOMSerializerImpl implements LSSerializer,
DOMConfiguration {
* default encoding of "UTF-8" will be used.
* <br> If the specified encoding is not supported an
* "unsupported-encoding" error is raised.
- * @param node The node to serialize.
- * @param URI The URI to write to.
- * @return Returns <code>true</code> if <code>node</code> was
- * successfully serialized and <code>false</code> in case the node
- * couldn't be serialized.
+ * @param node the node to serialize
+ * @param URI the URI to write to
+ * @return <code>true</code> if <code>node</code> was successfully
serialized
+ * and <code>false</code> in case the node couldn't be serialized
+ * @throws LSException SERIALIZE_ERR: if unable to serialize the node
*/
public boolean writeToURI(Node node, String URI) throws LSException{
if (node == null){
diff --git a/src/org/apache/xml/serialize/EncodingInfo.java
b/src/org/apache/xml/serialize/EncodingInfo.java
index b493b73d5..f2ecca400 100644
--- a/src/org/apache/xml/serialize/EncodingInfo.java
+++ b/src/org/apache/xml/serialize/EncodingInfo.java
@@ -61,6 +61,10 @@ public class EncodingInfo {
/**
* Creates new <code>EncodingInfo</code> instance.
+ *
+ * @param ianaName name of encoding as registered with IANA (preferably a
MIME name, but aliases are fine too)
+ * @param javaName not actually used
+ * @param lastPrintable the integer value of the last printable char in
the character encoding
*/
public EncodingInfo(String ianaName, String javaName, int lastPrintable) {
this.ianaName = ianaName;
@@ -70,6 +74,7 @@ public class EncodingInfo {
/**
* Returns a MIME charset name of this encoding.
+ * @return a string value of the MIME charset name for this encoding
*/
public String getIANAName() {
return this.ianaName;
@@ -79,9 +84,9 @@ public class EncodingInfo {
* Returns a writer for this encoding based on
* an output stream.
*
- * @return A suitable writer
- * @exception UnsupportedEncodingException There is no convertor
- * to support this encoding
+ * @param output the output stream to use
+ * @return a suitable writer
+ * @throws UnsupportedEncodingException if there is no convertor to
support this encoding
*/
public Writer getWriter(OutputStream output)
throws UnsupportedEncodingException {
@@ -99,6 +104,7 @@ public class EncodingInfo {
* Checks whether the specified character is printable or not in this
encoding.
*
* @param ch a code point (0-0x10ffff)
+ * @return true if the char is printable with this encoding
*/
public boolean isPrintable(char ch) {
if (ch <= this.lastPrintable) {
@@ -113,6 +119,7 @@ public class EncodingInfo {
* available it will attempt use a sun.io.CharToByteConverter.
*
* @param ch a code point (0-0x10ffff)
+ * @return true if the char is printable with this encoding
*/
private boolean isPrintable0(char ch) {
@@ -186,8 +193,12 @@ public class EncodingInfo {
}
}
- // is this an encoding name recognized by this JDK?
- // if not, will throw UnsupportedEncodingException
+ /**
+ * Checks that a charset is recognized by this JDK.
+ *
+ * @param name the charset name
+ * @throws UnsupportedEncodingException if the charset name is not
recognized by the JDK
+ */
public static void testJavaEncodingName(String name) throws
UnsupportedEncodingException {
final byte [] bTest = {(byte)'v', (byte)'a', (byte)'l', (byte)'i',
(byte)'d'};
String s = new String(bTest, name);
diff --git a/src/org/apache/xml/serialize/Encodings.java
b/src/org/apache/xml/serialize/Encodings.java
index f8e9e96e9..e62944369 100644
--- a/src/org/apache/xml/serialize/Encodings.java
+++ b/src/org/apache/xml/serialize/Encodings.java
@@ -61,7 +61,7 @@ public class Encodings
static Hashtable _encodings = new Hashtable();
/**
- * @param encoding a MIME charset name, or null.
+ * @param encoding a MIME charset name, or null
*/
static EncodingInfo getEncodingInfo(String encoding, boolean
allowJavaNames) throws UnsupportedEncodingException {
EncodingInfo eInfo = null;
diff --git a/src/org/apache/xml/serialize/HTMLSerializer.java
b/src/org/apache/xml/serialize/HTMLSerializer.java
index d61d49881..9be82178d 100755
--- a/src/org/apache/xml/serialize/HTMLSerializer.java
+++ b/src/org/apache/xml/serialize/HTMLSerializer.java
@@ -56,26 +56,31 @@ import org.xml.sax.SAXException;
* constructor. For usage instructions see {@link Serializer}.
* <p>
* If an output stream is used, the encoding is taken from the
- * output format (defaults to <tt>UTF-8</tt>). If a writer is
+ * output format (defaults to UTF-8). If a writer is
* used, make sure the writer uses the same encoding (if applies)
* as specified in the output format.
+ * </p>
* <p>
* The serializer supports both DOM and SAX. DOM serializing is done
* by calling {@link #serialize} and SAX serializing is done by firing
* SAX events and using the serializer as a document handler.
+ * </p>
* <p>
* If an I/O exception occurs while serializing, the serializer
* will not throw an exception directly, but only throw it
* at the end of serializing (either DOM or SAX's {@link
* org.xml.sax.DocumentHandler#endDocument}.
+ * </p>
* <p>
* For elements that are not specified as whitespace preserving,
* the serializer will potentially break long text lines at space
* boundaries, indent lines, and serialize elements on separate
* lines. Line terminators will be regarded as spaces, and
* spaces at beginning of line will be stripped.
+ * </p>
* <p>
* XHTML is slightly different than HTML:
+ * </p>
* <ul>
* <li>Element/attribute names are lower case and case matters
* <li>Attributes must specify value, even if empty string
@@ -103,6 +108,9 @@ public class HTMLSerializer
private boolean _xhtml;
+ /**
+ * The XHTML namespace URI
+ */
public static final String XHTMLNamespace = "http://www.w3.org/1999/xhtml";;
// for users to override XHTMLNamespace if need be.
@@ -111,10 +119,11 @@ public class HTMLSerializer
/**
* Constructs a new HTML/XHTML serializer depending on the value of
- * <tt>xhtml</tt>. The serializer cannot be used without calling
+ * <code>xhtml</code>. The serializer cannot be used without calling
* {@link #setOutputCharStream} or {@link #setOutputByteStream} first.
*
- * @param xhtml True if XHTML serializing
+ * @param xhtml true if XHTML serializing
+ * @param format the output format to use
*/
protected HTMLSerializer( boolean xhtml, OutputFormat format )
{
@@ -138,6 +147,8 @@ public class HTMLSerializer
* Constructs a new serializer. The serializer cannot be used without
* calling {@link #setOutputCharStream} or {@link #setOutputByteStream}
* first.
+ *
+ * @param format the output format to use, null for the default
*/
public HTMLSerializer( OutputFormat format )
{
@@ -148,11 +159,11 @@ public class HTMLSerializer
/**
* Constructs a new serializer that writes to the specified writer
- * using the specified output format. If <tt>format</tt> is null,
+ * using the specified output format. If <code>format</code> is null,
* will use a default output format.
*
- * @param writer The writer to use
- * @param format The output format to use, null for the default
+ * @param writer the writer to use
+ * @param format the output format to use, null for the default
*/
public HTMLSerializer( Writer writer, OutputFormat format )
{
@@ -163,11 +174,11 @@ public class HTMLSerializer
/**
* Constructs a new serializer that writes to the specified output
- * stream using the specified output format. If <tt>format</tt>
+ * stream using the specified output format. If <code>format</code>
* is null, will use a default output format.
*
- * @param output The output stream to use
- * @param format The output format to use, null for the default
+ * @param output the output stream to use
+ * @param format the output format to use, null for the default
*/
public HTMLSerializer( OutputStream output, OutputFormat format )
{
@@ -176,6 +187,11 @@ public class HTMLSerializer
}
+ /**
+ * Sets the output format for this serializer.
+ *
+ * @param format the output format to use, null for the default
+ */
public void setOutputFormat( OutputFormat format )
{
super.setOutputFormat( format != null ? format : new OutputFormat(
Method.HTML, "ISO-8859-1", false ) );
@@ -623,6 +639,10 @@ public class HTMLSerializer
* pre-root comments and PIs that were accumulated in the document
* (see {@link #serializePreRoot}). Pre-root will be serialized even if
* this is not the first root element of the document.
+ * </p>
+ *
+ * @param rootTagName unused variable
+ * @throws IOException if an I/O exception occurs while serializing
*/
protected void startDocument( String rootTagName )
throws IOException
@@ -684,7 +704,7 @@ public class HTMLSerializer
}
_started = true;
- // Always serialize these, even if not te first root element.
+ // Always serialize these, even if not the first root element.
serializePreRoot();
}
@@ -692,7 +712,10 @@ public class HTMLSerializer
/**
* Called to serialize a DOM element. Equivalent to calling {@link
* #startElement}, {@link #endElement} and serializing everything
- * inbetween, but better optimized.
+ * in between, but better optimized.
+ *
+ * @param elem the element to serialize
+ * @throws IOException an I/O exception occurred while serializing
*/
protected void serializeElement( Element elem )
throws IOException
diff --git a/src/org/apache/xml/serialize/HTMLdtd.java
b/src/org/apache/xml/serialize/HTMLdtd.java
index f3fd914d6..78143db65 100755
--- a/src/org/apache/xml/serialize/HTMLdtd.java
+++ b/src/org/apache/xml/serialize/HTMLdtd.java
@@ -34,10 +34,11 @@ import org.apache.xerces.dom.DOMMessageFormatter;
* The HTML DTD is expressed as three utility function groups. Two methods
* allow for checking whether an element requires an open tag on printing
* ({@link #isEmptyTag}) or on parsing ({@link #isOptionalClosing}).
- * <P>
+ * <p>
* Two other methods translate character references from name to value and
* from value to name. A small entities resource is loaded into memory the
* first time any of these methods is called for fast and efficient access.
+ * </p>
*
* @deprecated This class was deprecated in Xerces 2.9.0. It is recommended
* that new applications use JAXP's Transformation API for XML (TrAX) for
@@ -81,7 +82,7 @@ public final class HTMLdtd
/**
* Table of entity name to value mapping. Entities are held as strings,
- * character references as <TT>Character</TT> objects.
+ * character references as <code>Character</code> objects.
*/
private static Hashtable _byName;
@@ -171,8 +172,8 @@ public final class HTMLdtd
* Returns true if element is declared to be empty. HTML elements are
* defines as empty in the DTD, not by the document syntax.
*
- * @param tagName The element tag name (upper case)
- * @return True if element is empty
+ * @param tagName the element tag name (upper case)
+ * @return true if element is empty
*/
public static boolean isEmptyTag( String tagName )
{
@@ -185,8 +186,8 @@ public final class HTMLdtd
* Whitespaces appearing inside element content will be ignored,
* other text will simply report an error.
*
- * @param tagName The element tag name (upper case)
- * @return True if element content
+ * @param tagName the element tag name (upper case)
+ * @return true if element content
*/
public static boolean isElementContent( String tagName )
{
@@ -199,8 +200,8 @@ public final class HTMLdtd
* This only applies to PRE and TEXTAREA, all other HTML elements
* do not preserve space.
*
- * @param tagName The element tag name (upper case)
- * @return True if element's text content preserves spaces
+ * @param tagName the element tag name (upper case)
+ * @return true if element's text content preserves spaces
*/
public static boolean isPreserveSpace( String tagName )
{
@@ -211,10 +212,10 @@ public final class HTMLdtd
/**
* Returns true if element's closing tag is optional and need not
* exist. An error will not be reported for such elements if they
- * are not closed. For example, <tt>LI</tt> is most often not closed.
+ * are not closed. For example, <code>LI</code> is most often not closed.
*
- * @param tagName The element tag name (upper case)
- * @return True if closing tag implied
+ * @param tagName the element tag name (upper case)
+ * @return true if closing tag implied
*/
public static boolean isOptionalClosing( String tagName )
{
@@ -224,10 +225,10 @@ public final class HTMLdtd
/**
* Returns true if element's closing tag is generally not printed.
- * For example, <tt>LI</tt> should not print the closing tag.
+ * For example, <code>LI</code> should not print the closing tag.
*
- * @param tagName The element tag name (upper case)
- * @return True if only opening tag should be printed
+ * @param tagName the element tag name (upper case)
+ * @return true if only opening tag should be printed
*/
public static boolean isOnlyOpening( String tagName )
{
@@ -236,14 +237,14 @@ public final class HTMLdtd
/**
- * Returns true if the opening of one element (<tt>tagName</tt>) implies
- * the closing of another open element (<tt>openTag</tt>). For example,
- * every opening <tt>LI</tt> will close the previously open <tt>LI</tt>,
- * and every opening <tt>BODY</tt> will close the previously open
<tt>HEAD</tt>.
+ * Returns true if the opening of one element (<code>tagName</code>)
implies
+ * the closing of another open element (<code>openTag</code>). For example,
+ * every opening <code>LI</code> will close the previously open
<code>LI</code>,
+ * and every opening <code>BODY</code> will close the previously open
<code>HEAD</code>.
*
- * @param tagName The newly opened element
- * @param openTag The already opened element
- * @return True if closing tag closes opening tag
+ * @param tagName the newly opened element
+ * @param openTag the already opened element
+ * @return true if closing tag closes opening tag
*/
public static boolean isClosing( String tagName, String openTag )
{
@@ -276,8 +277,8 @@ public final class HTMLdtd
* escaped appropriately. In HTML URIs are escaped differently
* than normal attributes.
*
- * @param tagName The element's tag name
- * @param attrName The attribute's name
+ * @param tagName the element's tag name
+ * @param attrName the attribute's name
*/
public static boolean isURI( String tagName, String attrName )
{
@@ -291,8 +292,8 @@ public final class HTMLdtd
* printed without the value. This applies to attributes that are true
* if they exist, such as selected (OPTION/INPUT).
*
- * @param tagName The element's tag name
- * @param attrName The attribute's name
+ * @param tagName the element's tag name
+ * @param attrName the attribute's name
*/
public static boolean isBoolean( String tagName, String attrName )
{
@@ -313,8 +314,8 @@ public final class HTMLdtd
* reference is not found or was not defined as a character reference,
* returns EOF (-1).
*
- * @param name Name of character reference
- * @return Character code or EOF (-1)
+ * @param name name of character reference
+ * @return a character code or EOF (-1)
*/
public static int charFromName( String name )
{
@@ -420,14 +421,15 @@ public final class HTMLdtd
/**
* Defines a new character reference. The reference's name and value are
* supplied. Nothing happens if the character reference is already defined.
- * <P>
+ * <p>
* Unlike internal entities, character references are a string to single
* character mapping. They are used to map non-ASCII characters both on
* parsing and printing, primarily for HTML documents. '<amp;' is an
* example of a character reference.
+ * </p>
*
- * @param name The entity's name
- * @param value The entity's value
+ * @param name the entity's name
+ * @param value the entity's value
*/
private static void defineEntity( String name, char value )
{
diff --git a/src/org/apache/xml/serialize/IndentPrinter.java
b/src/org/apache/xml/serialize/IndentPrinter.java
index 93a4bfa4a..37a0ce15e 100644
--- a/src/org/apache/xml/serialize/IndentPrinter.java
+++ b/src/org/apache/xml/serialize/IndentPrinter.java
@@ -138,7 +138,7 @@ public class IndentPrinter
* added to the accumulate line. When a line is long enough, it can
* be broken at its text boundary.
*
- * @param text The text to print
+ * @param text the text to print
*/
public void printText( String text )
{
diff --git a/src/org/apache/xml/serialize/LineSeparator.java
b/src/org/apache/xml/serialize/LineSeparator.java
index e629bd000..38713126f 100644
--- a/src/org/apache/xml/serialize/LineSeparator.java
+++ b/src/org/apache/xml/serialize/LineSeparator.java
@@ -34,25 +34,25 @@ public final class LineSeparator
/**
- * Line separator for Unix systems (<tt>\n</tt>).
+ * Line separator for Unix systems (<code>\n</code>).
*/
public static final String Unix = "\n";
/**
- * Line separator for Windows systems (<tt>\r\n</tt>).
+ * Line separator for Windows systems (<code>\r\n</code>).
*/
public static final String Windows = "\r\n";
/**
- * Line separator for Macintosh systems (<tt>\r</tt>).
+ * Line separator for Macintosh systems (<code>\r</code>).
*/
public static final String Macintosh = "\r";
/**
- * Line separator for the Web (<tt>\n</tt>).
+ * Line separator for the Web (<code>\n</code>).
*/
public static final String Web = "\n";
diff --git a/src/org/apache/xml/serialize/ObjectFactory.java
b/src/org/apache/xml/serialize/ObjectFactory.java
index 1373231b0..ad52e2f1d 100644
--- a/src/org/apache/xml/serialize/ObjectFactory.java
+++ b/src/org/apache/xml/serialize/ObjectFactory.java
@@ -35,7 +35,7 @@ import java.util.Properties;
* later, and to compile on JDK 1.2 and onward.
* The code also runs both as part of an unbundled jar file and
* when bundled as part of the JDK.
- * <p>
+ * </p>
*
* @version $Id$
*/
@@ -85,12 +85,12 @@ final class ObjectFactory {
*
* @return Class object of factory, never null
*
- * @param factoryId Name of the factory to find, same as
+ * @param factoryId the name of the factory to find, same as
* a property name
- * @param fallbackClassName Implementation class name, if nothing else
- * is found. Use null to mean no fallback.
+ * @param fallbackClassName an implementation class name, if nothing
else
+ * is found. Use <code>null</code> to mean no
fallback.
*
- * @exception ObjectFactory.ConfigurationError
+ * @throws ObjectFactory.ConfigurationError will be thrown if cannot
create an instance
*/
static Object createObject(String factoryId, String fallbackClassName)
throws ConfigurationError {
@@ -109,15 +109,15 @@ final class ObjectFactory {
*
* @return Class object of factory, never null
*
- * @param factoryId Name of the factory to find, same as
+ * @param factoryId the name of the factory to find, same as
* a property name
- * @param propertiesFilename The filename in the $java.home/lib directory
+ * @param propertiesFilename the filename in the $java.home/lib directory
* of the properties file. If none specified,
- * ${java.home}/lib/xerces.properties will be
used.
- * @param fallbackClassName Implementation class name, if nothing else
- * is found. Use null to mean no fallback.
+ * ${java.home}/lib/xerces.properties will be
used
+ * @param fallbackClassName an implementation class name, if nothing
else
+ * is found. Use <code>null</code> to mean no
fallback.
*
- * @exception ObjectFactory.ConfigurationError
+ * @throws ObjectFactory.ConfigurationError will be thrown if cannot
create an instance
*/
static Object createObject(String factoryId,
String propertiesFilename,
diff --git a/src/org/apache/xml/serialize/OutputFormat.java
b/src/org/apache/xml/serialize/OutputFormat.java
index 21ac304da..e412ae987 100644
--- a/src/org/apache/xml/serialize/OutputFormat.java
+++ b/src/org/apache/xml/serialize/OutputFormat.java
@@ -42,6 +42,7 @@ import org.w3c.dom.html.HTMLDocument;
* document should be formatted on output.
* <p>
* The two interesting constructors are:
+ * </p>
* <ul>
* <li>{@link #OutputFormat(String,String,boolean)} creates a format
* for the specified method (XML, HTML, Text, etc), encoding and indentation
@@ -127,7 +128,7 @@ public class OutputFormat
/**
* The default line width at which to break long lines
- * when identing. This is set to 72.
+ * when indenting. This is set to 72.
*/
public static final int LineWidth = 72;
@@ -136,7 +137,7 @@ public class OutputFormat
/**
* Holds the output method specified for this document,
- * or null if no method was specified.
+ * or <code>null</code> if no method was specified.
*/
private String _method;
@@ -257,13 +258,13 @@ public class OutputFormat
/**
* Constructs a new output format with the default values for
- * the specified method and encoding. If <tt>indent</tt>
+ * the specified method and encoding. If <code>indent</code>
* is true, the document will be pretty printed with the default
* indentation level and default line wrapping.
*
- * @param method The specified output method
- * @param encoding The specified encoding
- * @param indenting True for pretty printing
+ * @param method the specified output method
+ * @param encoding the specified encoding
+ * @param indenting true for pretty printing
* @see #setEncoding
* @see #setIndenting
* @see #setMethod
@@ -281,7 +282,7 @@ public class OutputFormat
* document type identifiers and media type for the specified
* document.
*
- * @param doc The document to output
+ * @param doc the document to output
* @see #whichMethod
*/
public OutputFormat( Document doc )
@@ -295,13 +296,13 @@ public class OutputFormat
/**
* Constructs a new output format with the proper method,
* document type identifiers and media type for the specified
- * document, and with the specified encoding. If <tt>indent</tt>
+ * document, and with the specified encoding. If <code>indent</code>
* is true, the document will be pretty printed with the default
* indentation level and default line wrapping.
*
- * @param doc The document to output
- * @param encoding The specified encoding
- * @param indenting True for pretty printing
+ * @param doc the document to output
+ * @param encoding the specified encoding
+ * @param indenting true for pretty printing
* @see #setEncoding
* @see #setIndenting
* @see #whichMethod
@@ -316,8 +317,8 @@ public class OutputFormat
/**
* Returns the method specified for this output format.
- * Typically the method will be <tt>xml</tt>, <tt>html</tt>
- * or <tt>text</tt>, but it might be other values.
+ * Typically the method will be <code>xml</code>, <code>html</code>
+ * or <code>text</code>, but it might be other values.
* If no method was specified, null will be returned
* and the most suitable method will be determined for
* the document by calling {@link #whichMethod}.
@@ -334,7 +335,7 @@ public class OutputFormat
* Sets the method for this output format.
*
* @see #getMethod
- * @param method The output method, or null
+ * @param method the output method, or null
*/
public void setMethod( String method )
{
@@ -363,7 +364,7 @@ public class OutputFormat
* it would be "4.0".
*
* @see #getVersion
- * @param version The output method version, or null
+ * @param version the output method version, or null
*/
public void setVersion( String version )
{
@@ -400,7 +401,7 @@ public class OutputFormat
* Calling {@link #setIndenting} will reset this
* value to zero (off) or the default (on).
*
- * @param indent The indentation, or zero
+ * @param indent the indentation, or zero
*/
public void setIndent( int indent )
{
@@ -418,7 +419,7 @@ public class OutputFormat
* To specify a different indentation level or line wrapping,
* use {@link #setIndent} and {@link #setLineWidth}.
*
- * @param on True if indentation should be on
+ * @param on set to true for indentation to be used
*/
public void setIndenting( boolean on )
{
@@ -451,7 +452,7 @@ public class OutputFormat
* used by the {@link java.io.Writer}.
*
* @see #getEncoding
- * @param encoding The encoding, or null
+ * @param encoding the encoding, or <code>null</code>
*/
public void setEncoding( String encoding )
{
@@ -460,8 +461,11 @@ public class OutputFormat
}
/**
- * Sets the encoding for this output method with an
<code>EncodingInfo</code>
- * instance.
+ * Sets the encoding for this output method with an
<code>EncodingInfo</code> instance.
+ * Note that <code>EncodingInfo</code> is now deprecated. Use the setter
that takes a string value.
+ *
+ * @see #setEncoding(String)
+ * @param encInfo an <code>EncodingInfo</code> instance for this output
method
*/
public void setEncoding(EncodingInfo encInfo) {
_encoding = encInfo.getIANAName();
@@ -471,7 +475,9 @@ public class OutputFormat
/**
* Returns an <code>EncodingInfo</code> instance for the encoding.
*
- * @see #setEncoding
+ * @see #setEncoding(EncodingInfo)
+ * @return the encoding as an <code>EncodingInfo</code> instance
+ * @throws UnsupportedEncodingException if the specified encoding is not
supported
*/
public EncodingInfo getEncodingInfo() throws UnsupportedEncodingException {
if (_encodingInfo == null)
@@ -510,7 +516,7 @@ public class OutputFormat
* Sets the media type.
*
* @see #getMediaType
- * @param mediaType The specified media type
+ * @param mediaType the specified media type
*/
public void setMediaType( String mediaType )
{
@@ -732,7 +738,7 @@ public class OutputFormat
/**
* Returns a specific line separator to use. The default is the
- * Web line separator (<tt>\n</tt>). A string is returned to
+ * Web line separator (<code>\n</code>). A string is returned to
* support double codes (CR + LF).
*
* @return The specified line separator
@@ -745,8 +751,8 @@ public class OutputFormat
/**
* Sets the line separator. The default is the Web line separator
- * (<tt>\n</tt>). The machine's line separator can be obtained
- * from the system property <tt>line.separator</tt>, but is only
+ * (<code>\n</code>). The machine's line separator can be obtained
+ * from the system property <code>line.separator</code>, but is only
* useful if the document is edited on machines of the same type.
* For general documents, use the Web line separator.
*
@@ -845,10 +851,10 @@ public class OutputFormat
/**
* Determine the output method for the specified document.
* If the document is an instance of {@link org.w3c.dom.html.HTMLDocument}
- * then the method is said to be <tt>html</tt>. If the root
+ * then the method is said to be <code>html</code>. If the root
* element is 'html' and all text nodes preceding the root
* element are all whitespace, then the method is said to be
- * <tt>html</tt>. Otherwise the method is <tt>xml</tt>.
+ * <code>html</code>. Otherwise, the method is <code>xml</code>.
*
* @param doc The document to check
* @return The suitable method
diff --git a/src/org/apache/xml/serialize/Printer.java
b/src/org/apache/xml/serialize/Printer.java
index 7af4da81d..f53857683 100644
--- a/src/org/apache/xml/serialize/Printer.java
+++ b/src/org/apache/xml/serialize/Printer.java
@@ -128,6 +128,8 @@ public class Printer
* This method may be called any number of time but will only
* have affect the first time it's called. To exist DTD state
* and get the accumulated DTD, call {@link #leaveDTD}.
+ *
+ * @throws IOException can be thrown by underlying call to {@link
Printer#flushLine(boolean)}
*/
public void enterDTD()
throws IOException
@@ -148,6 +150,9 @@ public class Printer
* Called by the root element to leave DTD mode and if any
* DTD parts were printer, will return a string with their
* textual content.
+ *
+ * @return a string of DTD content or <code>null</code>
+ * @throws IOException can be thrown by underlying call to {@link
Printer#flushLine(boolean)}
*/
public String leaveDTD()
throws IOException
@@ -162,7 +167,16 @@ public class Printer
return null;
}
-
+ /**
+ * Called to print additional text. Each time this method is called
+ * it accumulates more text. When a space is printed ({@link #printSpace})
+ * all the accumulated text becomes one part and is added to the
+ * accumulate line. When a line is long enough, it can be broken at
+ * its text boundary.
+ *
+ * @param text the value to write to the buffer
+ * @throws IOException can be thrown by underlying call to {@link
Writer#write(char[])}
+ */
public void printText( String text )
throws IOException
{
@@ -185,7 +199,12 @@ public class Printer
}
}
-
+ /**
+ * Same as {@link #printText(String)} but this method takes a {@link
StringBuffer}.
+ *
+ * @param text the value to write to the buffer
+ * @throws IOException can be thrown by underlying call to {@link
Writer#write(char[])}
+ */
public void printText( StringBuffer text )
throws IOException
{
@@ -318,6 +337,8 @@ public class Printer
/**
* Flush the output stream. Must be called when done printing
* the document, otherwise some text might be buffered.
+ *
+ * @throws IOException if an I/O exception occurs while writing/flushing
*/
public void flush()
throws IOException
diff --git a/src/org/apache/xml/serialize/Serializer.java
b/src/org/apache/xml/serialize/Serializer.java
index 0891a4199..cba955011 100644
--- a/src/org/apache/xml/serialize/Serializer.java
+++ b/src/org/apache/xml/serialize/Serializer.java
@@ -39,6 +39,7 @@ import org.xml.sax.DocumentHandler;
* be thrown by {@link DocumentHandler#endDocument}. The SAX serializer
* may also be used as {@link org.xml.sax.DTDHandler}, {@link
org.xml.sax.ext.DeclHandler} and
* {@link org.xml.sax.ext.LexicalHandler}.
+ * </p>
* <p>
* To serialize a DOM document or DOM element, create a compatible
* serializer and call it's {@link
@@ -46,12 +47,14 @@ import org.xml.sax.DocumentHandler;
* Both methods would produce a full XML document, to serizlie only
* the portion of the document use {@link OutputFormat#setOmitXMLDeclaration}
* and specify no document type.
+ * </p>
* <p>
* The {@link OutputFormat} dictates what underlying serialized is used
* to serialize the document based on the specified method. If the output
* format or method are missing, the default is an XML serializer with
* UTF-8 encoding and now indentation.
- *
+ * </p>
+ *
* @deprecated This class was deprecated in Xerces 2.9.0. It is recommended
* that new applications use the DOM Level 3 LSSerializer or JAXP's
Transformation
* API for XML (TrAX) for serializing XML and HTML. See the Xerces
documentation for more
@@ -73,6 +76,8 @@ public interface Serializer
* Specifies an output stream to which the document should be
* serialized. This method should not be called while the
* serializer is in the process of serializing a document.
+ *
+ * @param output an output stream to which the document should be
serialized
*/
public void setOutputByteStream(OutputStream output);
@@ -81,6 +86,8 @@ public interface Serializer
* Specifies a writer to which the document should be serialized.
* This method should not be called while the serializer is in
* the process of serializing a document.
+ *
+ * @param output a writer to which the document should be serialized
*/
public void setOutputCharStream( Writer output );
@@ -92,7 +99,7 @@ public interface Serializer
* called while the serializer is in the process of serializing
* a document.
*
- * @param format The output format to use
+ * @param format the output format to use
*/
public void setOutputFormat( OutputFormat format );
@@ -100,7 +107,10 @@ public interface Serializer
/**
* Return a {@link DocumentHandler} interface into this serializer.
* If the serializer does not support the {@link DocumentHandler}
- * interface, it should return null.
+ * interface, it should return <code>null</code>.
+ *
+ * @return a {@link DocumentHandler} for the serializer implementation or
<code>null</code>
+ * @throws IOException if an I/O exception occurs in the implementation
*/
public DocumentHandler asDocumentHandler()
throws IOException;
@@ -109,7 +119,10 @@ public interface Serializer
/**
* Return a {@link ContentHandler} interface into this serializer.
* If the serializer does not support the {@link ContentHandler}
- * interface, it should return null.
+ * interface, it should return <code>null</code>.
+ *
+ * @return a {@link ContentHandler} for the serializer implementation or
<code>null</code>
+ * @throws IOException if an I/O exception occurs in the implementation
*/
public ContentHandler asContentHandler()
throws IOException;
@@ -118,7 +131,10 @@ public interface Serializer
/**
* Return a {@link DOMSerializer} interface into this serializer.
* If the serializer does not support the {@link DOMSerializer}
- * interface, it should return null.
+ * interface, it should return <code>null</code>.
+ *
+ * @return a {@link DOMSerializer} for the serializer implementation or
<code>null</code>
+ * @throws IOException if an I/O exception occurs in the implementation
*/
public DOMSerializer asDOMSerializer()
throws IOException;
diff --git a/src/org/apache/xml/serialize/TextSerializer.java
b/src/org/apache/xml/serialize/TextSerializer.java
index 769902cf4..bbd70e4f6 100755
--- a/src/org/apache/xml/serialize/TextSerializer.java
+++ b/src/org/apache/xml/serialize/TextSerializer.java
@@ -39,18 +39,21 @@ import org.xml.sax.SAXException;
* serializing. For usage instructions see {@link Serializer}.
* <p>
* If an output stream is used, the encoding is taken from the
- * output format (defaults to <tt>UTF-8</tt>). If a writer is
+ * output format (defaults to UTF-8). If a writer is
* used, make sure the writer uses the same encoding (if applies)
* as specified in the output format.
+ * </p>
* <p>
* The serializer supports both DOM and SAX. DOM serializing is done
* by calling {@link #serialize} and SAX serializing is done by firing
* SAX events and using the serializer as a document handler.
+ * </p>
* <p>
* If an I/O exception occurs while serializing, the serializer
* will not throw an exception directly, but only throw it
* at the end of serializing (either DOM or SAX's {@link
* org.xml.sax.DocumentHandler#endDocument}.
+ * </p>
*
* @deprecated This class was deprecated in Xerces 2.9.0. It is recommended
* that new applications use the DOM Level 3 LSSerializer or JAXP's
Transformation
@@ -229,6 +232,10 @@ public class TextSerializer
* pre-root comments and PIs that were accumulated in the document
* (see {@link #serializePreRoot}). Pre-root will be serialized even if
* this is not the first root element of the document.
+ * </p>
+ *
+ * @param rootTagName unused
+ * @throws IOException if an I/O error occurred while serializing
*/
protected void startDocument( String rootTagName )
throws IOException
@@ -246,7 +253,7 @@ public class TextSerializer
/**
* Called to serialize a DOM element. Equivalent to calling {@link
* #startElement}, {@link #endElement} and serializing everything
- * inbetween, but better optimized.
+ * in between, but better optimized.
*/
protected void serializeElement( Element elem )
throws IOException
@@ -301,7 +308,7 @@ public class TextSerializer
/**
* Serialize the DOM node. This method is unique to the Text serializer.
*
- * @param node The node to serialize
+ * @param node the node to serialize
*/
protected void serializeNode( Node node )
throws IOException
diff --git a/src/org/apache/xml/serialize/XHTMLSerializer.java
b/src/org/apache/xml/serialize/XHTMLSerializer.java
index b7ebaa712..109bc758a 100644
--- a/src/org/apache/xml/serialize/XHTMLSerializer.java
+++ b/src/org/apache/xml/serialize/XHTMLSerializer.java
@@ -66,11 +66,11 @@ public class XHTMLSerializer
/**
* Constructs a new serializer that writes to the specified writer
- * using the specified output format. If <tt>format</tt> is null,
+ * using the specified output format. If <code>format</code> is null,
* will use a default output format.
*
- * @param writer The writer to use
- * @param format The output format to use, null for the default
+ * @param writer the writer to use
+ * @param format the output format to use, null for the default
*/
public XHTMLSerializer( Writer writer, OutputFormat format )
{
@@ -81,11 +81,11 @@ public class XHTMLSerializer
/**
* Constructs a new serializer that writes to the specified output
- * stream using the specified output format. If <tt>format</tt>
+ * stream using the specified output format. If <code>format</code>
* is null, will use a default output format.
*
- * @param output The output stream to use
- * @param format The output format to use, null for the default
+ * @param output the output stream to use
+ * @param format the output format to use, null for the default
*/
public XHTMLSerializer( OutputStream output, OutputFormat format )
{
diff --git a/src/org/apache/xml/serialize/XML11Serializer.java
b/src/org/apache/xml/serialize/XML11Serializer.java
index 21e43cc18..b6d5ce8b4 100644
--- a/src/org/apache/xml/serialize/XML11Serializer.java
+++ b/src/org/apache/xml/serialize/XML11Serializer.java
@@ -48,9 +48,10 @@ import org.xml.sax.SAXException;
* serializing. For usage instructions see {@link Serializer}.
* <p>
* If an output stream is used, the encoding is taken from the
- * output format (defaults to <tt>UTF-8</tt>). If a writer is
+ * output format (defaults to UTF-8). If a writer is
* used, make sure the writer uses the same encoding (if applies)
* as specified in the output format.
+ * </p>
* <p>
* The serializer supports both DOM and SAX. SAX serializing is done by firing
* SAX events and using the serializer as a document handler. DOM serializing
is done
@@ -58,18 +59,21 @@ import org.xml.sax.SAXException;
* {@link org.w3c.dom.ls.LSSerializer} and
* serializing with {@link org.w3c.dom.ls.LSSerializer#write},
* {@link org.w3c.dom.ls.LSSerializer#writeToString}.
+ * </p>
* <p>
* If an I/O exception occurs while serializing, the serializer
* will not throw an exception directly, but only throw it
* at the end of serializing (either DOM or SAX's {@link
* org.xml.sax.DocumentHandler#endDocument}.
+ * </p>
* <p>
* For elements that are not specified as whitespace preserving,
* the serializer will potentially break long text lines at space
* boundaries, indent lines, and serialize elements on separate
* lines. Line terminators will be regarded as spaces, and
* spaces at beginning of line will be stripped.
- *
+ * </p>
+ *
* @deprecated This class was deprecated in Xerces 2.9.0. It is recommended
* that new applications use the DOM Level 3 LSSerializer or JAXP's
Transformation
* API for XML (TrAX) for serializing XML. See the Xerces documentation for
more
@@ -146,11 +150,11 @@ extends XMLSerializer {
/**
* Constructs a new serializer that writes to the specified writer
- * using the specified output format. If <tt>format</tt> is null,
+ * using the specified output format. If <code>format</code> is null,
* will use a default output format.
*
- * @param writer The writer to use
- * @param format The output format to use, null for the default
+ * @param writer the writer to use
+ * @param format the output format to use, <code>null</code> for the
default
*/
public XML11Serializer( Writer writer, OutputFormat format ) {
super( writer, format );
@@ -160,11 +164,11 @@ extends XMLSerializer {
/**
* Constructs a new serializer that writes to the specified output
- * stream using the specified output format. If <tt>format</tt>
+ * stream using the specified output format. If <code>format</code>
* is null, will use a default output format.
*
- * @param output The output stream to use
- * @param format The output format to use, null for the default
+ * @param output the output stream to use
+ * @param format the output format to use, <code>null</code> for the
default
*/
public XML11Serializer( OutputStream output, OutputFormat format ) {
super( output, format != null ? format : new OutputFormat( Method.XML,
null, false ) );
diff --git a/src/org/apache/xml/serialize/XMLSerializer.java
b/src/org/apache/xml/serialize/XMLSerializer.java
index 9bce5e954..ebf88da7c 100755
--- a/src/org/apache/xml/serialize/XMLSerializer.java
+++ b/src/org/apache/xml/serialize/XMLSerializer.java
@@ -59,9 +59,10 @@ import org.xml.sax.helpers.AttributesImpl;
* serializing. For usage instructions see {@link Serializer}.
* <p>
* If an output stream is used, the encoding is taken from the
- * output format (defaults to <tt>UTF-8</tt>). If a writer is
+ * output format (defaults to UTF-8). If a writer is
* used, make sure the writer uses the same encoding (if applies)
* as specified in the output format.
+ * </p>
* <p>
* The serializer supports both DOM and SAX. SAX serializing is done by firing
* SAX events and using the serializer as a document handler. DOM serializing
is done
@@ -69,18 +70,21 @@ import org.xml.sax.helpers.AttributesImpl;
* {@link org.w3c.dom.ls.LSSerializer} and
* serializing with {@link org.w3c.dom.ls.LSSerializer#write},
* {@link org.w3c.dom.ls.LSSerializer#writeToString}.
+ * </p>
* <p>
* If an I/O exception occurs while serializing, the serializer
* will not throw an exception directly, but only throw it
* at the end of serializing (either DOM or SAX's {@link
* org.xml.sax.DocumentHandler#endDocument}.
+ * </p>
* <p>
* For elements that are not specified as whitespace preserving,
* the serializer will potentially break long text lines at space
* boundaries, indent lines, and serialize elements on separate
* lines. Line terminators will be regarded as spaces, and
* spaces at beginning of line will be stripped.
- *
+ * </p>
+ *
* @deprecated This class was deprecated in Xerces 2.9.0. It is recommended
* that new applications use the DOM Level 3 LSSerializer or JAXP's
Transformation
* API for XML (TrAX) for serializing XML. See the Xerces documentation for
more
@@ -152,6 +156,8 @@ extends BaseMarkupSerializer {
* Constructs a new serializer. The serializer cannot be used without
* calling {@link #setOutputCharStream} or {@link #setOutputByteStream}
* first.
+ *
+ * @param format the output format to use, null for the default
*/
public XMLSerializer( OutputFormat format ) {
super( format != null ? format : new OutputFormat( Method.XML, null,
false ) );
@@ -161,11 +167,11 @@ extends BaseMarkupSerializer {
/**
* Constructs a new serializer that writes to the specified writer
- * using the specified output format. If <tt>format</tt> is null,
+ * using the specified output format. If <code>format</code> is null,
* will use a default output format.
*
- * @param writer The writer to use
- * @param format The output format to use, null for the default
+ * @param writer the writer to use
+ * @param format the output format to use, null for the default
*/
public XMLSerializer( Writer writer, OutputFormat format ) {
super( format != null ? format : new OutputFormat( Method.XML, null,
false ) );
@@ -176,11 +182,11 @@ extends BaseMarkupSerializer {
/**
* Constructs a new serializer that writes to the specified output
- * stream using the specified output format. If <tt>format</tt>
+ * stream using the specified output format. If <code>format</code>
* is null, will use a default output format.
*
- * @param output The output stream to use
- * @param format The output format to use, null for the default
+ * @param output the output stream to use
+ * @param format the output format to use, null for the default
*/
public XMLSerializer( OutputStream output, OutputFormat format ) {
super( format != null ? format : new OutputFormat( Method.XML, null,
false ) );
@@ -189,17 +195,21 @@ extends BaseMarkupSerializer {
}
+ /**
+ * Sets the output format for this serializer.
+ *
+ * @param format the output format to use, null for the default
+ */
public void setOutputFormat( OutputFormat format ) {
super.setOutputFormat( format != null ? format : new OutputFormat(
Method.XML, null, false ) );
}
/**
- * This methods turns on namespace fixup algorithm during
- * DOM serialization.
+ * This method turns on namespace fixup algorithm during DOM serialization.
* @see org.w3c.dom.ls.LSSerializer
*
- * @param namespaces
+ * @param namespaces set to true to enable namespace fixup algorithm
*/
public void setNamespaces (boolean namespaces){
fNamespaces = namespaces;
@@ -546,6 +556,10 @@ extends BaseMarkupSerializer {
* pre-root comments and PIs that were accumulated in the document
* (see {@link #serializePreRoot}). Pre-root will be serialized even if
* this is not the first root element of the document.
+ * </p>
+ *
+ * @param rootTagName the tag name of the root tag
+ * @throws IOException if an I/O exception occurs while serializing
*/
protected void startDocument( String rootTagName )
throws IOException
@@ -632,7 +646,10 @@ extends BaseMarkupSerializer {
/**
* Called to serialize a DOM element. Equivalent to calling {@link
* #startElement}, {@link #endElement} and serializing everything
- * inbetween, but better optimized.
+ * in between, but better optimized.
+ *
+ * @param elem the element to serialize
+ * @throws IOException if an I/O error occurred while serializing
*/
protected void serializeElement( Element elem )
throws IOException
@@ -1099,11 +1116,10 @@ extends BaseMarkupSerializer {
* Serializes a namespace attribute with the given prefix and value for
URI.
* In case prefix is empty will serialize default namespace declaration.
*
- * @param prefix
- * @param uri
- * @exception IOException
+ * @param prefix the namespace prefix. If empty the default namespace
declaration will be used
+ * @param uri the namespace uri value
+ * @throws IOException will be thrown if the attribute cannot be printed
*/
-
private void printNamespaceAttr(String prefix, String uri) throws
IOException{
_printer.printSpace();
if (prefix == XMLSymbols.EMPTY_STRING) {
@@ -1128,10 +1144,10 @@ extends BaseMarkupSerializer {
* Prints attribute.
* NOTE: xml:space attribute modifies output format
*
- * @param name
- * @param value
- * @param isSpecified
- * @exception IOException
+ * @param name the attribute name
+ * @param value the attribute value
+ * @param isSpecified true if this attribute was explicitly given a value
+ * @throws IOException will be thrown if the attribute cannot be printed
*/
private void printAttribute (String name, String value, boolean
isSpecified, Attr attr) throws IOException{
@@ -1388,7 +1404,7 @@ extends BaseMarkupSerializer {
* DOM Level 3:
* Check a node to determine if it contains unbound namespace prefixes.
*
- * @param node The node to check for unbound namespace prefices
+ * @param node the node to check for unbound namespace prefixes
*/
protected void checkUnboundNamespacePrefixedNode (Node node) throws
IOException{
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
