biz.c24.io.api.presentation
Class CDOStreamWriter

java.lang.Object
  extended by biz.c24.io.api.presentation.CDOStreamWriter
All Implemented Interfaces:
javax.xml.stream.XMLStreamWriter

public class CDOStreamWriter
extends Object
implements javax.xml.stream.XMLStreamWriter

The XMLStreamWriter implementation for an Complex Data Object.

Provides construction of a Complex Data Object based on StAX events. It does not perform any other validation checking on input beside that specified by model binding rules. I.e. its behaviuor is controlled by the JSR-173 specification as well as by the data model for an expected Complex Data Object. That model is specified by the element provided during instantiation. On finish the result will be represented as constructed Complex Data Object. Before the finish the result is undefined and can't be used.

If used with Java 1.5 or 1.4, then please ensure that the JSR-173 API library added to your classpath (jsr173_api.jar).

Note. Internal parts of this built up on the "Thread Local pattern". So, between the {#writeStartDocument start document} and end document it should not be used by any other threads.

The typical usage scenarion is following:

     Element element = ...
     CDOStreamWriter writer = new CDOStreamWriter(element);
     writer.writeStartDocument();
     // write root element <test>
     writer.writeStartElement("test");
     writer.writeDefaultNamespace("http://www.c24.biz/IO/StAXSupport");
     // write nested element <a>
     writer.writeStartElement("a");
     // within attribute att=&qout;value&qout;
     writer.writeAttribute("att", "value");
     // and textual content 'data'
     writer.writeCharacters("data")
     // write closing tag for an element <a>
     writer.writeEndElement();
     ...
     // other stuff that should be written
     ...
     // write closing tag for a root element <test>
     writer.writeEndElement();
     writer.writeEndDocument();
     // optional
     writer.flush()
     // getting the expected CDO
     ComplexDataObject cdo = writer.getResult();
 

That will produce the Complex Data Object having following XML representation:

<test xmlns="http://www.c24.biz/IO/StAXSupport"> <a att="value">data</a> ... </test>

Version:
$Revision: 10811 $ $Date: 2008-05-01 15:45:59 -0400 (Thu, 01 May 2008) $

Constructor Summary
CDOStreamWriter(Element element)
          Constructor with expected object model.
 
Method Summary
 void close()
          Closes this writer and free any resources associated with it.
 void flush()
          Writes any cached data to the underlying output mechanism.
 NamespaceContext getNamespaceContext()
          Returns the current namespace context.
 String getPrefix(String uri)
          Gets the prefix the namespece URI is bound to.
 Object getProperty(String name)
          Get the value of a feature/property from the underlying implementation.
 ComplexDataObject getResult()
          Returns the result of writing.
 void setDefaultNamespace(String uri)
          Binds a URI to the default namespace.
 void setNamespaceContext(NamespaceContext context)
          Sets the current namespace context for prefix and namespace URI bindings.
 void setPrefix(String prefix, String uri)
          Sets the prefix the namespace URI is bound to.
 void writeAttribute(String name, String value)
          Writes an attribute with local name only.
 void writeAttribute(String uri, String name, String value)
          Writes an attribute without prefix into current context.
 void writeAttribute(String prefix, String uri, String name, String value)
          Writes an attribute into current context.
 void writeCData(String data)
          Writes a CDATA section.
 void writeCharacters(char[] text, int start, int len)
          Write characters to the current context.
 void writeCharacters(String text)
          Write text to the current context.
 void writeComment(String data)
          Writes a comment with the data enclosed.
 void writeDefaultNamespace(String uri)
          Writes the default namespace.
 void writeDTD(String dtd)
          Write a DTD section.
 void writeEmptyElement(String name)
          Writes an empty element tag with local name only.
 void writeEmptyElement(String uri, String name)
          Writes an empty element tag without prefix.
 void writeEmptyElement(String prefix, String name, String uri)
          Writes an empty element tag.
 void writeEndDocument()
          Closes any start tags and writes corresponding end tags.
 void writeEndElement()
          Writes an end tag.
 void writeEntityRef(String name)
          Writes an entity reference.
 void writeNamespace(String prefix, String uri)
          Writes a namespace.
 void writeProcessingInstruction(String target)
          Writes a processing instruction without data.
 void writeProcessingInstruction(String target, String data)
          Writes a processing instruction.
 void writeStartDocument()
          Write the default XML Declaration.
 void writeStartDocument(String version)
          Write the XML Declaration with specified version.
 void writeStartDocument(String encoding, String version)
          Write the XML Declaration with specified version and encoding.
 void writeStartElement(String name)
          Writes a start tag with local name only.
 void writeStartElement(String uri, String name)
          Writes a start tag without prefix.
 void writeStartElement(String prefix, String name, String uri)
          Writes a start tag.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CDOStreamWriter

public CDOStreamWriter(Element element)
Constructor with expected object model.

Constructs the CDO writer with specified element model which describes the expected Complex Data Object.

The provided element may be null. This means that result has not a model and consequently may contain an any contents (i.e. an analog of XML's

xs:any). The DOM like result will be produced without any binding restrictions.

Parameters:
element - the element instance that described the expected Complex Data Object, may be null.
Method Detail

writeStartDocument

public void writeStartDocument()
                        throws javax.xml.stream.XMLStreamException
Write the default XML Declaration.

Prepares the writer for writing/construction of the Complex Data Object. This method does not write any XML Declaration stuff, since the actual XML Declaration provided by Complex Data Object marshalling.

Specified by:
writeStartDocument in interface javax.xml.stream.XMLStreamWriter
Throws:
javax.xml.stream.XMLStreamException - if process failed.

writeStartDocument

public void writeStartDocument(String version)
                        throws javax.xml.stream.XMLStreamException
Write the XML Declaration with specified version.

In fact delegate to the default XML Declaration writing.

Specified by:
writeStartDocument in interface javax.xml.stream.XMLStreamWriter
Parameters:
version - version of the xml document.
Throws:
javax.xml.stream.XMLStreamException
See Also:
writeStartDocument()

writeStartDocument

public void writeStartDocument(String encoding,
                               String version)
                        throws javax.xml.stream.XMLStreamException
Write the XML Declaration with specified version and encoding.

In fact delegate to the default XML Declaration writing.

Specified by:
writeStartDocument in interface javax.xml.stream.XMLStreamWriter
Parameters:
encoding - encoding of the xml declaration
version - version of the xml document
Throws:
javax.xml.stream.XMLStreamException
See Also:
writeStartDocument(String)

writeProcessingInstruction

public void writeProcessingInstruction(String target,
                                       String data)
                                throws javax.xml.stream.XMLStreamException
Writes a processing instruction.

Writes the processing instruction specified by target and data into current context. The context is opened on each start element event.

Specified by:
writeProcessingInstruction in interface javax.xml.stream.XMLStreamWriter
Parameters:
target - the target of the processing instruction, may not be null.
data - the data contained in the processing instruction.
Throws:
javax.xml.stream.XMLStreamException - if process failed.
IllegalArgumentException - if provided target or data is null.

writeProcessingInstruction

public void writeProcessingInstruction(String target)
                                throws javax.xml.stream.XMLStreamException
Writes a processing instruction without data.

Writes the processing instruction specified by target into current context. The context is opened on each start element event.

Specified by:
writeProcessingInstruction in interface javax.xml.stream.XMLStreamWriter
Parameters:
target - the target of the processing instruction, may not be null.
Throws:
javax.xml.stream.XMLStreamException - if process failed.
IllegalArgumentException - if provided target or data is null.

writeComment

public void writeComment(String data)
                  throws javax.xml.stream.XMLStreamException
Writes a comment with the data enclosed.

Specified by:
writeComment in interface javax.xml.stream.XMLStreamWriter
Parameters:
data - the data contained in the comment, may be null.
Throws:
javax.xml.stream.XMLStreamException

writeStartElement

public void writeStartElement(String prefix,
                              String name,
                              String uri)
                       throws javax.xml.stream.XMLStreamException
Writes a start tag.

Opens the new context for an writing attributes, namespaces and charachters. The writes end tag will cause the closing current context.

Specified by:
writeStartElement in interface javax.xml.stream.XMLStreamWriter
Parameters:
name - local name of the tag, may not be null.
prefix - the prefix of the tag, may not be null.
uri - the namespace URI to bind the prefix to, may not be null.
Throws:
javax.xml.stream.XMLStreamException - if process failed.
IllegalArgumentException - if any arguments is null.

writeStartElement

public void writeStartElement(String uri,
                              String name)
                       throws javax.xml.stream.XMLStreamException
Writes a start tag without prefix.

In fact delegates the call to the writeStartElement(String, String, String) with empty (means default) prefix.

Specified by:
writeStartElement in interface javax.xml.stream.XMLStreamWriter
Parameters:
uri - the namespace URI of the prefix to use, may not be null.
name - local name of the tag, may not be null.
Throws:
javax.xml.stream.XMLStreamException - if the namespace URI has not been bound to a prefix.
IllegalArgumentException - if any arguments is null.

writeStartElement

public void writeStartElement(String name)
                       throws javax.xml.stream.XMLStreamException
Writes a start tag with local name only.

In fact delegates the call to the writeStartElement(String, String) with empty namespace URI.

Specified by:
writeStartElement in interface javax.xml.stream.XMLStreamWriter
Parameters:
name - local name of the tag, may not be null.
Throws:
javax.xml.stream.XMLStreamException - if process failed.
IllegalArgumentException - if name is null.

writeEmptyElement

public void writeEmptyElement(String prefix,
                              String name,
                              String uri)
                       throws javax.xml.stream.XMLStreamException
Writes an empty element tag.

Opens the new context and closes it immediatelly. In fact is the consequent call of writeStartElement(String, String, String) and writeEndElement().

Specified by:
writeEmptyElement in interface javax.xml.stream.XMLStreamWriter
Parameters:
prefix - the prefix of the tag, may not be null.
name - local name of the tag, may not be null.
uri - the namespace URI to bind the tag to, may not be null.
Throws:
javax.xml.stream.XMLStreamException - if process failed.
IllegalArgumentException - if any arguments is null.

writeEmptyElement

public void writeEmptyElement(String uri,
                              String name)
                       throws javax.xml.stream.XMLStreamException
Writes an empty element tag without prefix.

In fact delegates the call to the writeEmptyElement(String, String, String) with empty prefix.

Specified by:
writeEmptyElement in interface javax.xml.stream.XMLStreamWriter
Parameters:
uri - the namespace URI to bind the tag to, may not be null.
name - local name of the tag, may not be null.
Throws:
javax.xml.stream.XMLStreamException - if the namespace URI has not been bound to a prefix.
See Also:
writeEmptyElement(String, String, String)

writeEmptyElement

public void writeEmptyElement(String name)
                       throws javax.xml.stream.XMLStreamException
Writes an empty element tag with local name only.

In fact delegates the call to the writeEmptyElement(String, String) with empty namespace URI.

Specified by:
writeEmptyElement in interface javax.xml.stream.XMLStreamWriter
Parameters:
name - local name of the tag, may not be null.
Throws:
javax.xml.stream.XMLStreamException - if the namespace URI has not been bound to a prefix.
See Also:
writeEmptyElement(String, String)

writeEndElement

public void writeEndElement()
                     throws javax.xml.stream.XMLStreamException
Writes an end tag.

Closes the current scope opened by start tag writer.

Specified by:
writeEndElement in interface javax.xml.stream.XMLStreamWriter
Throws:
javax.xml.stream.XMLStreamException - if process failed.

writeEndDocument

public void writeEndDocument()
                      throws javax.xml.stream.XMLStreamException
Closes any start tags and writes corresponding end tags.

Specified by:
writeEndDocument in interface javax.xml.stream.XMLStreamWriter
Throws:
javax.xml.stream.XMLStreamException - if process failed.

close

public void close()
           throws javax.xml.stream.XMLStreamException
Closes this writer and free any resources associated with it.

Actually does not anything. Implemented according to stream writer contract.

Specified by:
close in interface javax.xml.stream.XMLStreamWriter
Throws:
javax.xml.stream.XMLStreamException - never happend, preserves the stream writer contract.

flush

public void flush()
           throws javax.xml.stream.XMLStreamException
Writes any cached data to the underlying output mechanism.

Specified by:
flush in interface javax.xml.stream.XMLStreamWriter
Throws:
javax.xml.stream.XMLStreamException - if process failed.

writeAttribute

public void writeAttribute(String prefix,
                           String uri,
                           String name,
                           String value)
                    throws javax.xml.stream.XMLStreamException
Writes an attribute into current context.

Specified by:
writeAttribute in interface javax.xml.stream.XMLStreamWriter
Parameters:
prefix - the prefix for this attribute
uri - the namespace URI of the prefix for this attribute.
name - the local name of the attribute.
value - the value of the attribute.
Throws:
IllegalStateException - if the current state does not allow attribute writing.
javax.xml.stream.XMLStreamException - if the namespace URI has not been bound to a prefix.

writeAttribute

public void writeAttribute(String uri,
                           String name,
                           String value)
                    throws javax.xml.stream.XMLStreamException
Writes an attribute without prefix into current context.

In fact, delegates the call to the writeAttribute(String, String, String, String) with an empty prefix.

Specified by:
writeAttribute in interface javax.xml.stream.XMLStreamWriter
Parameters:
uri - the namespace URI of the prefix for this attribute.
name - the local name of the attribute.
value - the value of the attribute.
Throws:
IllegalStateException - if the current state does not allow attribute writing.
javax.xml.stream.XMLStreamException - if the namespace URI has not been bound to a prefix.

writeAttribute

public void writeAttribute(String name,
                           String value)
                    throws javax.xml.stream.XMLStreamException
Writes an attribute with local name only.

In fact, delegates the call to the writeAttribute(String, String, String) with an empty namespace URI.

Specified by:
writeAttribute in interface javax.xml.stream.XMLStreamWriter
Parameters:
name - the local name of the attribute
value - the value of the attribute
Throws:
IllegalStateException - if the current state does not allow attribute writing.
javax.xml.stream.XMLStreamException - if the namespace URI has not been bound to a prefix.

writeDTD

public void writeDTD(String dtd)
              throws javax.xml.stream.XMLStreamException
Write a DTD section.

This string represents the entire doctypedecl production from the XML 1.0 specification.

Specified by:
writeDTD in interface javax.xml.stream.XMLStreamWriter
Parameters:
dtd - the DTD to be written.
Throws:
javax.xml.stream.XMLStreamException - if proces failed.

writeEntityRef

public void writeEntityRef(String name)
                    throws javax.xml.stream.XMLStreamException
Writes an entity reference.

Specified by:
writeEntityRef in interface javax.xml.stream.XMLStreamWriter
Parameters:
name - the name of the entity.
Throws:
javax.xml.stream.XMLStreamException - if process failed.

writeCharacters

public void writeCharacters(String text)
                     throws javax.xml.stream.XMLStreamException
Write text to the current context.

Specified by:
writeCharacters in interface javax.xml.stream.XMLStreamWriter
Parameters:
text - the value to write.
Throws:
javax.xml.stream.XMLStreamException - if process failed.

writeCharacters

public void writeCharacters(char[] text,
                            int start,
                            int len)
                     throws javax.xml.stream.XMLStreamException
Write characters to the current context.

Specified by:
writeCharacters in interface javax.xml.stream.XMLStreamWriter
Parameters:
text - the characters to write.
start - the starting position in the characters.
len - the number of characters to write.
Throws:
javax.xml.stream.XMLStreamException - if process failed.

writeCData

public void writeCData(String data)
                throws javax.xml.stream.XMLStreamException
Writes a CDATA section.

Specified by:
writeCData in interface javax.xml.stream.XMLStreamWriter
Parameters:
data - the data contained in the CDATA section, may not be null
Throws:
javax.xml.stream.XMLStreamException - if process failed.

getPrefix

public String getPrefix(String uri)
                 throws javax.xml.stream.XMLStreamException
Gets the prefix the namespece URI is bound to.

Specified by:
getPrefix in interface javax.xml.stream.XMLStreamWriter
Returns:
the prefix or null
Throws:
javax.xml.stream.XMLStreamException - if process failed.

setPrefix

public void setPrefix(String prefix,
                      String uri)
               throws javax.xml.stream.XMLStreamException
Sets the prefix the namespace URI is bound to.

This prefix is bound in the scope of the current START_ELEMENT / END_ELEMENT pair. If this method is called before a START_ELEMENT has been written the prefix is bound in the root scope.

In fact, delegates the call to the writeNamespace(String, String).

Specified by:
setPrefix in interface javax.xml.stream.XMLStreamWriter
Parameters:
prefix - the prefix to bind to the namespace URI, may not be null.
uri - the namespace URI to bind to the prefix, may be null.
Throws:
javax.xml.stream.XMLStreamException - if process failed.

writeNamespace

public void writeNamespace(String prefix,
                           String uri)
                    throws javax.xml.stream.XMLStreamException
Writes a namespace.

Stores the provided namespace URI and its prefix to the underlied Complex Data Object. If the prefix argument to this method is the empty string, "xmlns" or null this method will delegate call to the writeDefaultNamespace.

Specified by:
writeNamespace in interface javax.xml.stream.XMLStreamWriter
Parameters:
prefix - the prefix to bind this namespace to.
uri - the URI to bind the prefix to.
Throws:
IllegalStateException - if the current state does not allow namespace writing.
javax.xml.stream.XMLStreamException - if process failed.

writeDefaultNamespace

public void writeDefaultNamespace(String uri)
                           throws javax.xml.stream.XMLStreamException
Writes the default namespace.

Stores the default namespace with provided URI to the underlied Complex Data Object.

In fact, delegates the call to the writeNamespace(String, String) with an empty prefix.

Specified by:
writeDefaultNamespace in interface javax.xml.stream.XMLStreamWriter
Parameters:
uri - the namespace URI to bind the default namespace to.
Throws:
IllegalStateException - if the current state does not allow namespace writing.
javax.xml.stream.XMLStreamException - if process failed.

setDefaultNamespace

public void setDefaultNamespace(String uri)
                         throws javax.xml.stream.XMLStreamException
Binds a URI to the default namespace.

This URI is bound in the scope of the current START_ELEMENT / END_ELEMENT pair. If this method is called before a START_ELEMENT has been written the URI is bound in the root scope.

In fact, delegates the call to the writeDefaultNamespace(String).

Specified by:
setDefaultNamespace in interface javax.xml.stream.XMLStreamWriter
Parameters:
uri - the uri to bind to the default namespace, may be null.
Throws:
javax.xml.stream.XMLStreamException - if process failed.

setNamespaceContext

public void setNamespaceContext(NamespaceContext context)
                         throws javax.xml.stream.XMLStreamException
Sets the current namespace context for prefix and namespace URI bindings.

This context becomes the root namespace context for writing and will replace the current root namespace context. Subsequent calls to setPrefix(String, String) and setDefaultNamespace(String) will bind namespaces using the context passed to the method as the root context for resolving namespaces. This method may only be called once at the start of the document. It does not cause the namespaces to be declared.

If a namespace URI to prefix mapping is found in the namespace context it is treated as declared and the prefix may be used by the writer.

Specified by:
setNamespaceContext in interface javax.xml.stream.XMLStreamWriter
Parameters:
context - the namespace context to use for this writer, may not be null.
Throws:
javax.xml.stream.XMLStreamException - if process failed.

getNamespaceContext

public NamespaceContext getNamespaceContext()
Returns the current namespace context.

Specified by:
getNamespaceContext in interface javax.xml.stream.XMLStreamWriter
Returns:
the current namespace context
See Also:
setNamespaceContext(javax.xml.namespace.NamespaceContext)

getProperty

public Object getProperty(String name)
                   throws IllegalArgumentException
Get the value of a feature/property from the underlying implementation.

Specified by:
getProperty in interface javax.xml.stream.XMLStreamWriter
Parameters:
name - The name of the property, may not be null.
Returns:
The value of the property.
Throws:
IllegalArgumentException - if the property is not supported.
NullPointerException - if the name is null.

getResult

public ComplexDataObject getResult()
Returns the result of writing.

Returns the constructed Complex Data Object that was built during writer using.

Returns:
the expected Complex Data Object instance.


C24 Technologies © 2002-2012: All Rights Reserved.