org.xpresso.xml
Class Document

java.lang.Object
  extended by org.xpresso.xml.XmlContent
      extended by org.xpresso.xml.Document
All Implemented Interfaces:
java.io.Serializable, java.lang.CharSequence, java.lang.Cloneable
Direct Known Subclasses:
ConcurrentDocument

public class Document
extends XmlContent
implements java.lang.Cloneable, java.lang.CharSequence

The main class, used to generate the XML document. It contains a stack containing Elements.
Content is added to the upper Element on the stack. Document provides methods to stack and unstack elements,
adding content and returning the resulting XML.

Document is itself a XmlContent, so a Document can be added at a chosen place of another Document. Header information (XML header,
DTD declaration) are in this case discarded.
This code is under the LGPL v3 licence.

Author:
Alexis Dufrenoy
See Also:
Serialized Form

Field Summary
protected  java.lang.StringBuilder header
          Contains the header: XML declaration and DTD reference
protected  boolean open
          Content can only be added to the Document if this boolean is true.
protected  java.util.Deque<Element> stack
          This stack is used to know the depth in the document tree
 
Fields inherited from class org.xpresso.xml.XmlContent
content
 
Constructor Summary
protected Document()
          Constructor creating a new Document without content.
protected Document(Element root)
          Constructor creating a new Document with only a root Element.
protected Document(java.lang.String xmlVersion, Element root)
          Constructor creating a new Document with a xml version and a root Element.
protected Document(java.lang.String xmlVersion, Element root, java.lang.String dtdName, java.lang.String dtdFile)
          Constructor creating a new Document with a xml version, a root Element
and a DOCTYPE statement.
protected Document(java.lang.String xmlVersion, java.lang.String encoding, Element root)
          Constructor creating a new Document with a xml version, the character set encoding
and a root Element.
protected Document(java.lang.String xmlVersion, java.lang.String encoding, Element root, boolean standalone)
          Constructor creating a new Document with a xml version, the character set encoding, the standalone setting
and a root Element.
protected Document(java.lang.String xmlVersion, java.lang.String encoding, Element root, boolean standalone, java.lang.String dtdName, java.lang.String dtdFile)
          Constructor creating a new Document with a xml version, the character set encoding, the standalone setting
a root Element and a DOCTYPE statement.
protected Document(java.lang.String xmlVersion, java.lang.String encoding, Element root, java.lang.String dtdName, java.lang.String dtdFile)
          Constructor creating a new Document with a xml version, the character set encoding,
a root Element and a DOCTYPE statement.
 
Method Summary
 void add(XmlContent xmlContent)
          Add an XmlContent to the uppest Element of the stack.
 char charAt(int index)
          Required for implementing CharSequence
 Document clone()
          Returns a deep clone of the Document, regardless its current state.
static CDATA createCdata(java.lang.String text)
          Returns a new CDATA
static Comment createComment(java.lang.String text)
          Returns a new Comment
static Document createDocument(Element root)
          Creates a new Document with only a root Element.
static Document createDocument(java.lang.String xmlVersion, Element root)
          Creates a new Document with a xml version and a root Element.
static Document createDocument(java.lang.String xmlVersion, Element root, java.lang.String dtdName, java.lang.String dtdFile)
          Creates a new Document with a xml version, a root Element
and a DOCTYPE statement.
static Document createDocument(java.lang.String xmlVersion, java.lang.String encoding, Element root)
          Creates a new Document with a xml version, the character set encoding
and a root Element.
static Document createDocument(java.lang.String xmlVersion, java.lang.String encoding, Element root, boolean standalone)
          Creates a new Document with a xml version, the character set encoding, the standalone setting
and a root Element.
static Document createDocument(java.lang.String xmlVersion, java.lang.String encoding, Element root, boolean standalone, java.lang.String dtdName, java.lang.String dtdFile)
          Creates a new Document with a xml version, the character set encoding, the standalone setting
a root Element and a DOCTYPE statement.
static Document createDocument(java.lang.String xmlVersion, java.lang.String encoding, Element root, java.lang.String dtdName, java.lang.String dtdFile)
          a new Document with a xml version, the character set encoding,
a root Element and a DOCTYPE statement.
static Element createElement(java.lang.String label)
          Creates a new Element
static ProcessingInstruction createProcessingInstruction(java.lang.String text)
          Returns a new ProcessingInstruction
static Text createText(java.lang.String text)
          Returns a new XML Text
 void finish()
          Unstack all Elements, which means the document is closed.
 java.io.StringReader getStringReader()
          Returns a StringReader containing the XML.
 java.lang.String getText()
          Return the Document as a String which can be added to another Document, which means it has to be
closed and that the header informations are discarded.
 java.lang.String getXmlText()
          Return the Document in its current state of completion.
 int length()
          Required for implementing CharSequence
static void main(java.lang.String[] args)
          For test purpose only !
 void stackElement(Element element)
          Adds a level of depth to the current branch of the document.
 java.lang.CharSequence subSequence(int start, int end)
          Required for implementing CharSequence
 void unstackElement()
          Unstack a level of depth from the current branch of the document.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.lang.CharSequence
toString
 

Field Detail

header

protected java.lang.StringBuilder header
Contains the header: XML declaration and DTD reference


stack

protected java.util.Deque<Element> stack
This stack is used to know the depth in the document tree


open

protected boolean open
Content can only be added to the Document if this boolean is true. It is set to false by
the finish() method or when
the last Element is unstacked by
the unstackElement() method.

Constructor Detail

Document

protected Document(Element root)
Constructor creating a new Document with only a root Element.

Parameters:
root - Root Element of the document

Document

protected Document(java.lang.String xmlVersion,
                   Element root)
Constructor creating a new Document with a xml version and a root Element.

Parameters:
xmlVersion - XML version in the header of the Document
root - Root Element of the document

Document

protected Document(java.lang.String xmlVersion,
                   Element root,
                   java.lang.String dtdName,
                   java.lang.String dtdFile)
Constructor creating a new Document with a xml version, a root Element
and a DOCTYPE statement.

Parameters:
xmlVersion - XML version in the header of the Document
root - Root Element of the document
dtdName - Reference name to give to the DTD with the XML document
dtdFile - DTD File

Document

protected Document(java.lang.String xmlVersion,
                   java.lang.String encoding,
                   Element root)
Constructor creating a new Document with a xml version, the character set encoding
and a root Element.

Parameters:
xmlVersion - XML version in the header of the Document
encoding - Character set encoding
root - Root Element of the document

Document

protected Document(java.lang.String xmlVersion,
                   java.lang.String encoding,
                   Element root,
                   java.lang.String dtdName,
                   java.lang.String dtdFile)
Constructor creating a new Document with a xml version, the character set encoding,
a root Element and a DOCTYPE statement.

Parameters:
xmlVersion - XML version in the header of the Document
encoding - Character set encoding
root - Root Element of the document
dtdName - Reference name to give to the DTD with the XML document
dtdFile - DTD File

Document

protected Document(java.lang.String xmlVersion,
                   java.lang.String encoding,
                   Element root,
                   boolean standalone)
Constructor creating a new Document with a xml version, the character set encoding, the standalone setting
and a root Element.

Parameters:
xmlVersion - XML version in the header of the Document
encoding - Character set encoding
root - Root Element of the document
standalone - Is the document standalone, which means does it refer to a DTD or not. Values are "true" or "false"

Document

protected Document(java.lang.String xmlVersion,
                   java.lang.String encoding,
                   Element root,
                   boolean standalone,
                   java.lang.String dtdName,
                   java.lang.String dtdFile)
Constructor creating a new Document with a xml version, the character set encoding, the standalone setting
a root Element and a DOCTYPE statement.

Parameters:
xmlVersion - XML version in the header of the Document
encoding - Character set encoding
root - Root Element of the document
standalone - Is the document standalone, which means does it refer to a DTD or not. Values are "true" or "false"
dtdName - Reference name to give to the DTD with the XML document
dtdFile - DTD File

Document

protected Document()
Constructor creating a new Document without content. All data structures are initialized and empty

Method Detail

createDocument

public static Document createDocument(Element root)
Creates a new Document with only a root Element.

Parameters:
root - Root Element of the document
Returns:
The created Document

createDocument

public static Document createDocument(java.lang.String xmlVersion,
                                      Element root)
Creates a new Document with a xml version and a root Element.

Parameters:
xmlVersion - XML version in the header of the Document
root - Root Element of the document
Returns:
The created Document

createDocument

public static Document createDocument(java.lang.String xmlVersion,
                                      Element root,
                                      java.lang.String dtdName,
                                      java.lang.String dtdFile)
Creates a new Document with a xml version, a root Element
and a DOCTYPE statement.

Parameters:
xmlVersion - XML version in the header of the Document
root - Root Element of the document
dtdName - Reference name to give to the DTD with the XML document
dtdFile - DTD File
Returns:
The created Document

createDocument

public static Document createDocument(java.lang.String xmlVersion,
                                      java.lang.String encoding,
                                      Element root)
Creates a new Document with a xml version, the character set encoding
and a root Element.

Parameters:
xmlVersion - XML version in the header of the Document
encoding - Character set encoding
root - Root Element of the document
Returns:
The created Document

createDocument

public static Document createDocument(java.lang.String xmlVersion,
                                      java.lang.String encoding,
                                      Element root,
                                      java.lang.String dtdName,
                                      java.lang.String dtdFile)
a new Document with a xml version, the character set encoding,
a root Element and a DOCTYPE statement.

Parameters:
xmlVersion - XML version in the header of the Document
encoding - Character set encoding
root - Root Element of the document
dtdName - Reference name to give to the DTD with the XML document
dtdFile - DTD File
Returns:
The created Document

createDocument

public static Document createDocument(java.lang.String xmlVersion,
                                      java.lang.String encoding,
                                      Element root,
                                      boolean standalone)
Creates a new Document with a xml version, the character set encoding, the standalone setting
and a root Element.

Parameters:
xmlVersion - XML version in the header of the Document
encoding - Character set encoding
root - Root Element of the document
standalone - Is the document standalone, which means does it refer to a DTD or not. Values are "true" or "false"
Returns:
The created Document

createDocument

public static Document createDocument(java.lang.String xmlVersion,
                                      java.lang.String encoding,
                                      Element root,
                                      boolean standalone,
                                      java.lang.String dtdName,
                                      java.lang.String dtdFile)
Creates a new Document with a xml version, the character set encoding, the standalone setting
a root Element and a DOCTYPE statement.

Parameters:
xmlVersion - XML version in the header of the Document
encoding - Character set encoding
root - Root Element of the document
standalone - Is the document standalone, which means does it refer to a DTD or not. Values are "true" or "false"
dtdName - Reference name to give to the DTD with the XML document
dtdFile - DTD File
Returns:
The created Document

stackElement

public void stackElement(Element element)
                  throws ClosedDocumentException
Adds a level of depth to the current branch of the document. It adds an Element.
Further content will be added to the newly added element, until a new one is stacked or it is unstacked.

Parameters:
element - The new Element to be stacked
Throws:
ClosedDocumentException - Thrown if the method is added after the document was closed

unstackElement

public void unstackElement()
                    throws ClosedDocumentException
Unstack a level of depth from the current branch of the document. Further XmlContent
will be added to the Element just below the one unstacked. If this one is the last in
the stack, the document is closed.

Throws:
ClosedDocumentException - Thrown if the method is added after the document was closed

add

public void add(XmlContent xmlContent)
         throws ClosedDocumentException
Add an XmlContent to the uppest Element of the stack.
If the content is an Element, it will be added as an empty element.

Parameters:
xmlContent - Content to be added
Throws:
ClosedDocumentException - Thrown if the method is added after the document was closed

finish

public void finish()
Unstack all Elements, which means the document is closed.


getXmlText

public java.lang.String getXmlText()
Return the Document in its current state of completion. If Elements are left on the stack,
the result will not be a well-formed XML document.

Returns:
The document as a String

getStringReader

public java.io.StringReader getStringReader()
Returns a StringReader containing the XML.

Returns:
The XML

getText

public java.lang.String getText()
                         throws IllegalContentException
Return the Document as a String which can be added to another Document, which means it has to be
closed and that the header informations are discarded.

Overrides:
getText in class XmlContent
Returns:
String containing the XmlContent
Throws:
IllegalContentException - Thrown if the Document is not closed

charAt

public char charAt(int index)
Required for implementing CharSequence

Specified by:
charAt in interface java.lang.CharSequence

length

public int length()
Required for implementing CharSequence

Specified by:
length in interface java.lang.CharSequence

subSequence

public java.lang.CharSequence subSequence(int start,
                                          int end)
Required for implementing CharSequence

Specified by:
subSequence in interface java.lang.CharSequence

clone

public Document clone()
               throws java.lang.CloneNotSupportedException
Returns a deep clone of the Document, regardless its current state. Can be used to generated several Documents
with approaching content

Overrides:
clone in class java.lang.Object
Throws:
java.lang.CloneNotSupportedException

createElement

public static Element createElement(java.lang.String label)
Creates a new Element

Parameters:
label - label of the new Element
Returns:
A new element

createCdata

public static CDATA createCdata(java.lang.String text)
Returns a new CDATA

Parameters:
text - Content of the CDATA
Returns:
A new CDATA block

createComment

public static Comment createComment(java.lang.String text)
Returns a new Comment

Parameters:
text - Content of the Comment
Returns:
A new Comment

createProcessingInstruction

public static ProcessingInstruction createProcessingInstruction(java.lang.String text)
Returns a new ProcessingInstruction

Parameters:
text - Text of the Processing Instruction
Returns:
a new Processing Instruction

createText

public static Text createText(java.lang.String text)
Returns a new XML Text

Parameters:
text - Content of the Text
Returns:
A new Text

main

public static void main(java.lang.String[] args)
For test purpose only !

Parameters:
args -