sboag 00/06/20 09:29:55
Added: java/src/serialize DOMSerializer.java Method.java
OutputFormat.java QName.java Serializer.java
SerializerFactory.java SerializerHandler.java
package.html serializer.properties
java/src/serialize/helpers HTMLOutputFormat.java
TextOutputFormat.java XHTMLOutputFormat.java
XMLOutputFormat.java
Log:
no message
Revision Changes Path
1.1 xml-xalan/java/src/serialize/DOMSerializer.java
Index: DOMSerializer.java
===================================================================
package serialize;
import java.io.IOException;
import org.w3c.dom.Element;
import org.w3c.dom.Document;
import org.w3c.dom.DocumentFragment;
/**
* Interface for a DOM serializer implementation.
* <p>
* The DOM serializer is a facet of a serializer. A serializer may or may
* not support a DOM serializer.
* <p>
* Example:
* <pre>
* Document doc;
* Serializer ser;
* OutputStream os;
*
* ser.setOutputStream( os );
* ser.asDOMSerializer( doc );
* </pre>
*
*
* @version Alpha
* @author <a href="mailto:Scott_Boag/CAM/[EMAIL PROTECTED]">Scott Boag</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Assaf Arkin</a>
*/
public interface DOMSerializer
{
/**
* Serializes the DOM element. Throws an exception only if an I/O
* exception occured while serializing.
*
* @param elem The element to serialize
* @throws IOException An I/O exception occured while serializing
*/
public void serialize( Element elem )
throws IOException;
/**
* Serializes the DOM document. Throws an exception only if an I/O
* exception occured while serializing.
*
* @param doc The document to serialize
* @throws IOException An I/O exception occured while serializing
*/
public void serialize( Document doc )
throws IOException;
/**
* Serializes the DOM document fragment. Throws an exception only
* if an I/O exception occured while serializing.
*
* @param frag The document fragment to serialize
* @throws IOException An I/O exception occured while serializing
*/
public void serialize( DocumentFragment frag )
throws IOException;
}
1.1 xml-xalan/java/src/serialize/Method.java
Index: Method.java
===================================================================
package serialize;
/**
* Names of the four default output methods.
* <p>
* Four default output methods are defined: XML, HTML, XHTML and TEXT.
* Serializers may support additional output methods. The names of
* these output methods should be encoded as <tt>namespace:local</tt>.
*
* @version Alpha
* @author <a href="mailto:[EMAIL PROTECTED]">Assaf Arkin</a>
* @see OutputFormat
*/
public final class Method
{
/**
* The output method for XML documents: <tt>xml</tt>.
*/
public static final String XML = "xml";
/**
* The output method for HTML documents: <tt>html</tt>.
*/
public static final String HTML = "html";
/**
* The output method for XHTML documents: <tt>xhtml</tt>.
*/
public static final String XHTML = "xhtml";
/**
* The output method for text documents: <tt>text</tt>.
*/
public static final String Text = "text";
}
1.1 xml-xalan/java/src/serialize/OutputFormat.java
Index: OutputFormat.java
===================================================================
package serialize;
/**
* The output format affects the manner in which a document is
* serialized. The output format determines the output method,
* encoding, indentation, document type, and various other properties
* that affect the manner in which a document is serialized.
* <p>
* Once an output format has been handed to a serializer or XSLT
* processor, the application should not attempt to reuse it. The
* serializer or XSLT processor may modify the properties of the
* output format object.
* <p>
* Implementations may provide classes that extend <tt>OutputFormat</tt>
* with additional properties, e.g. indentation level, line separation,
* namespace handlers, etc. An application may use these extra properties
* by constructing an output format object based on the implementation
* specified type.
* <p>
* <tt>OutputFormat</tt> has been modeled after the XSLT <xsl:output>
* element declaration. However, it does not assume the existence of an
* XSLT processor or a particular serializer.
* <p>
* Typical usage scenarios supported by <tt>OutputFormat<tt>:
* <ul>
* <li>The application constructs an <tt>OutputFormat</tt> object and
* passes it to the serializer
* <li>The application constructs an <tt>OutputFormat</tt> object and
* passes it to the XSLT processor, overriding the properties
* specified in the stylesheet
* <li>The XSLT processor constructs an <tt>OutputFormat</tt> object
* and passes it to the serializer
* <li>The XSLT processor constructs an <tt>OutputFormat</tt> object
* from the stylesheet and returns it to the applicatio, the
* application passes <tt>OutputFormat</tt> to the serializer
* </ul>
*
* @version Alpha
* @author <a href="mailto:[EMAIL PROTECTED]">Assaf Arkin</a>
* <a href="mailto:[EMAIL PROTECTED]">Keith Visco</a>
* @see Method
*/
public class OutputFormat
{
/**
* Holds the output method specified for this document,
* or null if no method was specified.
*
* @see Method
*/
private String _method = Method.XML;
/**
* Specifies the version of the output method, null for the
* default.
*/
private String _version = null;
/**
* True if indentation is requested, false for no indentation.
*/
private boolean _indent = false;
/**
* The encoding to use, if an input stream is used, null for
* the default.
*/
private String _encoding = null;
/**
* The specified media type or null.
*/
private String _mediaType = null;
/**
* The specified document type system identifier, or null.
*/
private String _doctypeSystemId = null;
/**
* The specified document type public identifier, or null.
*/
private String _doctypePublicId = null;
/**
* Ture if the XML declaration should be ommited;
*/
private boolean _omitXmlDeclaration = false;
/**
* List of element tag names whose text node children must
* be output as CDATA.
*/
private QName[] _cdataElements = new QName[ 0 ];
/**
* List of element tag names whose text node children must
* be output unescaped.
*/
private QName[] _nonEscapingElements = new QName[ 0 ];
/**
* True if spaces should be preserved in elements that do not
* specify otherwise, or specify the default behavior.
*/
private boolean _preserve = false;
/**
* Constructs a new output format with the default values.
*/
public OutputFormat()
{
}
/**
* Returns the method specified for this output format. See [EMAIL
PROTECTED]
* Method} for a list of the default methods. Other methods should
* be of the format <tt>namespace:local</tt>. The default is
* [EMAIL PROTECTED] Method#XML}.
*
* @return The specified output method
*/
public String getMethod()
{
return _method;
}
/**
* Sets the method for this output format. See [EMAIL PROTECTED] Method}
for
* a list of the default methods. Other methods should be of the
* format <tt>namespace:local</tt>.
*
* @param method The output method, or null
*/
public void setMethod( String method )
{
_method = method;
}
/**
* Returns the version for this output method. If no version was
* specified, will return null and the default version number will
* be used. If the serializer does not support that particular
* version, it should default to a supported version.
*
* @return The specified method version, or null
*/
public String getVersion()
{
return _version;
}
/**
* Sets the version for this output method.
*
* @param version The output method version, or null
*/
public void setVersion( String version )
{
_version = version;
}
/**
* Returns true if indentation was specified. If no indentation
* was specified, returns false. A derived class may support
* additional properties, e.g. indentation level, line width to
* wrap at, tab/spaces, etc.
*
* @return True if indentation was specified
*/
public boolean getIndent()
{
return _indent;
}
/**
* Sets the indentation on and off. A derived class may support
* additional properties, e.g. indentation level, line width to
* wrap at, tab/spaces, etc. A serializer need not support
* indentation.
*
* @param ident True specifies identiation
*/
public void setIndenting( boolean indent )
{
_indent = indent;
}
/**
* Returns the specified encoding. If no encoding was specified,
* the default is used. For XML and HTML the default would be
* "UTF-8". For other output methods, the default encoding is
* unspecified.
*
* @return The encoding
*/
public String getEncoding()
{
return _encoding;
}
/**
* Sets the encoding for this output method. Null means the
* default encoding for the selected output method. For XML and
* HTML the default would be "UTF-8". For other output methods,
* the default encoding is unspecified.
*
* @param encoding The encoding, or null
*/
public void setEncoding( String encoding )
{
_encoding = encoding;
}
/**
* Returns the specified media type. For each output method a
* default media type will be used if one was not specified.
*
* @return The specified media type, or null
*/
public String getMediaType()
{
return _mediaType;
}
/**
* Sets the media type. For each output method a default media
* type will be used if one was not specified.
*
* @param mediaType The specified media type
*/
public void setMediaType( String mediaType )
{
_mediaType = mediaType;
}
/**
* Sets the document type public identifiers. If not specified the
* document type will depend on the output method (e.g. HTML, XHTML)
* or from some other mechanism (e.g. SAX events, DOM DocumentType).
*
* @param publicId The public identifier
*/
public void setDoctypePublicId( String publicId )
{
_doctypePublicId = publicId;
}
/**
* Returns the specified document type public identifier,
* or null.
*/
public String getDoctypePublicId()
{
return _doctypePublicId;
}
/**
* Sets the document type system identifiers. If not specified the
* document type will depend on the output method (e.g. HTML, XHTML)
* or from some other mechanism (e.g. SAX events, DOM DocumentType).
*
* @param systemId The system identifier
*/
public void setDoctypeSystemId( String systemId )
{
_doctypeSystemId = systemId;
}
/**
* Returns the specified document type system identifier,
* or null.
*/
public String getDoctypeSystemId()
{
return _doctypeSystemId;
}
/**
* Returns true if the XML document declaration should
* be ommited. The default is false.
*/
public boolean getOmitXMLDeclaration()
{
return _omitXmlDeclaration;
}
/**
* Sets XML declaration omitting on and off.
*
* @param omit True if XML declaration should be ommited
*/
public void setOmitXMLDeclaration( boolean omit )
{
_omitXmlDeclaration = omit;
}
/**
* Returns a list of all the elements whose text node children
* should be output as CDATA. Returns an empty array if no such
* elements were specified.
*
* @return List of all CDATA elements
*/
public QName[] getCDataElements()
{
return _cdataElements;
}
/**
* Sets the list of elements for which text node children
* should be output as CDATA.
*
* @param cdataElements List of all CDATA elements
*/
public void setCDataElements( QName[] cdataElements )
{
if ( cdataElements == null )
_cdataElements = new QName[ 0 ];
else
_cdataElements = cdataElements;
}
/**
* Returns a list of all the elements whose text node children
* should be output unescaped (no character references). Returns
* an empty array if no such elements were specified.
*
* @return List of all non escaping elements
*/
public QName[] getNonEscapingElements()
{
return _nonEscapingElements;
}
/**
* Sets the list of elements for which text node children
* should be output unescaped (no character references).
*
* @param nonEscapingElements List of all non-escaping elements
*/
public void setNonEscapingElements( QName[] nonEscapingElements )
{
if ( nonEscapingElements == null )
_nonEscapingElements = new QName[ 0 ];
else
_nonEscapingElements = nonEscapingElements;
}
/**
* Returns true if the default behavior for this format is to
* preserve spaces. All elements that do not specify otherwise
* or specify the default behavior will be formatted based on
* this rule. All elements that specify space preserving will
* always preserve space.
*/
public boolean getPreserveSpace()
{
return _preserve;
}
/**
* Sets space preserving as the default behavior. The default is
* space stripping and all elements that do not specify otherwise
* or use the default value will not preserve spaces.
*
* @param preserve True if spaces should be preserved
*/
public void setPreserveSpace( boolean preserve )
{
_preserve = preserve;
}
}
1.1 xml-xalan/java/src/serialize/QName.java
Index: QName.java
===================================================================
package serialize;
/**
* A qualified name. A qualified name has a local name, a namespace
* URI and a prefix (if known). A <tt>QName</tt> may also specify
* a non-qualified name by having a null namespace URI.
*
* @version Alpha
* @author <a href="mailto:[EMAIL PROTECTED]">Assaf Arkin</a>
*/
public class QName
{
/**
* The local name.
*/
private String _localName;
/**
* The namespace URI.
*/
private String _namespaceURI;
/**
* The namespace prefix.
*/
private String _prefix;
/**
* Constructs a new QName with the specified namespace URI and
* local name.
*
* @param namespaceURI The namespace URI if known, or null
* @param localName The local name
*/
public QName( String namespaceURI, String localName )
{
if ( localName == null )
throw new IllegalArgumentException( "Argument 'localName' is
null" );
_namespaceURI = namespaceURI;
_localName = localName;
}
/**
* Constructs a new QName with the specified namespace URI, prefix
* and local name.
*
* @param namespaceURI The namespace URI if known, or null
* @param prefix The namespace prefix is known, or null
* @param localName The local name
*/
public QName( String namespaceURI, String prefix, String localName )
{
if ( localName == null )
throw new IllegalArgumentException( "Argument 'localName' is
null" );
_namespaceURI = namespaceURI;
_prefix = prefix;
_localName = localName;
}
/**
* Returns the namespace URI. Returns null if the namespace URI
* is not known.
*
* @return The namespace URI, or null
*/
public String getNamespaceURI()
{
return _namespaceURI;
}
/**
* Returns the namespace prefix. Returns null if the namespace
* prefix is not known.
*
* @return The namespace prefix, or null
*/
public String getPrefix()
{
return _prefix;
}
/**
* Returns the local part of the qualified name.
*
* @return The local part of the qualified name
*/
public String getLocalName()
{
return _localName;
}
public boolean equals( Object object )
{
if ( object == this )
return true;
if ( object instanceof QName ) {
return ( ( ( _localName == null && ( (QName) object )._localName
== null ) ||
( _localName != null && _localName.equals( ( (QName)
object )._localName ) ) ) &&
( ( _namespaceURI == null && ( (QName) object
)._namespaceURI == null ) ||
( _namespaceURI != null && _namespaceURI.equals( (
(QName) object )._namespaceURI ) ) ) &&
( ( _prefix == null && ( (QName) object )._prefix ==
null ) ||
( _prefix != null && _prefix.equals( ( (QName) object
)._prefix ) ) ) );
}
return false;
}
public String toString()
{
return _prefix != null ? ( _prefix + ":" + _localName ) :
( _namespaceURI != null ? ( _namespaceURI + "^" + _localName ) :
_localName );
}
}
1.1 xml-xalan/java/src/serialize/Serializer.java
Index: Serializer.java
===================================================================
package serialize;
import java.io.Writer;
import java.io.OutputStream;
import java.io.IOException;
import org.xml.sax.DocumentHandler;
import org.xml.sax.ContentHandler;
/**
* A serializer is used for serializing a document with a given output
* method. The [EMAIL PROTECTED] Serializer} object serves as an anchor point
for
* setting the output stream and output format, for obtaining objects
* for serializing the document, and for resetting the serializer.
* <p>
* Prior to using the serializer, the output format and output stream
* or writer should be set. The serializer is then used in one of
* three ways:
* <ul>
* <li>To serialize SAX 1 events call [EMAIL PROTECTED] #asDocumentHandler}
* <li>To serialize SAX 2 events call [EMAIL PROTECTED] #asContentHandler}
* <li>To serialize a DOM document call [EMAIL PROTECTED] #asDOMSerializer}
* </ul>
* <p>
* The application may call one of these methods to obtain a way to
* serialize the document. It may not attempt to use two different
* handlers at the same time, nor should it use the same handler to
* serialize two documents.
* <p>
* The serializer may be recycled and used with a different or the
* same output format and output stream, by calling the [EMAIL PROTECTED]
#reset}
* method after completing serialization.
* <p>
* A serializer is not thread safe. Only one thread should call the
* <tt>asXXX</tt> methods and use the returned handler.
* <p>
* Example:
* <pre>
* ser = SerializerFactory.getSerializer( Method.XML );
* emptyDoc( ser, System.out );
* emptyDoc( ser, System.err );
* . . .
*
* void emptyDoc( Serializer ser, OutputStream os )
* {
* ser.setOutputStream( os );
* ser.asDocumentHandler().startDocument();
* ser.asDocumentHandler().startElement( "empty", new AttributeListImpl()
);
* ser.asDocumentHandler().endElement( "empty" );
* ser.asDocumentHandler().endDocument();
* ser.reset();
* }
* </pre>
*
* @version Alpha
* @author <a href="mailto:[EMAIL PROTECTED]">Assaf Arkin</a>
* @author <a href="mailto:Scott_Boag/CAM/[EMAIL PROTECTED]">Scott Boag</a>
*/
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.
* <p>
* The encoding specified in the [EMAIL PROTECTED] OutputFormat} is used,
or
* if no encoding was specified, the default for the selected
* output method.
*
* @param output The output stream
*/
public void setOutputStream( OutputStream output );
/**
* 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.
* <p>
* The encoding specified for the [EMAIL PROTECTED] OutputFormat} must be
* identical to the output format used with the writer.
*
* @param writer The output writer stream
*/
public void setWriter( Writer writer );
/**
* Specifies an output format for this serializer. It the
* serializer has already been associated with an output format,
* it will switch to the new format. This method should not be
* called while the serializer is in the process of serializing
* a document.
*
* @param format The output format to use
*/
public void setOutputFormat( OutputFormat format );
/**
* Returns the output format for this serializer.
*
* @return The output format in use
*/
public OutputFormat getOutputFormat();
/**
* Return a [EMAIL PROTECTED] DocumentHandler} interface into this
serializer.
* If the serializer does not support the [EMAIL PROTECTED]
DocumentHandler}
* interface, it should return null.
*
* @return A [EMAIL PROTECTED] DocumentHandler} interface into this
serializer,
* or null if the serializer is not SAX 1 capable
* @throws IOException An I/O exception occured
*/
public DocumentHandler asDocumentHandler()
throws IOException;
/**
* Return a [EMAIL PROTECTED] ContentHandler} interface into this
serializer.
* If the serializer does not support the [EMAIL PROTECTED]
ContentHandler}
* interface, it should return null.
*
* @return A [EMAIL PROTECTED] ContentHandler} interface into this
serializer,
* or null if the serializer is not SAX 2 capable
* @throws IOException An I/O exception occured
*/
public ContentHandler asContentHandler()
throws IOException;
/**
* Return a [EMAIL PROTECTED] DOMSerializer} interface into this
serializer.
* If the serializer does not support the [EMAIL PROTECTED] DOMSerializer}
* interface, it should return null.
*
* @return A [EMAIL PROTECTED] DOMSerializer} interface into this
serializer,
* or null if the serializer is not DOM capable
* @throws IOException An I/O exception occured
*/
public DOMSerializer asDOMSerializer()
throws IOException;
/**
* Resets the serializer. If this method returns true, the
* serializer may be used for subsequent serialization of new
* documents. It is possible to change the output format and
* output stream prior to serializing, or to use the existing
* output format and output stream.
*
* @return True if serializer has been reset and can be reused
*/
public boolean reset();
}
1.1 xml-xalan/java/src/serialize/SerializerFactory.java
Index: SerializerFactory.java
===================================================================
package serialize;
import java.util.Enumeration;
import java.util.Hashtable;
import java.util.Properties;
import java.util.StringTokenizer;
import java.io.IOException;
/**
* Factory for creating default serializers. An implementation need
* only support the default output methods (XML, HTML and Text).
* Additional serializers may be constructed directly by the application.
* <p>
* The factory is used with the default serializers provided by the
* implementation and named in the <tt>serializer.properties</tt>
* file of the implementation.
* <p>
* Usage example:
* <pre>
* Serializer ser;
*
* ser = SerializerFactory.getSerializer( Method.XML );
* </pre>
* or,
* <pre>
* Serializer ser;
* OutputFormat format;
*
* format = SerializerFactory.getOutputFormat( Method.HTML );
* ser = SerializerFactory.getSerializer( format );
* </pre>
* <p>
*
*
*
* @version Alpha
* @author <a href="mailto:[EMAIL PROTECTED]">Assaf Arkin</a>
*/
public abstract class SerializerFactory
{
/**
* The name of the properties file listing all the supported
* serializers. (<tt>/org/xml/serilize/serializer.properties</tt>).
*/
public static final String PropertiesResource =
"/org/xml/serilize/serializer.properties";
/**
* The name of the property listing all the supported output
* methods. Contains a comma delimited list of method names.
* (<tt>serialize.methods</tt>).
*/
public static final String PropertyMethods =
"serialize.methods";
/**
* The prefix of a property supplying the class name for a
* serializer implementing a specific method.
* (<tt>serialize.</tt>).
*/
public static final String PropertySerializerPrefix =
"serialize.";
/**
* The prefix of a property supplying the class name for an
* output format implementing a specific method.
* (<tt>serialize.format.</tt>).
*/
public static final String PropertyFormatPrefix =
"serialize.format.";
/**
* Associates output methods to serializer classes.
*/
private static Hashtable _serializers = new Hashtable();
/**
* Associates output methods to default output formats.
*/
private static Hashtable _formats = new Hashtable();
/**
* Returns a serializer for the specified output method. Returns
* null if no implementation exists that supports the specified
* output method. For a list of the default output methods see
* [EMAIL PROTECTED] Method}.
*
* @param method The output method
* @return A suitable serializer, or null
*/
public static Serializer getSerializer( String method )
{
Serializer ser;
Class cls;
cls = (Class) _serializers.get( method );
if ( cls == null )
return null;
try {
ser = (Serializer) cls.newInstance();
} catch ( Exception except ) {
return null;
}
return ser;
}
/**
* Returns a serializer for the specified output method. Returns
* null if no implementation exists that supports the specified
* output method. For a list of the default output methods see
* [EMAIL PROTECTED] Method}.
*
* @param format The output format
* @return A suitable serializer, or null
*/
public static Serializer getSerializer( OutputFormat format )
{
Serializer ser;
Class cls;
if ( format.getMethod() == null )
throw new IllegalArgumentException( "The output format has not
method name" );
cls = (Class) _serializers.get( format.getMethod() );
if ( cls == null )
return null;
try {
ser = (Serializer) cls.newInstance();
} catch ( Exception except ) {
return null;
}
ser.setOutputFormat( format );
return ser;
}
/**
* Returns an output format for the specified output method.
* An implementation may extend [EMAIL PROTECTED] OutputFormat} to provide
* additional properties.
*
* @param method The output method
* @return A suitable output format
*/
public static OutputFormat getOutputFormat( String method )
{
OutputFormat format;
Class cls;
cls = (Class) _formats.get( method );
if ( cls != null ) {
try {
format = (OutputFormat) cls.newInstance();
return format;
} catch ( Exception except ) { }
}
format = new OutputFormat();
format.setMethod( method );
return format;
}
/**
* Returns an enumeration of all the output methods supported by this
* implementation. The enumeration contains the names of all the output
* methods for which this implementation provides a serializer.
*
* @return An enumeration of all output methods
*/
public Enumeration listMethods()
{
return _serializers.keys();
}
/**
* Static constructor loads serializers and output formats
* from properties file.
*/
static {
Properties props;
StringTokenizer token;
try {
props = new Properties();
props.load( SerializerFactory.class.getResourceAsStream(
PropertiesResource ) );
if ( props.getProperty ( PropertyMethods ) == null )
System.err.println( "Serializer property file has no " +
PropertyMethods + " property" );
else {
token = new StringTokenizer( props.getProperty (
PropertyMethods ) );
while ( token.hasMoreElements() ) {
String method;
String clsName;
Class cls;
method = token.nextToken();
// Get the serializer class that matches this output
method
clsName = props.getProperty( PropertySerializerPrefix +
method );
if ( clsName == null ) {
System.err.println( "Could not find property for
serializer implementing output method " + method );
} else {
try {
cls =
SerializerFactory.class.getClassLoader().loadClass( clsName );
_serializers.put( method, cls );
} catch ( ClassNotFoundException except ) {
System.err.println( "Could not locate serializer
class " + clsName );
}
}
// Get the output format class that matches this output
method
clsName = props.getProperty( PropertyFormatPrefix +
method );
if ( clsName == null ) {
System.err.println( "Could not find property for
output format implementing output method " + method );
} else {
try {
cls =
SerializerFactory.class.getClassLoader().loadClass( clsName );
_formats.put( method, cls );
} catch ( ClassNotFoundException except ) {
System.err.println( "Could not locate output
format class " + clsName );
}
}
}
}
} catch ( IOException except ) {
System.err.println( "Error loading " + PropertiesResource + ": " +
except.toString() );
}
}
}
1.1 xml-xalan/java/src/serialize/SerializerHandler.java
Index: SerializerHandler.java
===================================================================
package serialize;
/**
* Interface that supplements [EMAIL PROTECTED] org.xml.sax.DocumentHandler}
and
* [EMAIL PROTECTED] org.xml.sax.ContentHandler} with additional methods
suitable
* for serialization. This interface is required only for XML and
* HTML serializers.
*
* @version Alpha
* @author <a href="mailto:[EMAIL PROTECTED]">Assaf Arkin</a>
*/
public interface SerializerHandler
{
/**
* Starts an un-escaping section. All characters printed within an
* un-escaping section are printed as is, without escaping special
* characters into entity references. Only XML and HTML serializers
* need to support this method.
* <p>
* The contents of the un-escaping section will be delivered through
* the regular <tt>characters</tt> event.
*/
public void startNonEscaping();
/**
* Ends an un-escaping section.
*
* @see #startNonEscaping
*/
public void endNonEscaping();
/**
* Starts a whitespace preserving section. All characters printed
* within a preserving section are printed without indentation and
* without consolidating multiple spaces. This is equivalent to
* the <tt>xml:space="preserve"</tt> attribute. Only XML
* and HTML serializers need to support this method.
* <p>
* The contents of the whitespace preserving section will be delivered
* through the regular <tt>characters</tt> event.
*/
public void startPreserving();
/**
* Ends a whitespace preserving section.
*
* @see #startPreserving
*/
public void endPreserving();
}
1.1 xml-xalan/java/src/serialize/package.html
Index: package.html
===================================================================
<!-- CVS $Revision: 1.1 $ $Date: 2000/06/20 16:29:50 $ -->
<html>
<title>Interfaces for SAX and DOM serializers.</title>
<body>
<p>Defines an interface for SAX and DOM serializers, a serializer
factory and its configuration, the output format properties,
and related interfaces.<p>
<dl>
<dt><b>Version: </b></dt><dd>Alpha $Revision: 1.1 $ $Date: 2000/06/20
16:29:50 $</dd>
<dt><b>Author: </b></dt><dd><a href="mailto:[EMAIL PROTECTED]">Assaf
Arkin</a></dd>
<dt><b>Goals: </b></dt><dd>
<ul>
<li>Define an interface for serializers that will allow an
application
to use any implementation.</li>
<li>Support SAX 1, SAX 2, DOM Level 1, DOM Level 2
serialization</li>
<li>Allow implementations to extend the interfaces and provide
additional
functionality, and support implementations for any output
method.</li>
<li>Provide a factory for the default output methods (XML, HTML,
Text).</li>
</ul>
</dd>
</dl>
<h3>The Serializer Interfaces</h3>
<p>[EMAIL PROTECTED] serialize.Serializer} defines the interface
supported by
a serializer. A serializer implements a mechanism for producing output
from
a series of SAX events or a DOM document, in a given format (aka the
output
method). A serializer can be constructed directly, or obtained from
some
factory, it may implement the base functionality or provide additional
functionality suitable for the given output method (e.g. indentation in
XML, page control in PDF, etc).</p>
<p>A serializer is not thread safe and may not be used concurrently,
however,
a serializer may be recyclable and used to serialize any number of
documents
with the same output method.</p>
<p>Before serializing a document, the serializer must be set with the
output
stream or writer, and optionally with an [EMAIL PROTECTED]
serialize.OutputFormat}
specifying the output properties. Serializer implementations may
support
additional methods to control the way in which documents are
serialized,
or extend [EMAIL PROTECTED] serialize.OutputFormat} and offer
additional
output properties.</p>
<p>[EMAIL PROTECTED] serialize.Serializer} and [EMAIL PROTECTED]
serialize.OutputFormat}
provides the minimum functionality that all serializers must support
and that an application may depend on, and are based on the XSLT 1.0
specification.</p>
<p>For the purpose of serializing, a handle to the serializer is obtained
that can be either a SAX 1 <tt>DocumentHandler</tt>, a SAX 2
<tt>ContentHandler</tt>
or a DOM Level 1/2 [EMAIL PROTECTED] serialize.DOMSerializer}. The
application
should obtain and use only one handle at any given time and may not
reuse
the handle to serialize multiple documents. It is illegal for the
application
to call two different handle returning methods without resetting the
serializer,
or two use the same handle after resetting the serializer.</p>
<p>[EMAIL PROTECTED] serialize.SerializerFactory} provides a means of
obtaining
the default serializers available from a given implementation. At the
minimum
an implementation should support XML, HTML and Text serializers. When
additional
serializers are available, the application may obtain them through the
[EMAIL PROTECTED]
serialize.SerializerFactory} or construct them directly.</p>
<p>Non-escaping and whitespace preserving output control is offered for
XML, HTML and similar output methods, but it is not mandatory that a
serializer support these output control methods. Non-escaping and
whitespace
preserving can be set globally through [EMAIL PROTECTED]
serialize.OutputFormat},
or directly when serializing SAX events through [EMAIL PROTECTED]
serialize.SerializerHandler}.
Serializers are not required to implement the [EMAIL PROTECTED]
serialize.SerializerHandler}
interface.</p>
<h3>Usage Examples</h3>
<p>Serialize a DOM document as XML:</p>
<pre>
void printXML( Document doc, OutputStream stream, String encoding )
{
OutputFormat format;
Serializer ser;
// Obtain a suitable output format for the XML method and
// set the encoding.
format = SerializerFactory.getOutputFormat( Method.XML );
format.setEncoding( encoding );
// Obtain a suitable serializer for the XML method and
// set the output stream.
ser = SerializerFactory.getSerializer( format );
ser.setOutputStream( stream );
// Use DOMSerializer to serialize the document
ser.asDOMSerializer().serialize( doc );
}
</pre>
<p>Serialize an empty HTML document using SAX events, reuse the
serializer:</p>
<pre>
Serializer ser;
// Obtain an HTML serializer once, use it multiple times.
ser = SerializerFactory.getSerializer( Method.HTML );
printEmptyHTML( ser, System.out );
printEmptyHTML( ser, System.err );
. . .
void printEmptyHTML( Serializer ser, OutputStream os )
{
ser.setOutputStream( os );
ser.asDocumentHandler().startDocument();
ser.asDocumentHandler().startElement( "html", new AttributeListImpl() );
ser.asDocumentHandler().endElement( "html" );
ser.asDocumentHandler().endDocument();
ser.reset();
}
</pre>
<h3>The Properties File</h3>
<p>An implementation will include a serializer properties file called
<tt>serializer.properties</tt> located in the <tt>serialize</tt>
package. The properties file lists all the default serializers
supported
by that implementation. Serializers that are not listed in the
properties
file may be constructed directly by the application.</p>
<p>The properties file contains a property <tt>serialize.methods</tt>
listing all the output methods supported by the implementation (comma
separated list). For each method a property <tt>serialize.[method]</tt>
names the class of the [EMAIL PROTECTED] serialize.Serializer}
implementation.
The optional property <tt>serialize.format.[method]</tt> names the
class of a suitable [EMAIL PROTECTED] serialize.OutputFormat}
implementation.</p>
</body>
</html>
1.1 xml-xalan/java/src/serialize/serializer.properties
Index: serializer.properties
===================================================================
#
# $Revision: 1.1 $ $Date: 2000/06/20 16:29:50 $
#
# Note: This properties file is provided for illustrative purposes
# only and is not part of the interface definition.
# This properties file is located in the implementation JAR
# and different implementations will specify different
# implementation classes and output methods.
#
#
# Lis the methods supported by this implementation
#
serialize.methods=xml,html,xhtml,text,wml:wml
#
# Use the Xerces serializer implementations for the default methods
#
serialize.xml=org.apache.xml.serialize.XMLSerializer
serialize.html=org.apache.xml.serialize.HTMLSerializer
serialize.xhtml=org.apache.xml.serialize.XHTMLSerializer
serialize.text=org.apache.xml.serialize.TextSerializer
serialize.wml:wml=org.apache.xml.serialize.WMLSerializer
#
# Use the helper output formats for the default methods
#
serialize.format.xml=serialize.format.XMLOutputFormat
serialize.format.html=serialize.format.HTMLOutputFormat
serialize.format.xhtml=serialize.format.XHTMLOutputFormat
serialize.format.text=serialize.format.TextOutputFormat
1.1
xml-xalan/java/src/serialize/helpers/HTMLOutputFormat.java
Index: HTMLOutputFormat.java
===================================================================
package serialize.helpers;
import serialize.OutputFormat;
import serialize.Method;
/**
* Output format for HTML documents.
* <p>
* The output format affects the manner in which a document is
* serialized. The output format determines the output method,
* encoding, indentation, document type, and various other properties
* that affect the manner in which a document is serialized.
*
* @version Alpha
* @author <a href="mailto:[EMAIL PROTECTED]">Assaf Arkin</a>
*/
public class HTMLOutputFormat
extends OutputFormat
{
public HTMLOutputFormat()
{
setMethod( Method.HTML );
setMediaType( "text/html" );
setOmitXMLDeclaration( true );
setPreserveSpace( false );
setDoctypePublicId( "-//W3C//DTD HTML 4.0//EN" );
setDoctypeSystemId(
"http://www.w3.org/TR/WD-html-in-xml/DTD/xhtml1-strict.dtd"; );
}
public HTMLOutputFormat( String encoding )
{
this();
setEncoding( encoding );
}
public HTMLOutputFormat( boolean indenting )
{
this();
setIndenting( indenting );
}
}
1.1
xml-xalan/java/src/serialize/helpers/TextOutputFormat.java
Index: TextOutputFormat.java
===================================================================
package serialize.helpers;
import serialize.OutputFormat;
import serialize.Method;
/**
* Output format for text documents.
* <p>
* The output format affects the manner in which a document is
* serialized. The output format determines the output method,
* encoding, indentation, document type, and various other properties
* that affect the manner in which a document is serialized.
*
* @version Alpha
* @author <a href="mailto:[EMAIL PROTECTED]">Assaf Arkin</a>
*/
public class TextOutputFormat
extends OutputFormat
{
public TextOutputFormat()
{
setMethod( Method.Text );
setMediaType( "text/plain" );
setPreserveSpace( true );
}
public TextOutputFormat( String encoding )
{
this();
setEncoding( encoding );
}
public TextOutputFormat( boolean indenting )
{
this();
setIndenting( indenting );
setPreserveSpace( false );
}
}
1.1
xml-xalan/java/src/serialize/helpers/XHTMLOutputFormat.java
Index: XHTMLOutputFormat.java
===================================================================
package serialize.helpers;
import serialize.OutputFormat;
import serialize.Method;
/**
* Output format for XHTML documents.
* <p>
* The output format affects the manner in which a document is
* serialized. The output format determines the output method,
* encoding, indentation, document type, and various other properties
* that affect the manner in which a document is serialized.
*
* @version Alpha
* @author <a href="mailto:[EMAIL PROTECTED]">Assaf Arkin</a>
*/
public class XHTMLOutputFormat
extends OutputFormat
{
public XHTMLOutputFormat()
{
setMethod( Method.XHTML );
setMediaType( "text/html" );
setOmitXMLDeclaration( true );
setPreserveSpace( false );
setDoctypePublicId( "-//W3C//DTD XHTML 1.0 Strict//EN" );
setDoctypeSystemId(
"http://www.w3.org/TR/WD-html-in-xml/DTD/xhtml1-strict.dtd"; );
}
public XHTMLOutputFormat( String encoding )
{
this();
setEncoding( encoding );
}
public XHTMLOutputFormat( boolean indenting )
{
this();
setIndenting( indenting );
}
}
1.1 xml-xalan/java/src/serialize/helpers/XMLOutputFormat.java
Index: XMLOutputFormat.java
===================================================================
package serialize.helpers;
import serialize.OutputFormat;
import serialize.Method;
/**
* Output format for XML documents.
* <p>
* The output format affects the manner in which a document is
* serialized. The output format determines the output method,
* encoding, indentation, document type, and various other properties
* that affect the manner in which a document is serialized.
*
* @version Alpha
* @author <a href="mailto:[EMAIL PROTECTED]">Assaf Arkin</a>
*/
public class XMLOutputFormat
extends OutputFormat
{
public XMLOutputFormat()
{
setMethod( Method.XML );
setMediaType( "text/xml" );
setPreserveSpace( true );
}
public XMLOutputFormat( String encoding )
{
this();
setEncoding( encoding );
}
public XMLOutputFormat( boolean indenting )
{
this();
setIndenting( indenting );
setPreserveSpace( false );
}
}
