You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by sb...@locus.apache.org on 2000/06/20 18:29:56 UTC
cvs commit: xml-xalan/java/src/serialize/helpers HTMLOutputFormat.java TextOutputFormat.java XHTMLOutputFormat.java XMLOutputFormat.java
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/Lotus@lotus.com">Scott Boag</a>
* @author <a href="mailto:arkin@exoffice.com">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:arkin@exoffice.com">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:arkin@exoffice.com">Assaf Arkin</a>
* <a href="mailto:visco@exoffice.com">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 {@link
* Method} for a list of the default methods. Other methods should
* be of the format <tt>namespace:local</tt>. The default is
* {@link Method#XML}.
*
* @return The specified output method
*/
public String getMethod()
{
return _method;
}
/**
* Sets the method for this output format. See {@link 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:arkin@exoffice.com">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 {@link 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 {@link #asDocumentHandler}
* <li>To serialize SAX 2 events call {@link #asContentHandler}
* <li>To serialize a DOM document call {@link #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 {@link #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:arkin@exoffice.com">Assaf Arkin</a>
* @author <a href="mailto:Scott_Boag/CAM/Lotus@lotus.com">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 {@link 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 {@link 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 {@link DocumentHandler} interface into this serializer.
* If the serializer does not support the {@link DocumentHandler}
* interface, it should return null.
*
* @return A {@link 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 {@link ContentHandler} interface into this serializer.
* If the serializer does not support the {@link ContentHandler}
* interface, it should return null.
*
* @return A {@link 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 {@link DOMSerializer} interface into this serializer.
* If the serializer does not support the {@link DOMSerializer}
* interface, it should return null.
*
* @return A {@link 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:arkin@exoffice.com">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
* {@link 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
* {@link 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 {@link 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 {@link org.xml.sax.DocumentHandler} and
* {@link 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:arkin@exoffice.com">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:arkin@exoffice.com">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>{@link 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 {@link serialize.OutputFormat}
specifying the output properties. Serializer implementations may support
additional methods to control the way in which documents are serialized,
or extend {@link serialize.OutputFormat} and offer additional
output properties.</p>
<p>{@link serialize.Serializer} and {@link 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 {@link 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>{@link 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 {@link
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 {@link serialize.OutputFormat},
or directly when serializing SAX events through {@link serialize.SerializerHandler}.
Serializers are not required to implement the {@link 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 {@link serialize.Serializer} implementation.
The optional property <tt>serialize.format.[method]</tt> names the
class of a suitable {@link 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:arkin@exoffice.com">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:arkin@exoffice.com">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:arkin@exoffice.com">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:arkin@exoffice.com">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 );
}
}