com.objsys.xbinder.runtime

Class XBXmlEncoder

java.lang.Object

java.io.Writer

com.objsys.xbinder.runtime.XBXmlEncoder

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable, java.lang.Appendable, java.lang.AutoCloseable

public class XBXmlEncoder
extends java.io.Writer

Provides methods for encoding to XML (text). This class is a Writer, so you can always use the Writer methods to directly write to the output stream. However, doing that has the obvious consequences that you are writing directly to the output stream and this class won't know anything about what you are doing.

Field Summary

Fields

Modifier and Type	Field and Description
static int	XMLINDENT

Fields inherited from class java.io.Writer

lock

Constructor Summary

Constructors

Constructor and Description
XBXmlEncoder(java.io.OutputStream out) Create an XBXmlEncoder on top of the given output (byte) stream.
XBXmlEncoder(java.io.OutputStream out, java.lang.String charsetName) Create an XBXmlEncoder on top of the given output (byte) stream.

Method Summary

Modifier and Type	Method and Description
java.lang.String	checkWellFormedElementAndContent(java.lang.String xmlFragment) Parse the given XML fragment to ensure it is well-formed.
void	close()
void	enableUniqueAttrChecking() For the current element only, turn on unique attribute checking.
void	encodeAttr(java.lang.String name, java.lang.String nsUri, java.lang.String prefix, java.lang.String value) This method encodes an XML attribute value.
void	encodeAttrs(java.util.List attrs) This method encodes the attributes in the given list.
void	encodeChars(java.lang.String data) Encode characters, applying escaping.
void	encodeCharsNoEscaping(java.lang.String data) Encode characters, as is (without escaping).
void	encodeEndElement() This method closes an element.
void	encodeNamespace(XBXmlNamespace namespace) Encode the given namespace on the next start element tag.
void	encodeStartDocument() This method encodes standard header information at the beginning of the XML document.
void	encodeStartElement(java.lang.String elemName, java.lang.String nsUri, java.lang.String nsPrefix) This method encodes an XML start element tag.
void	encodeXsiType(javax.xml.namespace.QName typeQName) Encode an xsi:type attribute for the given QName Eg.
void	flush()
void	setCanonicalXML(boolean value) Turn Canonical XML behavior on/off.
void	setIndent(int value) This method sets the number of spaces per indentation.
void	setNamespaces(XBXmlNamespace[] namespaces) Set the namespaces that should be encoded in the root element.
void	write(char[] cbuf, int off, int len)
void	write(int c)
void	write(java.lang.String str, int off, int len)

Methods inherited from class java.io.Writer

append, append, append, write, write

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

XMLINDENT

public static final int XMLINDENT

See Also:

Constant Field Values

Constructor Detail

XBXmlEncoder

public XBXmlEncoder(java.io.OutputStream out)

Create an XBXmlEncoder on top of the given output (byte) stream. Characters will be encoded according to UTF-8. Using this constructor, output to the stream you provide will be buffered.

Parameters:

out -

XBXmlEncoder

public XBXmlEncoder(java.io.OutputStream out,
                    java.lang.String charsetName)

Create an XBXmlEncoder on top of the given output (byte) stream. On JSE platforms, the output to the stream you provide will be buffered.

Parameters:

out -

charsetName - Characters will be encoded according to the given charset name (see java.nio.charset.Charset class).

Method Detail

checkWellFormedElementAndContent

public java.lang.String checkWellFormedElementAndContent(java.lang.String xmlFragment)

Parse the given XML fragment to ensure it is well-formed. The fragment must contain a single element and its content, and it must begin with the element start tag. Return the namespace for the element. If the element has a prefix, it will first be resolved according to the namespaces declared in the fragment. If this prefix is not declared, it will be resolved according to the currently declared namespaces known to this encoder. Calling this method has the side-effect of moving the encoder into the content of the current element, if it is not already there. This means you should make calls to encodeAttr and encodeNamespace prior to calling this method.

Parameters:

xmlFragment -

Returns:

The namespace, or empty string, if there isn't one.

enableUniqueAttrChecking

public void enableUniqueAttrChecking()

For the current element only, turn on unique attribute checking. It must be invoked prior to the first encodeAttr; otherwise, the results are undefined. By default, unique attribute checking is turned off. This is because the uniqueness of attributes is normally the result of data binding's mapping each declared attribute to a property. However, when wildcard attributes are in use, uniqueness is no longer guaranteed.

encodeAttr

public void encodeAttr(java.lang.String name,
                       java.lang.String nsUri,
                       java.lang.String prefix,
                       java.lang.String value)
                throws XBException

This method encodes an XML attribute value. If a prefix is already declared for the namespace, it will be used. Otherwise, if the suggested prefix is not in use, it will be used. Otherwise, a prefix will be generated. Any prefix used but not declared will automatically be declared.

Parameters:

name - Attribute name

nsUri - The attribute's namespace (empty if none)

prefix - Suggested prefix

value - Attribute value in string form.

Throws:

XBException

encodeAttrs

public void encodeAttrs(java.util.List attrs)
                 throws XBException

This method encodes the attributes in the given list. The prefix in the attribute is treated as a suggested prefix. If a prefix is already declared for the namespace, it will be used. Otherwise, if the suggested prefix is not in use, it will be used. Otherwise, a prefix will be generated. Any prefix used but not declared will automatically be declared. You should not modify the attribute objects you give to this method. The attribute objects may have their prefix changed.

Parameters:

attrs - The attributes to encode. List<XBAttributeBase>

Throws:

XBException

encodeChars

public void encodeChars(java.lang.String data)

Encode characters, applying escaping. Calling this method automatically closes any open element start tag.

encodeCharsNoEscaping

public void encodeCharsNoEscaping(java.lang.String data)

Encode characters, as is (without escaping). Users of this method should apply XML escaping when it may be needed. Calling this method automatically closes any open element start tag.

encodeNamespace

public void encodeNamespace(XBXmlNamespace namespace)

Encode the given namespace on the next start element tag. If called after encodeStartElement, but before encoding any content (characters or child elements) for that element, the declaration will belong to that element. If called after encoding some content, or ending an element, the declaration will belong to the next element. A prefix cannot be bound to two different namespaces in the same scope. To declare the default namespace, use an empty prefix.

encodeStartElement

public void encodeStartElement(java.lang.String elemName,
                               java.lang.String nsUri,
                               java.lang.String nsPrefix)

This method encodes an XML start element tag. The prefix provided is a suggestion. If the namespace is already mapped to some prefix, the existing prefix is used. Otherwise, if the prefix is not in use, it will be used. Otherwise, a prefix is generated. No prefix is used when the namespace is the default namespace. Whichever prefix is used, a namespace declaration will be automatically encoded, if necessary. For every call to encodeStartElement, you should make a corresponding call to encodeEndElement.

Parameters:

elemName - The name of element.

nsUri - The element's namespace (possibly empty)

nsPrefix - A suggested prefix for nsUri

Throws:

XBException - Thrown, if operation is failed.

encodeEndElement

public void encodeEndElement()

This method closes an element. If the start tag is still open (ie, no content was written), it will be closed with "/>". Otherwise, the most recently opened element is closed with "</qname>"

encodeXsiType

public void encodeXsiType(javax.xml.namespace.QName typeQName)

Encode an xsi:type attribute for the given QName Eg. xsi:type="pre:name" The namespace for the QName should already be mapped to a prefix (or be the default namespace). This method will determine the prefix to use inside the attribute value. This method may undeclare the default namespace (necessary if the given QName does not have a namespace).

setIndent

public void setIndent(int value)

This method sets the number of spaces per indentation. If the value is set to zero, no indentation of the XML data is done.

Parameters:

value - Number of spaces per indentation level.

encodeStartDocument

public void encodeStartDocument()

This method encodes standard header information at the beginning of the XML document.

Throws:

XBException - Thrown, if operation is failed.

setCanonicalXML

public void setCanonicalXML(boolean value)

Turn Canonical XML behavior on/off.

Parameters:

value - true to turn Canonical XML behavior on

setNamespaces

public void setNamespaces(XBXmlNamespace[] namespaces)

Set the namespaces that should be encoded in the root element. Each namespace in the array will end up being declared. However, prefixes declared using encodeNamespaces take precedence, so that a prefix found in this array and also given to encodeNamespaces will be replaced with a generated prefix. Also, if a namespace is given a prefix by encodeNamespaces, the prefix given here will be ignored. To declare the default namespace, use an empty prefix. For the default namespace, declarations made with encodeNamespaces take precedence.

close

public void close()
           throws java.io.IOException

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in class java.io.Writer

Throws:

java.io.IOException

flush

public void flush()
           throws java.io.IOException

Specified by:

flush in interface java.io.Flushable

Specified by:

flush in class java.io.Writer

Throws:

java.io.IOException

write

public void write(int c)
           throws java.io.IOException

Overrides:

write in class java.io.Writer

Throws:

java.io.IOException

write

public void write(java.lang.String str,
                  int off,
                  int len)
           throws java.io.IOException

Overrides:

write in class java.io.Writer

Throws:

java.io.IOException

write

public void write(char[] cbuf,
                  int off,
                  int len)
           throws java.io.IOException

Specified by:

write in class java.io.Writer

Throws:

java.io.IOException