DocumentWriter (XMLmind XML Editor Java[tm] API)

java.lang.Object
- com.xmlmind.xml.save.DocumentWriter

Direct Known Subclasses:

DocumentIndenter, DocumentWriterBase
```
public class DocumentWriter
extends Object
```
Low-level document writer. Cannot generate indented output.

See Also:

DocumentIndenter, SaveDocument

Field Summary

Fields
Modifier and Type	Field and Description
`protected ElementMatcher`	`cdataSections`
`protected DocumentType`	`documentType`
`protected DiagnosticUtil.DuplicateIDFilter`	`duplicateIDFilter`
`protected boolean`	`favorInteroperability`
`protected boolean`	`filterDuplicateIDs`
`protected Writer`	`out`
`protected Boolean`	`predeclarePrefixPrefs`
`protected boolean`	`preserveInclusions`
`protected QNameHelper`	`qNameHelper`
`protected com.xmlmind.xml.save.TextHelper`	`textHelper`

Constructor Summary

Constructors
Constructor and Description

DocumentWriter(Writer out)
Constructs a writer writing XML to specified output.

Constructors
Constructor and Description
`DocumentWriter(Writer out)` Constructs a writer writing XML to specified output.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`addXMLBase(Document doc, boolean addAttribute)` Adds `xml:base` properties or attributes to all included elements found in specified document.
`protected void`	`beginWrite(Document document)`
`protected void`	`beginWrite(Element element)`
`protected static void`	`checkComment(Comment comment)`
`protected static void`	`checkProcessingInstruction(ProcessingInstruction pi)`
`protected void`	`endWrite(Document document)`
`protected void`	`endWrite(Element element)`
`void`	`flush()` Flush the underlying `Writer`.
`XPath[]`	`getCdataSectionElements()` Returns the XPath of elements which are to be saved as CDATA sections.
`CharEntities`	`getCharEntities()` Returns the map specified using `setCharEntities(com.xmlmind.xml.load.CharEntities)`.
`CharRange[]`	`getCharsSavedAsEntityRefs()` Returns which characters, even if they are supported by the encoding, are always saved as entity references.
`DocumentType`	`getDocumentType()` Returns the document type of the document to be saved.
`String`	`getEncoding()` Returns the encoding being used for the save file.
`boolean`	`getFavorInteroperability()` Returns `true` if interoperability with HTML/SGML should be favored as recommended in the W3C XML specification.
`boolean`	`getFilterDuplicateIDs()` Returns `true` if this writer must mangle false duplicate IDs resulting from the use of included elements.
`Boolean`	`getPredeclarePrefixPreferences()` Returns a boolean indicating whether all the namespace prefixes specified using `setPrefixPreferences(com.xmlmind.xml.name.PrefixEntry[])` are pre-declared on the root element of the saved document.
`PrefixEntry[]`	`getPrefixPreferences()` Returns the prefix/namespace associations to be preferably used by this writer for saved files.
`boolean`	`getPreserveInclusions()` Returns `false` if inclusions (references to external entities, XIncludes, etc) are to be ```expanded'' in the XML files created by this writer.
`Writer`	`getWriter()` Returns the underlying `Writer`.
`protected boolean`	`hasEmptyContentType(Element element)`
`protected boolean`	`isEmptyElement(Element element)`
`protected void`	`popElement()`
`protected boolean`	`predeclarePrefixPrefs()`
`protected void`	`pushElement(Element element)`
`void`	`setCdataSectionElements(XPath[] cdataSectionElements)` Specifies the XPath of elements which are to be saved as CDATA sections.
`void`	`setCharEntities(CharEntities map)` Specifies a map defining character entities.
`void`	`setCharsSavedAsEntityRefs(CharRange[] ranges)` Specifies which characters, even if they are supported by the encoding, are always saved as entity references.
`void`	`setDocumentType(DocumentType documentType)` Specifies the document type of the document to be saved.
`void`	`setEncoding(String name)` Specifies the encoding being used for the save file.
`void`	`setFavorInteroperability(boolean favor)` Specifies whether interoperability with HTML/SGML should be favored as recommended in the W3C XML specification.
`void`	`setFilterDuplicateIDs(boolean filter)` Allows to mangle false duplicate IDs resulting from the use of included elements.
`void`	`setPredeclarePrefixPreferences(Boolean predeclare)` Specifies whether all the namespace prefixes specified using `setPrefixPreferences(com.xmlmind.xml.name.PrefixEntry[])` are pre-declared on the root element of the saved document.
`void`	`setPrefixPreferences(PrefixEntry[] prefixPreferences)` Specifies the prefix/namespace associations to be preferably used by this writer.
`void`	`setPreserveInclusions(boolean preserve)` Specify `false` if inclusions (references to external entities, XIncludes, etc) are to be ``expanded'' in the XML files created by this writer.
`protected static String`	`shorten(String text)`
`void`	`write(Document document)` Save specified document.
`void`	`write(Element element)` Save specified element as a document.
`protected void`	`writeAttribute(String tag, String value)`
`protected void`	`writeAttributes(Element element)`
`protected void`	`writeCDATA(Text text, Element element)`
`protected void`	`writeComment(Comment comment)`
`protected void`	`writeDocumentTypeDeclaration(DocumentTypeDeclaration dtd)`
`protected void`	`writeElement(Element element)`
`protected void`	`writeElementProperties(Element element)` Write certain element properties in the form of processing-instructions.
`protected void`	`writeEmptyEndTag(String tag, Element element)`
`protected void`	`writeEndTag(String tag, Element element)`
`protected void`	`writeEntityRef(EntityRef entityRef)`
`protected void`	`writeFrame()`
`protected void`	`writeInclusion(Inclusion inclusion, Node firstIncludedNode, Node lastIncludedNode)`
`protected void`	`writeProcessingInstruction(ProcessingInstruction pi)`
`protected void`	`writeStartTag(String tag, Element element)`
`protected void`	`writeText(Text text)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - out
```
protected Writer out
```
  - qNameHelper
```
protected QNameHelper qNameHelper
```
  - textHelper
```
protected com.xmlmind.xml.save.TextHelper textHelper
```
  - preserveInclusions
```
protected boolean preserveInclusions
```
  - filterDuplicateIDs
```
protected boolean filterDuplicateIDs
```
  - duplicateIDFilter
```
protected DiagnosticUtil.DuplicateIDFilter duplicateIDFilter
```
  - cdataSections
```
protected ElementMatcher cdataSections
```
  - documentType
```
protected DocumentType documentType
```
  - favorInteroperability
```
protected boolean favorInteroperability
```
  - predeclarePrefixPrefs
```
protected Boolean predeclarePrefixPrefs
```
- Constructor Detail
  - DocumentWriter
```
public DocumentWriter(Writer out)
```
    Constructs a writer writing XML to specified output.
- Method Detail
  - getWriter
```
public Writer getWriter()
```
    Returns the underlying Writer.
    
    See Also:
    
    flush()
  - setEncoding
```
public void setEncoding(String name)
                 throws UnsupportedEncodingException
```
    Specifies the encoding being used for the save file.
    Default value is SaveOptions.FALLBACK_ENCODING.
    
    Throws:
    
    UnsupportedEncodingException
  - getEncoding
```
public String getEncoding()
```
    Returns the encoding being used for the save file.
  - setCharEntities
```
public void setCharEntities(CharEntities map)
```
    Specifies a map defining character entities.
    Without such map, characters not supported by the encoding cannot be saved as references to character entities.
    If, for example, a map has been specified and this map defines the Euro sign as "€" and the encoding does not support the Euro sign (e.g. US-ASCII), then the Euro sign will be saved as "€". In all other cases, the Euro sign will be saved as "€".
    Initally, this map is not specified (that is, is null).
    
    See Also:
    
    getCharEntities()
  - getCharEntities
```
public CharEntities getCharEntities()
```
    Returns the map specified using setCharEntities(com.xmlmind.xml.load.CharEntities).
  - setCharsSavedAsEntityRefs
```
public void setCharsSavedAsEntityRefs(CharRange[] ranges)
```
    Specifies which characters, even if they are supported by the encoding, are always saved as entity references.
    For example, the Copyright sign is supported by the ISO-8859-1 encoding but you may prefer to see it saved as "©" in the XML file created by this DocumentWriter. In such case, specify a CharRange containing character 169.
    Default: null
  - getCharsSavedAsEntityRefs
```
public CharRange[] getCharsSavedAsEntityRefs()
```
    Returns which characters, even if they are supported by the encoding, are always saved as entity references. Returns null if such characters have not been specified.
  - setPrefixPreferences
```
public void setPrefixPreferences(PrefixEntry[] prefixPreferences)
```
    Specifies the prefix/namespace associations to be preferably used by this writer.
    If these preferences are not specified, this writer will automatically generate prefixes as needed: ns, ns2, ns3, ...
    Default: null.
  - getPrefixPreferences
```
public PrefixEntry[] getPrefixPreferences()
```
    Returns the prefix/namespace associations to be preferably used by this writer for saved files. Returns null if such preferences have not been specified.
  - setPreserveInclusions
```
public void setPreserveInclusions(boolean preserve)
```
    Specify false if inclusions (references to external entities, XIncludes, etc) are to be ``expanded'' in the XML files created by this writer.
    Default: true.
    
    See Also:
    
    getPreserveInclusions()
  - getPreserveInclusions
```
public boolean getPreserveInclusions()
```
    Returns false if inclusions (references to external entities, XIncludes, etc) are to be ```expanded'' in the XML files created by this writer.
  - setFilterDuplicateIDs
```
public void setFilterDuplicateIDs(boolean filter)
```
    Allows to mangle false duplicate IDs resulting from the use of included elements.
    If the document to be saved contains two elements having a "foo" ID and one of them is just an included replica of the other one, then turning this option on will replace ID "foo" by ID "foo.NNN" for the replica.
    Default: true.
    No effect unless inclusions are not preserved.
    
    Parameters:
    
    filter - if true, mangle false duplicate IDs resulting from the use of included elements.
    
    See Also:
    
    setPreserveInclusions(boolean)
  - getFilterDuplicateIDs
```
public boolean getFilterDuplicateIDs()
```
    Returns true if this writer must mangle false duplicate IDs resulting from the use of included elements. Returns false otherwise.
    
    See Also:
    
    setFilterDuplicateIDs(boolean)
  - setCdataSectionElements
```
public void setCdataSectionElements(XPath[] cdataSectionElements)
```
    Specifies the XPath of elements which are to be saved as CDATA sections. Generally these elements only contains text and have xml:space="preserve". An example of such element is XHTML script.
    In order to be saved as CDATA sections (<![CDATA[ ]]>), these elements must only contain text and nothing else (no comments or processing instructions).
    Default: null.
    
    Parameters:
    
    cdataSectionElements - XPath of elements which are to be saved as CDATA sections
    For efficiency reasons, an XPath whose last step does not test an element name is ignored. For example, "foo//*" is ignored.
  - getCdataSectionElements
```
public XPath[] getCdataSectionElements()
```
    Returns the XPath of elements which are to be saved as CDATA sections. Returns null if such elements have not been specified.
  - setDocumentType
```
public void setDocumentType(DocumentType documentType)
```
    Specifies the document type of the document to be saved. May be null.
  - getDocumentType
```
public DocumentType getDocumentType()
```
    Returns the document type of the document to be saved. May return null.
    
    See Also:
    
    setDocumentType(com.xmlmind.xml.validate.DocumentType)
  - setFavorInteroperability
```
public void setFavorInteroperability(boolean favor)
```
    Specifies whether interoperability with HTML/SGML should be favored as recommended in the W3C XML specification.
    Default: false.
    If true, this means that:
    - Empty elements having a non empty content are saved as "<tag></tag>".
    - Empty elements having an empty content are saved as "<tag />" (with a space after the tag).
  - getFavorInteroperability
```
public boolean getFavorInteroperability()
```
    Returns true if interoperability with HTML/SGML should be favored as recommended in the W3C XML specification. Returns false otherwise.
  - setPredeclarePrefixPreferences
```
public void setPredeclarePrefixPreferences(Boolean predeclare)
```
    Specifies whether all the namespace prefixes specified using setPrefixPreferences(com.xmlmind.xml.name.PrefixEntry[]) are pre-declared on the root element of the saved document. May be null which means "automatically determined".
    Default: null.
    
    See Also:
    
    getPredeclarePrefixPreferences()
  - getPredeclarePrefixPreferences
```
public Boolean getPredeclarePrefixPreferences()
```
    Returns a boolean indicating whether all the namespace prefixes specified using setPrefixPreferences(com.xmlmind.xml.name.PrefixEntry[]) are pre-declared on the root element of the saved document.
    May return null which means "automatically determined", that is, true unless option favorInteroperability is turned on or the document is conforming to a DTD.
    Value true is the most conservative choice because it avoids errors when, for example, some attribute values reference qualified XML names as it is often the case with schemas, stylesheets, configuration files, etc.
    
    See Also:
    
    setPredeclarePrefixPreferences(java.lang.Boolean)
  - predeclarePrefixPrefs
```
protected boolean predeclarePrefixPrefs()
```
  - write
```
public void write(Document document)
           throws IOException
```
    Save specified document.
    The saved file does not automatically start with a XML declaration <?xml version="...." ?>. You need to use SaveDocument.writeXMLDeclaration(java.lang.String, java.lang.String, java.lang.String, java.io.Writer) for that.
    
    Parameters:
    
    document - Document to be saved.
    
    Throws:
    
    IOException - if, for any reason, the document cannot be saved.
  - beginWrite
```
protected void beginWrite(Document document)
                   throws IOException
```
    Throws:
    
    IOException
  - endWrite
```
protected void endWrite(Document document)
                 throws IOException
```
    Throws:
    
    IOException
  - write
```
public void write(Element element)
           throws IOException
```
    Save specified element as a document.
    The saved file does not automatically start with a XML declaration <?xml version="...." ?>. You need to use SaveDocument.writeXMLDeclaration(java.lang.String, java.lang.String, java.lang.String, java.io.Writer) for that.
    
    Parameters:
    
    element - Element to be saved.
    
    Throws:
    
    IOException - if, for any reason, the element cannot be saved.
  - beginWrite
```
protected void beginWrite(Element element)
                   throws IOException
```
    Throws:
    
    IOException
  - endWrite
```
protected void endWrite(Element element)
                 throws IOException
```
    Throws:
    
    IOException
  - flush
```
public void flush()
           throws IOException
```
    Flush the underlying Writer.
    
    Throws:
    
    IOException
    
    See Also:
    
    getWriter()
  - writeDocumentTypeDeclaration
```
protected void writeDocumentTypeDeclaration(DocumentTypeDeclaration dtd)
                                     throws IOException
```
    Throws:
    
    IOException
  - writeComment
```
protected void writeComment(Comment comment)
                     throws IOException
```
    Throws:
    
    IOException
  - checkComment
```
protected static void checkComment(Comment comment)
                            throws IOException
```
    Throws:
    
    IOException
  - shorten
```
protected static String shorten(String text)
```
  - writeProcessingInstruction
```
protected void writeProcessingInstruction(ProcessingInstruction pi)
                                   throws IOException
```
    Throws:
    
    IOException
  - checkProcessingInstruction
```
protected static void checkProcessingInstruction(ProcessingInstruction pi)
                                          throws IOException
```
    Throws:
    
    IOException
  - writeInclusion
```
protected void writeInclusion(Inclusion inclusion,
                              Node firstIncludedNode,
                              Node lastIncludedNode)
                       throws IOException
```
    Throws:
    
    IOException
  - writeEntityRef
```
protected void writeEntityRef(EntityRef entityRef)
                       throws IOException
```
    Throws:
    
    IOException
  - writeElement
```
protected void writeElement(Element element)
                     throws IOException
```
    Throws:
    
    IOException
  - writeStartTag
```
protected void writeStartTag(String tag,
                             Element element)
                      throws IOException
```
    Throws:
    
    IOException
  - writeAttributes
```
protected void writeAttributes(Element element)
                        throws IOException
```
    Throws:
    
    IOException
  - writeFrame
```
protected void writeFrame()
                   throws IOException
```
    Throws:
    
    IOException
  - writeAttribute
```
protected void writeAttribute(String tag,
                              String value)
                       throws IOException
```
    Throws:
    
    IOException
  - writeElementProperties
```
protected void writeElementProperties(Element element)
                               throws IOException
```
    Write certain element properties in the form of processing-instructions.
    Base implementation does nothing at all as properties are not supposed to be serialized.
    
    Throws:
    
    IOException
  - writeEmptyEndTag
```
protected void writeEmptyEndTag(String tag,
                                Element element)
                         throws IOException
```
    Throws:
    
    IOException
  - isEmptyElement
```
protected boolean isEmptyElement(Element element)
```
  - hasEmptyContentType
```
protected boolean hasEmptyContentType(Element element)
```
  - writeEndTag
```
protected void writeEndTag(String tag,
                           Element element)
                    throws IOException
```
    Throws:
    
    IOException
  - writeCDATA
```
protected void writeCDATA(Text text,
                          Element element)
                   throws IOException
```
    Throws:
    
    IOException
  - writeText
```
protected void writeText(Text text)
                  throws IOException
```
    Throws:
    
    IOException
  - pushElement
```
protected void pushElement(Element element)
```
  - popElement
```
protected void popElement()
```
  - addXMLBase
```
public static void addXMLBase(Document doc,
                              boolean addAttribute)
```
    Adds xml:base properties or attributes to all included elements found in specified document.
    This method is needed to implement xmltool indent -flat.
    
    Parameters:
    
    doc - the document to be annotated or modified
    
    addAttribute - if true, add an xml:base attribute rather than an xml:base property.
    Adding an xml:base attribute may cause validation errors to be reported. This is not the case with the xml:base property which is anyway also saved to disk as a xml:base attribute by a DocumentWriter or DocumentIndenter.

Class DocumentWriter

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

out

qNameHelper

textHelper

preserveInclusions

filterDuplicateIDs

duplicateIDFilter

cdataSections

documentType

favorInteroperability

predeclarePrefixPrefs

Constructor Detail

DocumentWriter

Method Detail

getWriter

setEncoding

getEncoding

setCharEntities

getCharEntities

setCharsSavedAsEntityRefs

getCharsSavedAsEntityRefs

setPrefixPreferences

getPrefixPreferences

setPreserveInclusions

getPreserveInclusions

setFilterDuplicateIDs

getFilterDuplicateIDs

setCdataSectionElements

getCdataSectionElements

setDocumentType

getDocumentType

setFavorInteroperability

getFavorInteroperability

setPredeclarePrefixPreferences

getPredeclarePrefixPreferences

predeclarePrefixPrefs

write

beginWrite

endWrite

write

beginWrite

endWrite

flush

writeDocumentTypeDeclaration

writeComment

checkComment

shorten

writeProcessingInstruction

checkProcessingInstruction

writeInclusion

writeEntityRef

writeElement

writeStartTag

writeAttributes

writeFrame

writeAttribute

writeElementProperties

writeEmptyEndTag

isEmptyElement

hasEmptyContentType

writeEndTag

writeCDATA

writeText

pushElement

popElement

addXMLBase