Qizx fe-4.4p2 API

com.qizx.api
Interface XMLPushStream

All Known Implementing Classes:
com.qizx.xdm.CorePushBuilder, PushNodeBuilder, PushStreamToDOM, PushStreamToSAX, com.qizx.xdm.XMLPushStreamBase, XMLSerializer

public interface XMLPushStream

Streaming output for XML contents, working in 'push' mode.

This interface is mainly implemented by XMLSerializer, but it can also be used for any conversion of the XML data model to another representation: in particular there is an adapter to SAX2 (PushStreamToSAX) and an adapter to W3C DOM (PushStreamToDOM).

Note: this interface is similar in essence to javax.xml.stream.XMLStreamWriter. It is however simpler and supports the copy-namespaces feature of XQuery.

In this representation, a well-formed fragment of XML contents is considered as a stream of abstract "events" reflecting the physical structure:

Example: the following XML document

 <x:doc id='1' xmlns:x="some.namespace.uri">some text<empty value='a'/>
  comment:<!-- commentary -->, a PI: <?pi some stuff?></x:doc>
 

can be generated by this stream of "events":

Event method arguments
putDocumentStart -
putElementStart QName {some.namespace.uri}doc (prefix irrelevant)
putAttribute QName id, value '1', type null
putNamespace prefix 'x', URI "some.namespace.uri"
putText String 'some text'
putElementStart QName empty
putAttribute QName value, value 'a', type null
putElementEnd QName empty
putText String 'a comment:'
putComment String 'commentary'
putText String ', a PI: '
putProcessingInstruction target 'pi', contents 'some stuff'
putElementEnd QName x:doc
putDocumentEnd -

Note: this interface has all facilities needed to handle Namespaces completely (in particular missing prefixes can be generated automatically). However prefixes defined on QName's passed as arguments are ignored: one has to call putNamespace explicitly.

Exceptions thrown by methods: depends on the actual stream implementation. Should be thrown for an error preventing proper completion of the node streaming.


Field Summary
static int NSCOPY_NOPRESERVE_INHERIT
          copy-namespace mode used in putNodeCopy(Node, int).
static int NSCOPY_NOPRESERVE_NOINHERIT
          copy-namespace mode used in putNodeCopy(Node, int).
static int NSCOPY_PRESERVE_INHERIT
          copy-namespace mode used in putNodeCopy(Node, int).
static int NSCOPY_PRESERVE_NOINHERIT
          copy-namespace mode used in putNodeCopy(Node, int).
 
Method Summary
 void flush()
          Optional flush of the output flow.
 String getNSPrefix(String namespaceURI)
          Finds the namespace prefix bound to this NS URI in the current context.
 String getNSURI(String nsPrefix)
          Finds the namespace URI bound to this NS prefix in the current context.
 void putAtom(Object value)
          Puts an atom value event.
 void putAttribute(QName name, String value, String attrType)
          Puts an Attribute event for the current element.
 void putChars(char[] text, int start, int textLength)
          Puts a Text Fragment event.
 void putComment(String text)
          Puts a Comment event.
 void putDocumentEnd()
          Puts a Document End event.
 boolean putDocumentStart()
          Puts a Document Start event.
 void putDTD(String name, String publicId, String systemId, String internalSubset)
          Optionally puts a DTD event.
 void putElementEnd(QName name)
          Puts an Element End event.
 void putElementStart(QName name)
          Puts an Element Start event.
 boolean putNamespace(String prefix, String namespaceURI)
          Puts a Namespace declaration event for the current element.
 void putNamespaces(Node element, int copyNamespaceMode)
          Puts Namespace declarations of the element to the stream according to the specified mode.
 void putNodeCopy(Node node, int copyNamespaceMode)
          Copies a Node to the output flow by traversing it recursively.
 void putProcessingInstruction(String target, String contents)
          Puts a Processing-instruction event.
 void putText(String text)
          Puts a Text Fragment event.
 void reset()
          Resets the state before a new use.
 

Field Detail

NSCOPY_PRESERVE_INHERIT

static final int NSCOPY_PRESERVE_INHERIT
copy-namespace mode used in putNodeCopy(Node, int).

See Also:
Constant Field Values

NSCOPY_NOPRESERVE_INHERIT

static final int NSCOPY_NOPRESERVE_INHERIT
copy-namespace mode used in putNodeCopy(Node, int).

See Also:
Constant Field Values

NSCOPY_PRESERVE_NOINHERIT

static final int NSCOPY_PRESERVE_NOINHERIT
copy-namespace mode used in putNodeCopy(Node, int).

See Also:
Constant Field Values

NSCOPY_NOPRESERVE_NOINHERIT

static final int NSCOPY_NOPRESERVE_NOINHERIT
copy-namespace mode used in putNodeCopy(Node, int).

See Also:
Constant Field Values
Method Detail

reset

void reset()
Resets the state before a new use.

Should always be called before using the object again.


putDocumentStart

boolean putDocumentStart()
                         throws DataModelException
Puts a Document Start event. This method should be called first if the result is meant to be a well-formed document. However it it possible to omit it (and putDocumentEnd) if the desired result is an element.

Returns:
false if the current stream position is already inside a node (this event is then ignored)
Throws:
DataModelException - reasons

putDocumentEnd

void putDocumentEnd()
                    throws DataModelException
Puts a Document End event.

Throws:
DataModelException - reasons

putDTD

void putDTD(String name,
            String publicId,
            String systemId,
            String internalSubset)
            throws DataModelException
Optionally puts a DTD event.

Parameters:
name - name of the DTD. Optional, can be null
publicId - public-id of the DTD. Optional, can be null
systemId - system-id of the DTD. Optional, can be null
internalSubset - source form of the internal subset. Optional, can be null
Throws:
DataModelException - reasons

putElementStart

void putElementStart(QName name)
                     throws DataModelException
Puts an Element Start event.

Should precede namespace and attributes event for the element.

Parameters:
name - qualified name of the element. The local-part and namespace-URI properties of the name are used, but the prefix is ignored: to define a namespace (i.e a prefix/namespace-URI association), use the putNamespace(java.lang.String, java.lang.String) method.
Throws:
DataModelException - reasons

putElementEnd

void putElementEnd(QName name)
                   throws DataModelException
Puts an Element End event. Should balance putElementStart exactly, else the result could be incorrect.

Parameters:
name - qualified name of the element
Throws:
DataModelException - reasons

putNamespace

boolean putNamespace(String prefix,
                     String namespaceURI)
                     throws DataModelException
Puts a Namespace declaration event for the current element.

Must follow putElementStart and precede the contents of the element. The order is irrelevant. Duplicate namespace declarations are normally an error.

A Namespace declaration associates a prefix with a namespace-URI; it is equivalent to the xmlns: pseudo-attributes of XML markup. The empty prefix may be used for the default element namespace.

Note that such declarations are not mandatory: prefixes can be synthesized automatically by a XMLSerializer if missing.

Parameters:
prefix - prefix of the namespace, can be the empty string, but not null
namespaceURI - URI of the namespace: may not be null. The empty string means that the namespace-URI associated with the current prefix is erased (a XML 1.1 feature)
Returns:
false if the declaration was redundant
Throws:
DataModelException - reasons

putAttribute

void putAttribute(QName name,
                  String value,
                  String attrType)
                  throws DataModelException
Puts an Attribute event for the current element.

Must follow putElementStart and precede the contents of the element. The order of attributes is kept. A duplicate attribute is normally an error.

Parameters:
name - name of the attribute
value - string value of the attribute
attrType - attribute type: optional, may be null, or one of the strings "CDATA", "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", or "NOTATION"
Throws:
DataModelException - reasons

putText

void putText(String text)
             throws DataModelException
Puts a Text Fragment event.

A text fragment should appear inside an element. Consecutive text events are coalesced into one. An empty text fragment is discarded.

Parameters:
text - a fragment of text
Throws:
DataModelException - reasons

putChars

void putChars(char[] text,
              int start,
              int textLength)
              throws DataModelException
Puts a Text Fragment event.

A text fragment should appear inside an element. Consecutive text events are coalesced into one. An empty text fragment is discarded.

Parameters:
text - an array of characters
start - start offset in the character array
textLength - length of the fragment
Throws:
DataModelException - reasons

putComment

void putComment(String text)
                throws DataModelException
Puts a Comment event.

Parameters:
text - contents of a comment.
Throws:
DataModelException - reasons

putProcessingInstruction

void putProcessingInstruction(String target,
                              String contents)
                              throws DataModelException
Puts a Processing-instruction event.

Parameters:
target - target (name) of the PI
contents - contents of the PI
Throws:
DataModelException - reasons

putAtom

void putAtom(Object value)
             throws DataModelException
Puts an atom value event. This is an extension to the XDM (data model). If the stream does not support this extension (e.g XMLSerializer) then the atom is silently converted to its String value.

Parameters:
value - value of the atom.
Throws:
DataModelException - reasons

flush

void flush()
           throws DataModelException
Optional flush of the output flow. This is normally called by putDocumentEnd, but it can be used at any time. The actual effect depends on the implementation used (for example on XMLSerializer, the effect is to flush the output byte stream).

Throws:
DataModelException - reasons

putNodeCopy

void putNodeCopy(Node node,
                 int copyNamespaceMode)
                 throws DataModelException
Copies a Node to the output flow by traversing it recursively.

Namespace declarations are handled according to the specified mode. This mode implements the copy-namespaces declaration of XQuery.

Parameters:
node - Node to include in the output flow.
copyNamespaceMode - one of the 4 combinations of PRESERVE and INHERIT. The normal mode is NSCOPY_PRESERVE_INHERIT.
Throws:
DataModelException - reasons

putNamespaces

void putNamespaces(Node element,
                   int copyNamespaceMode)
                   throws DataModelException
Puts Namespace declarations of the element to the stream according to the specified mode. This mode implements the copy-namespaces declaration of XQuery. Auxiliary method used by putNodeCopy.

Parameters:
element - Element whose namespace declarations are put to the output flow.
copyNamespaceMode - one of the 4 combinations of PRESERVE and INHERIT. The normal mode is NSCOPY_PRESERVE_INHERIT.
Throws:
DataModelException - reasons

getNSPrefix

String getNSPrefix(String namespaceURI)
Finds the namespace prefix bound to this NS URI in the current context.

Parameters:
namespaceURI -
Returns:
a prefix or null

getNSURI

String getNSURI(String nsPrefix)
Finds the namespace URI bound to this NS prefix in the current context.

Parameters:
nsPrefix -
Returns:
an URI or null

© 2010 Axyana Software