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 5345e59c2 [XERCESJ-1781] Javadoc changes in org.apache.xml.serialize
(#39)
5345e59c2 is described below
commit 5345e59c2195725b65f5873341868f6564c0bbde
Author: Samael <[email protected]>
AuthorDate: Fri Oct 31 12:48:08 2025 +0000
[XERCESJ-1781] Javadoc changes in org.apache.xml.serialize (#39)
---
.../apache/xml/serialize/BaseMarkupSerializer.java | 76 ++++++++-------
src/org/apache/xml/serialize/HTMLdtd.java | 6 +-
src/org/apache/xml/serialize/OutputFormat.java | 102 +++++++++++++++------
src/org/apache/xml/serialize/Printer.java | 21 ++++-
.../apache/xml/serialize/SerializerFactory.java | 32 +++++--
5 files changed, 164 insertions(+), 73 deletions(-)
diff --git a/src/org/apache/xml/serialize/BaseMarkupSerializer.java
b/src/org/apache/xml/serialize/BaseMarkupSerializer.java
index 715c78a6d..64ac47d4d 100644
--- a/src/org/apache/xml/serialize/BaseMarkupSerializer.java
+++ b/src/org/apache/xml/serialize/BaseMarkupSerializer.java
@@ -688,58 +688,52 @@ public abstract class BaseMarkupSerializer
state.afterElement = false;
}
-
+ /**
+ * Start serializing as CDATA section.
+ */
public void startCDATA()
{
- ElementState state;
-
- state = getElementState();
- state.doCData = true;
+ getElementState().doCData = true;
}
-
+ /**
+ * End serializing as CDATA section.
+ */
public void endCDATA()
{
- ElementState state;
-
- state = getElementState();
- state.doCData = false;
+ getElementState().doCData = false;
}
-
+ /**
+ * Start serializing as raw characters.
+ */
public void startNonEscaping()
{
- ElementState state;
-
- state = getElementState();
- state.unescaped = true;
+ getElementState().unescaped = true;
}
-
+ /**
+ * End serializing as raw characters.
+ */
public void endNonEscaping()
{
- ElementState state;
-
- state = getElementState();
- state.unescaped = false;
+ getElementState().unescaped = false;
}
-
+ /**
+ * Start preserving space.
+ */
public void startPreserving()
{
- ElementState state;
-
- state = getElementState();
- state.preserveSpace = true;
+ getElementState().preserveSpace = true;
}
-
+ /**
+ * End preserving space.
+ */
public void endPreserving()
{
- ElementState state;
-
- state = getElementState();
- state.preserveSpace = false;
+ getElementState().preserveSpace = false;
}
@@ -1394,6 +1388,12 @@ public abstract class BaseMarkupSerializer
// Text pretty printing and formatting methods //
//---------------------------------------------//
+ /**
+ * Prints the CDATA text to the underlying Printer.
+ *
+ * @param text CDATA value to be printed
+ * @throws IOException if an I/O error occurs
+ */
protected void printCDATAText( String text ) throws IOException {
int length = text.length();
char ch;
@@ -1627,7 +1627,12 @@ public abstract class BaseMarkupSerializer
_printer.printText( '"' );
}
-
+ /**
+ * Prints the char value to the underlying Printer
+ *
+ * @param ch character value
+ * @throws IOException if an I/O error occurs
+ */
protected void printEscaped( int ch )
throws IOException
{
@@ -1643,7 +1648,7 @@ public abstract class BaseMarkupSerializer
_printer.printText( ';' );
} else if ( ( ch >= ' ' && _encodingInfo.isPrintable((char)ch) && ch
!= 0x7F ) ||
ch == '\n' || ch == '\r' || ch == '\t' ) {
- // Non printables are below ASCII space but not tab or line
+ // Non-printable characters are below ASCII space but not tab or
line
// terminator, ASCII delete, or above a certain Unicode threshold.
if (ch < 0x10000) {
_printer.printText((char)ch );
@@ -1842,7 +1847,12 @@ public abstract class BaseMarkupSerializer
}
-
+ /**
+ * Should be called by subclasses of BaseMarkupSerializer when a fatal
problem occurs.
+ *
+ * @param message the text to describe the problem
+ * @throws IOException if no {@link DOMErrorHandler} is configured
+ */
protected void fatalError(String message) throws IOException{
if (fDOMErrorHandler != null) {
modifyDOMError(message, DOMError.SEVERITY_FATAL_ERROR, null,
fCurrentNode);
diff --git a/src/org/apache/xml/serialize/HTMLdtd.java
b/src/org/apache/xml/serialize/HTMLdtd.java
index c5dac9baa..cc3dc8e41 100755
--- a/src/org/apache/xml/serialize/HTMLdtd.java
+++ b/src/org/apache/xml/serialize/HTMLdtd.java
@@ -273,12 +273,13 @@ public final class HTMLdtd
/**
- * Returns true if the specified attribute it a URI and should be
+ * Returns true if the specified attribute is a URI and should be
* escaped appropriately. In HTML URIs are escaped differently
* than normal attributes.
*
- * @param tagName the element's tag name
+ * @param tagName the element's tag name (unused)
* @param attrName the attribute's name
+ * @return true if the specified attribute is a URI
*/
public static boolean isURI( String tagName, String attrName )
{
@@ -294,6 +295,7 @@ public final class HTMLdtd
*
* @param tagName the element's tag name
* @param attrName the attribute's name
+ * @return true if the specified attribute is a boolean
*/
public static boolean isBoolean( String tagName, String attrName )
{
diff --git a/src/org/apache/xml/serialize/OutputFormat.java
b/src/org/apache/xml/serialize/OutputFormat.java
index e412ae987..65a867b27 100644
--- a/src/org/apache/xml/serialize/OutputFormat.java
+++ b/src/org/apache/xml/serialize/OutputFormat.java
@@ -188,19 +188,19 @@ public class OutputFormat
/**
- * True if the XML declaration should be ommited;
+ * True if the XML declaration should be omitted.
*/
private boolean _omitXmlDeclaration = false;
/**
- * True if the DOCTYPE declaration should be ommited;
+ * True if the DOCTYPE declaration should be omitted.
*/
private boolean _omitDoctype = false;
/**
- * True if comments should be ommited;
+ * True if comments should be omitted.
*/
private boolean _omitComments = false;
@@ -388,6 +388,8 @@ public class OutputFormat
/**
* Returns true if indentation was specified.
+ *
+ * @return true if indentation was specified
*/
public boolean getIndenting()
{
@@ -452,7 +454,7 @@ public class OutputFormat
* used by the {@link java.io.Writer}.
*
* @see #getEncoding
- * @param encoding the encoding, or <code>null</code>
+ * @param encoding the encoding, or null
*/
public void setEncoding( String encoding )
{
@@ -486,14 +488,18 @@ public class OutputFormat
}
/**
- * Sets whether java encoding names are permitted
+ * Sets whether Java encoding names are permitted.
+ *
+ * @param allow set to true to permit Java encoding names
*/
public void setAllowJavaNames (boolean allow) {
_allowJavaNames = allow;
}
/**
- * Returns whether java encoding names are permitted
+ * Returns whether Java encoding names are permitted.
+ *
+ * @return whether Java encoding names are permitted
*/
public boolean setAllowJavaNames () {
return _allowJavaNames;
@@ -504,7 +510,7 @@ public class OutputFormat
* To determine the media type based on the
* document type, use {@link #whichMediaType}.
*
- * @return The specified media type, or null
+ * @return the specified media type, or null
*/
public String getMediaType()
{
@@ -543,8 +549,9 @@ public class OutputFormat
/**
- * Returns the specified document type public identifier,
- * or null.
+ * Returns the specified document type public identifier, or null.
+ *
+ * @return the specified document type public identifier, or null
*/
public String getDoctypePublic()
{
@@ -553,8 +560,9 @@ public class OutputFormat
/**
- * Returns the specified document type system identifier,
- * or null.
+ * Returns the specified document type system identifier, or null.
+ *
+ * @return the specified document type system identifier, or null
*/
public String getDoctypeSystem()
{
@@ -563,8 +571,10 @@ public class OutputFormat
/**
- * Returns true if comments should be ommited.
+ * Returns true if comments should be omitted.
* The default is false.
+ *
+ * @return true if comments should be omitted (default is false)
*/
public boolean getOmitComments()
{
@@ -575,7 +585,7 @@ public class OutputFormat
/**
* Sets comment omitting on and off.
*
- * @param omit True if comments should be ommited
+ * @param omit True if comments should be omitted
*/
public void setOmitComments( boolean omit )
{
@@ -584,8 +594,9 @@ public class OutputFormat
/**
- * Returns true if the DOCTYPE declaration should
- * be ommited. The default is false.
+ * Returns true if the DOCTYPE declaration should be omitted. The default
is false.
+ *
+ * @return true if the DOCTYPE declaration should be omitted (default is
false)
*/
public boolean getOmitDocumentType()
{
@@ -596,7 +607,7 @@ public class OutputFormat
/**
* Sets DOCTYPE declaration omitting on and off.
*
- * @param omit True if DOCTYPE declaration should be ommited
+ * @param omit true if DOCTYPE declaration should be omitted
*/
public void setOmitDocumentType( boolean omit )
{
@@ -605,8 +616,9 @@ public class OutputFormat
/**
- * Returns true if the XML document declaration should
- * be ommited. The default is false.
+ * Returns true if the XML document declaration should be omitted. The
default is false.
+ *
+ * @return true if the XML document declaration should be omitted (default
is false)
*/
public boolean getOmitXMLDeclaration()
{
@@ -617,7 +629,7 @@ public class OutputFormat
/**
* Sets XML declaration omitting on and off.
*
- * @param omit True if XML declaration should be ommited
+ * @param omit true if XML declaration should be omitted
*/
public void setOmitXMLDeclaration( boolean omit )
{
@@ -628,6 +640,8 @@ public class OutputFormat
/**
* Returns true if the document type is standalone.
* The default is false.
+ *
+ * @return true if the document type is standalone (default is false)
*/
public boolean getStandalone()
{
@@ -640,7 +654,7 @@ public class OutputFormat
* identifiers must be null for the document to be
* serialized as standalone.
*
- * @param standalone True if document DTD is standalone
+ * @param standalone true if document DTD is standalone
*/
public void setStandalone( boolean standalone )
{
@@ -649,9 +663,11 @@ public class OutputFormat
/**
- * Returns a list of all the elements whose text node children
+ * Returns an array of all the elements whose text node children
* should be output as CDATA, or null if no such elements were
* specified.
+ *
+ * @return an array of all the elements whose text node children should be
output as CDATA, or null
*/
public String[] getCDataElements()
{
@@ -692,9 +708,12 @@ public class OutputFormat
/**
- * Returns a list of all the elements whose text node children
+ * Returns an array of all the elements whose text node children
* should be output unescaped (no character references), or null
* if no such elements were specified.
+ *
+ * @return an array of all the elements whose text node children
+ * should be output unescaped (no character references), or null
*/
public String[] getNonEscapingElements()
{
@@ -707,7 +726,7 @@ public class OutputFormat
* should be output unescaped.
*
* @param tagName The element's tag name
- * @return True if should serialize unescaped
+ * @return true if should serialize unescaped
*/
public boolean isNonEscapingElement( String tagName )
{
@@ -724,10 +743,10 @@ public class OutputFormat
/**
- * Sets the list of elements for which text node children
- * should be output unescaped (no character references).
+ * Sets the elements for which text node children should be output
+ * unescaped (no character references).
*
- * @param nonEscapingElements List of unescaped element tag names
+ * @param nonEscapingElements unescaped element tag names
*/
public void setNonEscapingElements( String[] nonEscapingElements )
{
@@ -741,7 +760,7 @@ public class OutputFormat
* Web line separator (<code>\n</code>). A string is returned to
* support double codes (CR + LF).
*
- * @return The specified line separator
+ * @return the line separator
*/
public String getLineSeparator()
{
@@ -756,7 +775,7 @@ public class OutputFormat
* useful if the document is edited on machines of the same type.
* For general documents, use the Web line separator.
*
- * @param lineSeparator The specified line separator
+ * @param lineSeparator The line separator
*/
public void setLineSeparator( String lineSeparator )
{
@@ -773,6 +792,8 @@ public class OutputFormat
* or specify the default behavior will be formatted based on
* this rule. All elements that specify space preserving will
* always preserve space.
+ *
+ * @return true if the default behavior for this format is to preserve
spaces
*/
public boolean getPreserveSpace()
{
@@ -794,10 +815,12 @@ public class OutputFormat
/**
- * Return the selected line width for breaking up long lines.
+ * Return the line width for breaking up long lines.
* When indenting, and only when indenting, long lines will be
* broken at space boundaries based on this line width.
* No line wrapping occurs if this value is zero.
+ *
+ * @return the line width for breaking up long lines
*/
public int getLineWidth()
{
@@ -837,6 +860,8 @@ public class OutputFormat
* Returns the last printable character based on the selected
* encoding. Control characters and non-printable characters
* are always printed as character references.
+ *
+ * @return the last printable character based on the encoding
*/
public char getLastPrintable()
{
@@ -907,6 +932,8 @@ public class OutputFormat
/**
* Returns the document type public identifier
* specified for this document, or null.
+ *
+ * @return the document type public identifier specified for this
document, or null
*/
public static String whichDoctypePublic( Document doc )
{
@@ -931,6 +958,9 @@ public class OutputFormat
/**
* Returns the document type system identifier
* specified for this document, or null.
+ *
+ * @param doc the document to check
+ * @return the document type system identifier specified for this
document, or null
*/
public static String whichDoctypeSystem( Document doc )
{
@@ -953,8 +983,20 @@ public class OutputFormat
/**
- * Returns the suitable media format for a document
+ * Returns the media format for a document
* output with the specified method.
+ *
+ * <p>Supported methods are:</p>
+ * <ul>
+ * <li>xml</li>
+ * <li>html</li>
+ * <li>xhtml</li>
+ * <li>test</li>
+ * <li>fop</li>
+ * </ul>
+ *
+ * @param method for which a media type is required
+ * @return the media format for a document, or null
*/
public static String whichMediaType( String method )
{
diff --git a/src/org/apache/xml/serialize/Printer.java
b/src/org/apache/xml/serialize/Printer.java
index f53857683..8c5b54770 100644
--- a/src/org/apache/xml/serialize/Printer.java
+++ b/src/org/apache/xml/serialize/Printer.java
@@ -104,6 +104,12 @@ public class Printer
private int _pos = 0;
+ /**
+ * Create a new Printer instance with the desired char stream and output
format.
+ *
+ * @param writer an output char stream that will be written to
+ * @param format the output format to use
+ */
public Printer( Writer writer, OutputFormat format)
{
_writer = writer;
@@ -115,6 +121,12 @@ public class Printer
}
+ /**
+ * If the serializer encountered an exception it is held until the
serializer finishes.
+ * <p>This allows the serializer to retrieve the exception after flushing,
if one exists.</p>
+ *
+ * @return an IOException or null
+ */
public IOException getException()
{
return _exception;
@@ -151,7 +163,7 @@ public class Printer
* DTD parts were printer, will return a string with their
* textual content.
*
- * @return a string of DTD content or <code>null</code>
+ * @return a string of DTD content or null
* @throws IOException can be thrown by underlying call to {@link
Printer#flushLine(boolean)}
*/
public String leaveDTD()
@@ -250,7 +262,12 @@ public class Printer
}
}
-
+ /**
+ * Writes the char value to the underlying Writer
+ *
+ * @param ch character value
+ * @throws IOException if an I/O error occurs
+ */
public void printText( char ch )
throws IOException
{
diff --git a/src/org/apache/xml/serialize/SerializerFactory.java
b/src/org/apache/xml/serialize/SerializerFactory.java
index ac65748b6..82ced640d 100644
--- a/src/org/apache/xml/serialize/SerializerFactory.java
+++ b/src/org/apache/xml/serialize/SerializerFactory.java
@@ -34,7 +34,19 @@ import java.util.StringTokenizer;
*/
@Deprecated
public abstract class SerializerFactory {
-
+
+ /**
+ * The system property for registering additional implementations of
SerializerFactory.
+ * <p>
+ * Multiple factories can be registered by using a delimiter between
the values. Any of the following are supported:
+ * </p>
+ * <ul>
+ * <li><i>a single space</i></li>
+ * <li><strong>;</strong> semicolon</li>
+ * <li><strong>,</strong> comma</li>
+ * <li><strong>:</strong> colon</li>
+ * </ul>
+ */
public static final String FactoriesProperty =
"org.apache.xml.serialize.factories";
private static Hashtable _factories = new Hashtable();
@@ -114,6 +126,9 @@ public abstract class SerializerFactory {
* If this method is used to create the serializer, the {@link
* Serializer#setOutputByteStream} or {@link
Serializer#setOutputCharStream}
* methods must be called before serializing a document.
+ *
+ * @param format the output format to use
+ * @return a new serializer for the given output format
*/
public abstract Serializer makeSerializer(OutputFormat format);
@@ -122,18 +137,23 @@ public abstract class SerializerFactory {
* Create a new serializer, based on the {@link OutputFormat} and
* using the writer as the output character stream. If this
* method is used, the encoding property will be ignored.
+ *
+ * @param writer an output char stream that will be written to
+ * @param format the output format to use
+ * @return a new serializer for the given output format
*/
public abstract Serializer makeSerializer( Writer writer,
OutputFormat format );
/**
- * Create a new serializer, based on the {@link OutputFormat} and
- * using the output byte stream and the encoding specified in the
- * output format.
+ * Create a new serializer, based on the {@link OutputFormat} and using the
+ * output stream and the encoding specified in the output format.
*
- * @throws UnsupportedEncodingException The specified encoding is
- * not supported
+ * @param output an output stream that will be written to
+ * @param format the output format to use
+ * @return a new serializer for the given output format
+ * @throws UnsupportedEncodingException if the specified encoding is not
supported
*/
public abstract Serializer makeSerializer( OutputStream output,
OutputFormat format )
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
