org.enhydra.xml.io
Class OutputOptions

java.lang.Object
  |
  +--org.enhydra.xml.io.OutputOptions

public final class OutputOptions
extends Object

Object that specifies how a HTML or XML file will be formatted.

Use of certain options may be required when using certain document types in order to provide compatiblity for buggy or less capable browsers. Make sure to read the option descriptions and do your own testing to make sure these options are really necessary for use in your application...

HTML
oo.setUseAposEntity(false)
oo.setOmitAttributeCharEntityRefs(true)
oo.setOmitDocType(false) (html dom doesn't preserve doctype, so use this and two options below...)
oo.setPublicId("-//W3C//DTD HTML 4.01//EN")
oo.setSystemId("http://www.w3.org/TR/html401/strict.dtd")
XHTML
oo.setEnableXHTMLCompatibility(true)
oo.setUseAposEntity(false)
XML
Overriding the defaults of most of these options is not recommended for pure XML and may cause output that doesn't strictly follow the XML spec and/or, in the worst case, invalid XML.

Note: the pretty-printing options are not yet implemented by the formatters.


Inner Class Summary
static class OutputOptions.Format
          Desired output format enumerated type.
 
Field Summary
static OutputOptions.Format FORMAT_AUTO
          Constant indicating format should be determined automatically from examining the document object.
static OutputOptions.Format FORMAT_HTML
          Constant indicating HTML format.
static OutputOptions.Format FORMAT_XML
          Constant indicating XML format.
 
Constructor Summary
OutputOptions()
          Construct with default values.
OutputOptions(OutputOptions src)
          Copy constructor.
 
Method Summary
 void createCodeGenerator(String varName, boolean makeReadOnly, JavaCode code)
          Generate code to create an object with the same attributes as this object.
 boolean getDropHtmlSpanIds()
          Get the drop HTML SPAN element ids flag.
 boolean getEnableXHTMLCompatibility()
          Get enable-xhtml-compatibility flag.
 String getEncoding()
          Get the encoding.
 OutputOptions.Format getFormat()
          Get the output format for the file.
 int getIndentSize()
          Get indentation size.
 String getJavaEncoding()
          Deprecated. Use getEncoding() or getMIMEEncoding().
 String getMIMEEncoding()
          Get the MIME encoding.
 String getMIMEType()
          Get the MIME for an output routine to use.
 boolean getOmitAttributeCharEntityRefs()
          Get value of flag that enables or disables the use of character entity references in attribute values.
 boolean getOmitDocType()
          Get flag indicating if the DOCTYPE should be omitted.
 boolean getOmitEncoding()
          Get flag indicating if encoding should be omitted from the XML header.
 boolean getOmitXMLHeader()
          Get flag indicating if the XML header should be omitted.
 boolean getPreserveSpace()
          Get the default space-preservation flag.
 boolean getPrettyPrinting()
          Get pretty-printing flag.
 String getPublicId()
          Get the public id to be used in the DOCUMENT.
 String getSystemId()
          Get the system id to be used in the DOCUMENT.
 Set getURLRewriteAttributes()
          Get the URL attribute names to apply session rewriting.
 URLRewriter getURLRewriter()
          Get the URLRewriter.
 boolean getUseAposEntity()
          Get use-apos-entity flag
 boolean getUseHTML4Entities()
          Get the flag telling whether to use named entities from HTML 4.0 or not.
 String getXmlEncoding()
          Deprecated. Use getMIMEEncoding().
 void markReadOnly()
          Mark the object as read-only.
 void setDropHtmlSpanIds(boolean drop)
          Set the drop HTML <span> element id's flag.
 void setEnableXHTMLCompatibility(boolean enable)
          Enable or disable XMLC XHTML compatibility workarounds
 void setEncoding(String encoding)
          Set the encoding.
 void setFormat(OutputOptions.Format format)
          Set the output format for the file.
 void setIndentSize(int size)
          Set indentation size.
 void setJavaEncoding(String newJavaEncoding)
          Deprecated. Use setEncoding().
 void setMIMEType(String mimeType)
          Set the MIME for an output routine to use.
 void setOmitAttributeCharEntityRefs(boolean omit)
          Set value of flag that enables or disables the use of character entity references in attribute values.
 void setOmitDocType(boolean omit)
          Set flag indicating if the DOCTYPE should be omitted.
 void setOmitEncoding(boolean omit)
          Set flag indicating if encoding should be omitted from the XML header.
 void setOmitXMLHeader(boolean omit)
          Set flag indicating if the XML header should be omitted.
 void setPreserveSpace(boolean preserve)
          Set the default space-preservation flag.
 void setPrettyPrinting(boolean enable)
          Enable or disable pretty-printing.
 void setPublicId(String publicId)
          Set the public id to use in the DOCUMENT.
 void setSystemId(String systemId)
          Set the system id to use in the DOCUMENT.
 void setURLRewriteAttributes(Set attributes)
          Set the attribute names to apply URLRewriting to (assuming URLRewriting is being used instead of session cookies).
 void setURLRewriteAttributes(String[] attributes)
           
 void setURLRewriter(URLRewriter urlRewriter)
          Set the URLRewriter that all URL attributes will be passed through.
 void setUseAposEntity(boolean enable)
          Enable or disable the use of &apos; for escaping single quotes.
 void setUseHTML4Entities(boolean useHTML4Entities)
          Set the flag telling whether to use named entities from HTML 4.0 or not.
 void setXmlEncoding(String newXmlEncoding)
          Deprecated. Use setEncoding().
 String toString()
          Convert to a string for debugging.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

FORMAT_AUTO

public static final OutputOptions.Format FORMAT_AUTO
Constant indicating format should be determined automatically from examining the document object.

FORMAT_HTML

public static final OutputOptions.Format FORMAT_HTML
Constant indicating HTML format.

FORMAT_XML

public static final OutputOptions.Format FORMAT_XML
Constant indicating XML format.
Constructor Detail

OutputOptions

public OutputOptions()
Construct with default values.

OutputOptions

public OutputOptions(OutputOptions src)
Copy constructor. The read-only property is not copied, the resulting object may be modified.
Method Detail

markReadOnly

public void markReadOnly()
Mark the object as read-only. Once made read-only, it may never be modified. If a modification is required, create a new object using the copy-constructor.
See Also:
OutputOptions(OutputOptions)

setFormat

public void setFormat(OutputOptions.Format format)
Set the output format for the file. Specifying an incorrect format will result in an invalid document. Default is FORMAT_AUTO, which determines the format from the DOM.
Parameters:
format - one of FORMAT_AUTO, FORMAT_HTML, FORMAT_XML

getFormat

public OutputOptions.Format getFormat()
Get the output format for the file.
Returns:
the output format

getEncoding

public String getEncoding()
Get the encoding.
Returns:
The encoding or null if not specified.

setEncoding

public void setEncoding(String encoding)
Set the encoding.
Parameters:
encoding - The new encoding, or null to clear.

getMIMEEncoding

public String getMIMEEncoding()
Get the MIME encoding.
Returns:
The MIME-preferred name for the encoding, null if no encoding is specified.

getUseAposEntity

public boolean getUseAposEntity()
Get use-apos-entity flag
Returns:
true if enabled, false if disabled. The default is enabled.

setUseAposEntity

public void setUseAposEntity(boolean enable)
Enable or disable the use of &apos; for escaping single quotes.

&apos; was added in to the XML spec and doesn't exist in the HTML spec. As such, some browsers (some versions of IE) handle this poorly in attributes (think JavaScript). It is recommended that you disable the use of &apos; entity if you run into problems. This option will, eventually, be unnecessary once more browsers provide support for the &apos; entity.

Parameters:
enable - true to enable, false to disable.

getEnableXHTMLCompatibility

public boolean getEnableXHTMLCompatibility()
Get enable-xhtml-compatibility flag.
Returns:
true if enabled, false if disabled. The default is disabled.
Since:
2.2

setEnableXHTMLCompatibility

public void setEnableXHTMLCompatibility(boolean enable)
Enable or disable XMLC XHTML compatibility workarounds

Many browsers still in heavy use don't fully support XHTML. In order to make the transition to XHTML, XMLC must allow for reasonable workarounds to known compatibility issues in these less capable browsers. Setting this flag to 'true' tells XMLC and, specifically, the XMLFormater to do anything it needs to maintain compatibility with older browsers. Currently, the following XHTML compatibility issues are accounted for:

This allows browsers, using an HTML parser, to render XHTML properly. It also allows IE 5.5 and IE6 to evaluate javascript properly, since said browsers fail to understand the minimized <script ... />.

Note that this method name is intentionally generic to allow for the application of other arbitrary workarounds without requiring new methods to be added to OutputOptions.

Parameters:
enable - true to enable, false to disable
Since:
2.2

getPrettyPrinting

public boolean getPrettyPrinting()
Get pretty-printing flag.
Returns:
true if enabled, false if disabled. The default is disabled.

setPrettyPrinting

public void setPrettyPrinting(boolean enable)
Enable or disable pretty-printing.
Parameters:
enable - true to enable, false to disable

getIndentSize

public int getIndentSize()
Get indentation size.
Returns:
Number of characters to indent at each level. The default is 4.

setIndentSize

public void setIndentSize(int size)
Set indentation size. Only used if pretty printing is enabled.
Parameters:
size - Number of characters to indent at each level.

getPreserveSpace

public boolean getPreserveSpace()
Get the default space-preservation flag.
Returns:
true if preserving space where not otherwise specified by the document, false otherwise. The default is true.

setPreserveSpace

public void setPreserveSpace(boolean preserve)
Set the default space-preservation flag.
Parameters:
perserve - true if preserving space where not otherwise specified by the document

getOmitXMLHeader

public boolean getOmitXMLHeader()
Get flag indicating if the XML header should be omitted.
Returns:
true if omitted, false if admitted. The default is admitted.

setOmitXMLHeader

public void setOmitXMLHeader(boolean omit)
Set flag indicating if the XML header should be omitted.
Parameters:
omit - true to omit, false to admit

getOmitDocType

public boolean getOmitDocType()
Get flag indicating if the DOCTYPE should be omitted.
Returns:
true if omitted, false if admitted. The default is admitted.

setOmitDocType

public void setOmitDocType(boolean omit)
Set flag indicating if the DOCTYPE should be omitted.
Parameters:
omit - true to omit, false to admit

getOmitEncoding

public boolean getOmitEncoding()
Get flag indicating if encoding should be omitted from the XML header.
Returns:
true if omitted, false if admitted. The default is admitted.

setOmitEncoding

public void setOmitEncoding(boolean omit)
Set flag indicating if encoding should be omitted from the XML header. This is provided as a hack for WML. Several devices need ASCII encoding but can't handle the header.
Parameters:
omit - true to omit, false to admit

getDropHtmlSpanIds

public boolean getDropHtmlSpanIds()
Get the drop HTML SPAN element ids flag.
Returns:
true if dropped, false if kept. The default is kept.

setDropHtmlSpanIds

public void setDropHtmlSpanIds(boolean drop)
Set the drop HTML <span> element id's flag.

MS Internet Explorer 4.0 gets very confused about keep-alive connections if HTML <span> tags have "id" attributes. Until we find another workaround, this removes "id"'s from <span> tags.

Unless you have to support IE4 users and require keep-alive connections to your application, this option is not recommended

Parameters:
drop - true to drop, false to keep

getOmitAttributeCharEntityRefs

public boolean getOmitAttributeCharEntityRefs()
Get value of flag that enables or disables the use of character entity references in attribute values.
Returns:
true if omitted, false if admitted. The default is admitted.

setOmitAttributeCharEntityRefs

public void setOmitAttributeCharEntityRefs(boolean omit)
Set value of flag that enables or disables the use of character entity references in attribute values.

By default, all standard character entity references are used in attribute values. While this is legal in HTML and XML, some HTML clients may not handle this well (for instance, one of the major browsers didn't correctly expand the entity references in PARAM values passed to applets). If this flag is set, then standard character entity references (such as &amp;) will not be substituted. Numeric character entity references will still be substituted for quotes and for characters that can't be represented in the encoding.

This option is not recommended for XML and should be avoided in any case unless this issue becomes a problem in your application.

Parameters:
omit - true to omit, false to admit
See Also:
getOmitAttributeCharEntityRefs()

setURLRewriter

public void setURLRewriter(URLRewriter urlRewriter)
Set the URLRewriter that all URL attributes will be passed through. Documents must implement DocumentInfo for the URL rewriter to work.
Note: URL rewriting curret only works when the XMLC document object is passed to the formatter. Passing the contained document or any other node results in no URL rewriting.
Parameters:
urlRewriter - The URLRewriter object, or null to disassociate any URL rewriter.
See Also:
DocumentInfo

getURLRewriter

public URLRewriter getURLRewriter()
Get the URLRewriter.
Returns:
The URLRewriter object.
See Also:
DocumentInfo

getURLRewriteAttributes

public Set getURLRewriteAttributes()
Get the URL attribute names to apply session rewriting. If null, defaults defined per respective XMLCDomFactory are used.
Returns:
the set of attribute name strings

setURLRewriteAttributes

public void setURLRewriteAttributes(Set attributes)
Set the attribute names to apply URLRewriting to (assuming URLRewriting is being used instead of session cookies). If set, this overrides the defaults provided by each respective XMLCDomFactory implementation.
Parameters:
attributes - a set of attribute name strings to rewrite, null to use defaults defined in each respective XMLCDomFactory implementation.

setURLRewriteAttributes

public void setURLRewriteAttributes(String[] attributes)
Parameters:
attributes -  
See Also:
setURLRewriteAttributes(Set)

getPublicId

public String getPublicId()
Get the public id to be used in the DOCUMENT.
Returns:
the public id

setPublicId

public void setPublicId(String publicId)
Set the public id to use in the DOCUMENT. This overrides the default value determined from the DocumentType.
Returns:
the public id

getSystemId

public String getSystemId()
Get the system id to be used in the DOCUMENT.
Returns:
the system id

setSystemId

public void setSystemId(String systemId)
Set the system id to use in the DOCUMENT. This overrides the default value determined from the DocumentType.
Returns:
the system id

getMIMEType

public String getMIMEType()
Get the MIME for an output routine to use.
Returns:
The overriding MIME type, null if one was not specified.

setMIMEType

public void setMIMEType(String mimeType)
Set the MIME for an output routine to use. This is stored in this object for use by output routines, DOMFormatters don't actually use it. It is normally used to override the default MIME type that would be stored in the XMLObject.
Parameters:
mimeType - the mime-type to use

createCodeGenerator

public void createCodeGenerator(String varName,
                                boolean makeReadOnly,
                                JavaCode code)
Generate code to create an object with the same attributes as this object.

The following attributes are not generated in the new code:

Parameters:
varName - Variable or field name of variable to store the object in. It must already be declared.
makeReadOnly - Should the created object be made read-only?
code - Add generated code to this object.

toString

public String toString()
Convert to a string for debugging.
Overrides:
toString in class Object

getJavaEncoding

public String getJavaEncoding()
Deprecated. Use getEncoding() or getMIMEEncoding().

Get the encoding.
See Also:
getEncoding(), getMIMEEncoding()

setJavaEncoding

public void setJavaEncoding(String newJavaEncoding)
Deprecated. Use setEncoding().

Set the encoding.
See Also:
setEncoding(java.lang.String)

getXmlEncoding

public String getXmlEncoding()
Deprecated. Use getMIMEEncoding().

Get the MIME-preferred encoding.
See Also:
getMIMEEncoding()

setXmlEncoding

public void setXmlEncoding(String newXmlEncoding)
Deprecated. Use setEncoding().

Set the encoding.

getUseHTML4Entities

public boolean getUseHTML4Entities()
Get the flag telling whether to use named entities from HTML 4.0 or not.
Returns:
true if enabled, false if disabled. The default is disabled.

setUseHTML4Entities

public void setUseHTML4Entities(boolean useHTML4Entities)
Set the flag telling whether to use named entities from HTML 4.0 or not.
Parameters:
useHTML4Entities - true to enable, false to disable


Copyright © 1999-2002 enhydra.org (Mark Diekhans, David Li, Richard Kunze). All Rights reserved.