net.sf.saxon.s9api

Interface Push.Container

All Known Subinterfaces:

Push.Document, Push.Element

Enclosing interface:

Push

public static interface Push.Container

The Container interface represents a document node or element node under construction; there are concrete subclasses representing document nodes and element nodes respectively.

Method Summary

Modifier and Type	Method and Description
void	close() Close the current document or element container.
Push.Container	comment(java.lang.CharSequence value) Add a comment node to the current element or document node.
Push.Element	element(QName name) Start an element node, with a specified prefix, namespace URI, and local name.
Push.Element	element(java.lang.String name) Start an element node, with a specified local name.
Push.Container	processingInstruction(java.lang.String name, java.lang.CharSequence value) Add a processing instruction node to the current element or document node.
void	setDefaultNamespace(java.lang.String uri) Set the default namespace for a section of the document.
Push.Container	text(java.lang.CharSequence value) Add text content to the current element node (or, in the case of a non-well-formed document, as a child of the document node).

Method Detail

setDefaultNamespace

void setDefaultNamespace(java.lang.String uri)

Set the default namespace for a section of the document. This applies to all subsequent element(String) or #element(QName)} calls, and is inherited by inner elements unless overridden by another call that sets a different value.

Setting the default namespace has the effect that within its scope, on any call on element(String), the supplied string is taken as being a local name in the current default namespace. A default namespace declaration in the form xmlns="uri" will appear on any element where it is not redundant.

If the method is called repeatedly on the same Container, then the most recent call applies.

Parameters:

uri - the namespace URI to be used as the default namespace for the subsequent elements. The value may be a zero-length string or null, indicating that the default within the scope of this call is for elements to be in no namespace.

element

Push.Element element(QName name)
              throws SaxonApiException

Start an element node, with a specified prefix, namespace URI, and local name.

The level of validation applied to the supplied names is implementation-defined.

Parameters:

name - The name of the element, as a non-null QName (which may contain prefix, namespace URI, and local name). An empty string as the prefix represents the default namespace; an empty string as the namespace URI represents no namespace. If the namespace is empty then the prefix must also be empty.

A namespace declaration binding the prefix to the namespace URI will be generated unless it is redundant.

If the prefix is empty and the namespace is not the default namespace established using setDefaultNamespace(String), then the prefix will be substituted with a system-allocated prefix. The prefix and namespace URI used on this method call do not affect the namespace context for any elements other than this one.

Returns:

a new Tag representing the new element node

Throws:

SaxonApiException - if the specified constraints are violated, or if the implementation detects any problems

element

Push.Element element(java.lang.String name)
              throws SaxonApiException

Start an element node, with a specified local name. The element will be in the default namespace if one has been established; otherwise it will be in no namespace.

The level of validation applied to the supplied name is implementation-defined.

Parameters:

name - The local name of the element, as a non-null string. If a default namespace has been established by a call on setDefaultNamespace(String) then the element will be in that namespace; otherwise it will be in no namespace.

Returns:

a new Tag representing the new element node

Throws:

SaxonApiException - if the specified constraints are violated, or if the implementation detects any problems

text

Push.Container text(java.lang.CharSequence value)
             throws SaxonApiException

Add text content to the current element node (or, in the case of a non-well-formed document, as a child of the document node).

Multiple consecutive calls on text() generate a single text node with concatenated content: that is, text("one).text("two") is equivalent to text("onetwo").

Parameters:

value - the content of the text node. Supplying a zero-length string or null is permitted, but has no effect.

Returns:

the Container to which the method is applied. This is to allow chained method calls, of the form tag.element("a").text("content").close()

Throws:

SaxonApiException - if the specified constraints are violated, or if the implementation detects any problems

comment

Push.Container comment(java.lang.CharSequence value)
                throws SaxonApiException

Add a comment node to the current element or document node.

The method call is allowed in states START_TAG, CONTENT, and NON_TEXT_CONTENT, and it sets the state to CONTENT.

Parameters:

value - the content of the comment node. The value should not contain the string "--"; it is implementation-defined whether this causes an exception, or whether some recovery action is taken such as replacing the string by "- -". If the value is null, no comment node is written.

Returns:

the Container to which the method is applied. This is to allow chained method calls, of the form tag.element("a").comment("optional").close()

Throws:

SaxonApiException - if the specified constraints are violated, or if the implementation detects any problems

processingInstruction

Push.Container processingInstruction(java.lang.String name,
                                     java.lang.CharSequence value)
                              throws SaxonApiException

Add a processing instruction node to the current element or document node.

The method call is allowed in states START_TAG, CONTENT, and NON_TEXT_CONTENT, and it sets the state to CONTENT.

Parameters:

name - the name ("target") of the processing instruction. The level of validation applied to the supplied name is implementation-defined. Must not be null.

value - the content ("data") of the processing instruction node. The value should not contain the string "?>"; it is implementation-defined whether this causes an exception, or whether some recovery action is taken such as replacing the string by "? >". If the value is null, no processing instruction node is written.

Returns:

the Container to which the method is applied. This is to allow chained method calls, of the form tag.element("a").processing-instruction("target", "data").close()

Throws:

SaxonApiException - if the specified constraints are violated, or if the implementation detects any problems

close

void close()
    throws SaxonApiException

Close the current document or element container.

Closing a container more than once has no effect.

Adding any content to a node after it has been closed causes an exception.

Closing a node implicitly closes any unclosed children of the node.

Throws:

SaxonApiException - if a downstream recipient of the data reports a failure