|
Qizx fe-4.4p2 API | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 |
---|
static final int NSCOPY_PRESERVE_INHERIT
putNodeCopy(Node, int)
.
static final int NSCOPY_NOPRESERVE_INHERIT
putNodeCopy(Node, int)
.
static final int NSCOPY_PRESERVE_NOINHERIT
putNodeCopy(Node, int)
.
static final int NSCOPY_NOPRESERVE_NOINHERIT
putNodeCopy(Node, int)
.
Method Detail |
---|
void reset()
Should always be called before using the object again.
boolean putDocumentStart() throws DataModelException
DataModelException
- reasonsvoid putDocumentEnd() throws DataModelException
DataModelException
- reasonsvoid putDTD(String name, String publicId, String systemId, String internalSubset) throws DataModelException
name
- name of the DTD. Optional, can be nullpublicId
- public-id of the DTD. Optional, can be nullsystemId
- system-id of the DTD. Optional, can be nullinternalSubset
- source form of the internal subset. Optional, can
be null
DataModelException
- reasonsvoid putElementStart(QName name) throws DataModelException
Should precede namespace and attributes event for the element.
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.
DataModelException
- reasonsvoid putElementEnd(QName name) throws DataModelException
name
- qualified name of the element
DataModelException
- reasonsboolean putNamespace(String prefix, String namespaceURI) throws DataModelException
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.
prefix
- prefix of the namespace, can be the empty string, but not
nullnamespaceURI
- 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)
DataModelException
- reasonsvoid putAttribute(QName name, String value, String attrType) throws DataModelException
Must follow putElementStart and precede the contents of the element. The order of attributes is kept. A duplicate attribute is normally an error.
name
- name of the attributevalue
- string value of the attributeattrType
- attribute type: optional, may be null, or one of the
strings "CDATA", "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS",
"ENTITY", "ENTITIES", or "NOTATION"
DataModelException
- reasonsvoid putText(String text) throws DataModelException
A text fragment should appear inside an element. Consecutive text events are coalesced into one. An empty text fragment is discarded.
text
- a fragment of text
DataModelException
- reasonsvoid putChars(char[] text, int start, int textLength) throws DataModelException
A text fragment should appear inside an element. Consecutive text events are coalesced into one. An empty text fragment is discarded.
text
- an array of charactersstart
- start offset in the character arraytextLength
- length of the fragment
DataModelException
- reasonsvoid putComment(String text) throws DataModelException
text
- contents of a comment.
DataModelException
- reasonsvoid putProcessingInstruction(String target, String contents) throws DataModelException
target
- target (name) of the PIcontents
- contents of the PI
DataModelException
- reasonsvoid putAtom(Object value) throws DataModelException
value
- value of the atom.
DataModelException
- reasonsvoid flush() throws DataModelException
DataModelException
- reasonsvoid putNodeCopy(Node node, int copyNamespaceMode) throws DataModelException
Namespace declarations are handled according to the specified mode. This mode implements the copy-namespaces declaration of XQuery.
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.
DataModelException
- reasonsvoid putNamespaces(Node element, int copyNamespaceMode) throws DataModelException
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.
DataModelException
- reasonsString getNSPrefix(String namespaceURI)
namespaceURI
-
String getNSURI(String nsPrefix)
nsPrefix
-
|
© 2010 Axyana Software | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |