Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Qizx/open 4.1 API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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:

- Beginning of a document: putDocumentStart
- DTD information: putDTD, optional
- Beginning of an Element: putElementStart. Corresponds to the start-tag, can be followed by putAttribute and putNamespace. The contents of the element is then defined by following events putElementStart (nested elements), putText, putComment, putProcessingInstruction. An element is closed by putElementEnd.
- Attribute: putAttribute defines an attribute on the current element. Must come after a putElementStart, and before any content event.
- Namespace: putNamespace associates a namespace prefix with a namespace URI. Similar to the xmlns pseudo-attributes. The prefix/namespace-uri association defined remains valid until the end of current element (but can be overloaded by another prefix defined on an enclosed element). Must come after a putElementStart and before any content event.
- Text fragment: putText. Consecutive putText are coalesced into a single text node. A putText with length 0 creates no text node.
- Comment: putComment creates a comment node.
- Processing instruction: putProcessingInstruction.
- End of element: putElementEnd. Should match the opening putElementStart.
- End of document: putDocumentEnd.

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` | `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.

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

### 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

### 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:
    `prefix` -
  Returns:
    an URI or null

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| © 2010 Axyana Software
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD