Interface Container
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 TypeMethodDescriptionvoid
close()
Close the current document or element container.comment
(CharSequence value) Add a comment node to the current element or document node.Start an element node, with a specified local name.Start an element node, with a specified prefix, namespace URI, and local name.processingInstruction
(String name, CharSequence value) Add a processing instruction node to the current element or document node.void
Set the default namespace for a section of the document.text
(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 Details
-
setDefaultNamespace
Set the default namespace for a section of the document. This applies to all subsequentelement(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 formxmlns="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
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
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 onsetDefaultNamespace(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
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 totext("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
Add a comment node to the current element or document node.The method call is allowed in states
START_TAG
,CONTENT
, andNON_TEXT_CONTENT
, and it sets the state toCONTENT
.- 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
Add a processing instruction node to the current element or document node.The method call is allowed in states
START_TAG
,CONTENT
, andNON_TEXT_CONTENT
, and it sets the state toCONTENT
.- 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
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
-