dk.brics.xact
Class XML

java.lang.Object
  dk.brics.xact.Node
      dk.brics.xact.XML

All Implemented Interfaces:

ToXMLable

Direct Known Subclasses:

OperationNode, TempNode

public abstract class XML
extends Node
implements ToXMLable

XML template content node.

This class contains the main functionality of the XACT runtime system. See also the general documentation for the package dk.brics.xact.

Constructor Summary

protected

XML(Origin origin) Constructs a new template node.

Method Summary

XML	analyze(String type) Instruction for the program analyzer; no operation at runtime.
XML	append(Object v) Inserts the given value after this template.
XML	appendContent(Object v) Inserts the given value after the content of this element.
XML	appendContent(String xpath, Object v) Inserts the given value after the content of each selected element node.
int	byteLength(String encoding) Computes the number of bytes written if invoking toDocument(OutputStream, String).
XML	close() Removes all gaps in this template.
static XML	concat(Iterable<?> vs) Concatenates the given list of XML templates or strings into one template.
static XML	concat(Object... xs) Concatenates the given list of XML templates or strings.
(package private) static XML	concatXML(XML x1, XML x2) Concatenates the given XML templates.
XML	gapify(String xpath, String gap) Converts all nodes selected by the given XPath expression into gaps of the given name.
XML	gapify(String xpath, String gap, String type) Converts all nodes selected by the given XPath expression into gaps of the given name and schema type.
NodeList<Node>	get(String xpath) Returns the nodes specified by the given XPath expression.
String	getAttribute(String localname) Returns the value of the attribute of the given name in the first element in this template, or null if not present.
String	getAttribute(String namespace, String localname) Returns the value of the attribute of the given name in the first element in this template, or null if not present.
Element	getElement(String xpath) Returns the first element specified by the given XPath expression.
Element	getElementByID(String id) Returns the element with the given ID.
NodeList<Element>	getElements(String xpath) Returns the elements specified by the given XPath expression.
Element	getFirstElement() Returns the first element in this template.
static Map<String,String>	getNamespaceMap() Returns the global namespace map (from prefix to URI).
XML	getNextSibling() Returns the next sibling node, or null if none.
Number	getNumber() Returns the number value of the first element or text node in this template.
Number	getNumber(String xpath) Returns the number specified by the given XPath expression.
(package private) XML	getRealNextSibling() Returns the next sibling, without normalizing.
String	getString() Returns the string value of the first element or text node in this template.
String	getString(String xpath) Returns the text specified by the given XPath expression.
List<String>	getStrings(String xpath) Returns the text or attribute values specified by the given XPath expression.
static Map<String,String>	getThreadNamespaceMap() Returns the thread local namespace map (from prefix to URI).
boolean	has(String xpath) Returns the boolean specified by the given XPath expression.
XML	insertAfter(String xpath, Object v) Inserts the given value after each selected content node.
XML	insertBefore(String xpath, Object v) Inserts the given value before each selected content node.
static void	loadXMLSchema(String url) Loads an XML schema.
static void	loadXMLSchema(URL url) Loads an XML schema.
(package private) static TempNode	normalize(XML x) Normalizes the given node if it is an operation node.
static XML	parseDocument(InputStream in) Constructs an XML document from its string representation from an input stream.
static XML	parseDocument(InputStream in, String encoding, Origin origin) Constructs an XML document from its string representation from an input stream using the given encoding.
static XML	parseDocument(String doc) Constructs an XML document from its string representation.
static XML	parseDocument(URL url) Constructs an XML document from its string representation from a URL.
static XML	parseTemplate(InputStream in) Constructs an XML template from its string representation from an input stream.
static XML	parseTemplate(InputStream in, Origin origin) Constructs an XML template from its string representation from an input stream.
static XML	parseTemplate(String template) Constructs an XML template from its string representation.
static XML	parseTemplate(String template, Origin origin) Constructs an XML template from its string representation.
static XML	parseTemplateResource(Class<?> base, String name) Constructs an XML template from its string representation located in a resource.
static XML	parseTemplateResource(String name) Constructs an XML template from its string representation located in a resource.
XML	plug(String gap, Object v) Constructs a new XML template by plugging the given value into each template gap of the given name in this template.
XML	plugList(String gap, Iterable<?> vs) Constructs a new XML template by plugging the given list of values into the list of template gaps of the given name in this template.
XML	plugWrap(String gap, Iterable<?> vs) Constructs a template by wrapping each value from the given list into the gaps of the given name in this template and concatenating the results.
XML	prepend(Object v) Inserts the given value in front of this template.
XML	prependContent(Object v) Inserts the given value before the content of this element.
XML	prependContent(String xpath, Object v) Inserts the given value before the content of each selected element node.
XML	remove(String xpath) Removes the nodes selected by the given XPath expression.
XML	set(AttrNode a) Sets an attribute at this element.
XML	set(NamespaceDecl d) Sets a namespace declaration at this element.
XML	set(String xpath, AttrNode a) Sets an attribute at each selected element node.
XML	set(String xpath, Object v) Replaces each selected content node by the given value.
XML	setContent(Object v) Sets the content of this element to the given value.
XML	setContent(String xpath, Object v) Sets the content of each selected element node to the given value.
String	toDocument() Converts this XML template to its string representation with all gaps removed.
void	toDocument(OutputStream out, String encoding) Converts this XML template to its string representation with all gaps removed and prints the result to an output stream.
String	toDocument(String encoding) Converts this XML template to its string representation with all gaps removed, using the given encoding.
String	toDocument(XMLIndentation indentation) Converts this XML template to its string representation with all gaps removed, using the given encoding.
String	toTemplate() Converts this template to its string representation.
String	toTemplate(String encoding) Converts this template to its string representation, using the given encoding.
String	toTemplate(XMLIndentation indentation) Converts this template to its string representation, using the specified indentation strategy.
XML	toXML() Returns this object.
static XML	toXML(Object v) Converts the given value to an XML template using ToXMLable.toXML() or Node.toString().
XML	validate(String type) Checks that this template is valid according to the given schema type.
void	visitBy(NodeVisitor v) Visits this node by the given visitor.
<R,A> R	visitBy(NodeVisitorParameterized<R,A> v, A arg) Visits this node by the given visitor.

Methods inherited from class dk.brics.xact.Node

asAttribute, asComment, asElement, asNamespaceDecl, asProcessingInstruction, asTemplate, asText, expanded, follow, follow, follow, follow, forward, getOrigin, isAttribute, isComment, isElement, isNamespaceDecl, isProcessingInstruction, isTemplate, isText, toString, visitAnyBy, visitNormalizedBy, visitNormalizedBy

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

XML

protected XML(Origin origin)

Constructs a new template node.

Method Detail

analyze

public XML analyze(String type)

Instruction for the program analyzer; no operation at runtime. At analysis-time, the static analyzer will check validity of this template relative to the given schema type.

Returns:

this XML template

See Also:

validate(String)

append

public XML append(Object v)

Inserts the given value after this template.

See Also:

insertAfter(String, Object), prepend(Object)

appendContent

public XML appendContent(Object v)

Inserts the given value after the content of this element.

Throws:

ClassCastException - if this is not an element node

See Also:

appendContent(String, Object), prependContent(Object)

appendContent

public XML appendContent(String xpath,
                         Object v)

Inserts the given value after the content of each selected element node.

See Also:

appendContent(Object), prependContent(String, Object)

byteLength

public int byteLength(String encoding)
               throws UnsupportedEncodingException

Computes the number of bytes written if invoking toDocument(OutputStream, String).

Throws:

XMLWellformednessException - if the result is not a wellformed XML document

UnsupportedEncodingException - if the encoding is not supported

close

public final XML close()

Removes all gaps in this template.

See Also:

plug(String, Object), plugList(String, Iterable), plugWrap(String, Iterable)

concat

public static XML concat(Iterable<?> vs)

Concatenates the given list of XML templates or strings into one template.

See Also:

concat(Object...)

concat

public static XML concat(Object... xs)

Concatenates the given list of XML templates or strings.

See Also:

concat(Iterable)

concatXML

static XML concatXML(XML x1,
                     XML x2)

Concatenates the given XML templates.

gapify

public XML gapify(String xpath,
                  String gap)

Converts all nodes selected by the given XPath expression into gaps of the given name.

See Also:

gapify(String, String, String)

gapify

public XML gapify(String xpath,
                  String gap,
                  String type)

Converts all nodes selected by the given XPath expression into gaps of the given name and schema type.

See Also:

gapify(String, String)

get

public final NodeList<Node> get(String xpath)

Returns the nodes specified by the given XPath expression. The initial context node is this node. The document root node is an implicit node that has this node and its siblings as content. The nodes are returned in document order.

See Also:

getElements(String), getElement(String), getString(String), has(String)

getAttribute

public String getAttribute(String localname)

Returns the value of the attribute of the given name in the first element in this template, or null if not present.

See Also:

get(String), getAttribute(String, String)

getAttribute

public String getAttribute(String namespace,
                           String localname)

Returns the value of the attribute of the given name in the first element in this template, or null if not present.

See Also:

get(String), getAttribute(String)

getElement

public final Element getElement(String xpath)

Returns the first element specified by the given XPath expression.

See Also:

get(String), getFirstElement()

getElementByID

public final Element getElementByID(String id)

Returns the element with the given ID.

See Also:

getElement(String)

getElements

public final NodeList<Element> getElements(String xpath)

Returns the elements specified by the given XPath expression. The elements are returned in document order.

See Also:

get(String), getElement(String), getStrings(String), getString(String), has(String)

getFirstElement

public Element getFirstElement()

Returns the first element in this template.

See Also:

getElement(String)

getNamespaceMap

public static Map<String,String> getNamespaceMap()

Returns the global namespace map (from prefix to URI). The map is modifiable. The empty prefix string represents the default namespace.

See Also:

getThreadNamespaceMap()

getNextSibling

public XML getNextSibling()

Returns the next sibling node, or null if none.

getNumber

public Number getNumber()

Returns the number value of the first element or text node in this template.

See Also:

get(String), getNumber(String), getString()

getNumber

public Number getNumber(String xpath)

Returns the number specified by the given XPath expression. If multiple nodes are selected, only the first one is considered. The value is determined per the number(..) core function as defined in the XPath 1.0 specification.

See Also:

get(String), getNumber()

getRealNextSibling

XML getRealNextSibling()

Returns the next sibling, without normalizing. Overridden in subclasses that can have a next sibling.

getString

public String getString()

Returns the string value of the first element or text node in this template.

See Also:

getString(String)

getString

public String getString(String xpath)

Returns the text specified by the given XPath expression. If multiple nodes are selected, only the first one is considered. The value is determined per the string(..) core function as defined in the XPath 1.0 specification.

See Also:

getString(), get(String), getElement(String)

getStrings

public List<String> getStrings(String xpath)

Returns the text or attribute values specified by the given XPath expression. Each string value is determined per the string(..) core function as defined in the XPath 1.0 specification. The strings are returned in document order. The returned list is unmodifiable.

See Also:

get(String), getElements(String), getString(String)

getThreadNamespaceMap

public static Map<String,String> getThreadNamespaceMap()

Returns the thread local namespace map (from prefix to URI). The map is modifiable. The empty prefix string represents the default namespace. Overrides the global namespace map for this thread.

See Also:

getNamespaceMap()

has

public boolean has(String xpath)

Returns the boolean specified by the given XPath expression. If multiple nodes are selected, only the first one is considered. The value is determined per the boolean(..) core function as defined in the XPath 1.0 specification.

See Also:

get(String)

insertAfter

public XML insertAfter(String xpath,
                       Object v)

Inserts the given value after each selected content node.

See Also:

insertBefore(String, Object), append(Object), appendContent(String, Object)

insertBefore

public XML insertBefore(String xpath,
                        Object v)

Inserts the given value before each selected content node.

See Also:

insertAfter(String, Object), prepend(Object), prependContent(String, Object)

loadXMLSchema

public static void loadXMLSchema(String url)

Loads an XML schema. Supported schema languages: DTD, XML Schema, and Restricted RELAX NG.

loadXMLSchema

public static void loadXMLSchema(URL url)

Loads an XML schema. Supported schema languages: DTD, XML Schema, and Restricted RELAX NG.

normalize

static TempNode normalize(XML x)

Normalizes the given node if it is an operation node. Also merges adjacent text nodes and non-last empty text nodes. Do never inspect the type of a node before invoking this method.

parseDocument

public static XML parseDocument(InputStream in)

Constructs an XML document from its string representation from an input stream. Assumes UTF-8 encoding. (The global and thread local namespace declarations are not considered, and gaps are not recognized.)

Throws:

XMLTemplateException - if the string is not a syntactically wellformed XML document

See Also:

parseDocument(InputStream, String, Origin), parseDocument(String), toDocument(OutputStream, String)

parseDocument

public static XML parseDocument(InputStream in,
                                String encoding,
                                Origin origin)

Constructs an XML document from its string representation from an input stream using the given encoding. (The global and thread local namespace declarations are not considered, and gaps are not recognized.)

Throws:

XMLTemplateException - if the string is not a syntactically wellformed XML document

See Also:

parseDocument(InputStream), parseDocument(String), toDocument(OutputStream, String)

parseDocument

public static XML parseDocument(String doc)

Constructs an XML document from its string representation. Assumes UTF-8 encoding. (The global and thread local namespace declarations are not considered, and gaps are not recognized.)

Throws:

XMLTemplateException - if the string is not a syntactically wellformed XML document

See Also:

parseDocument(InputStream)

parseDocument

public static XML parseDocument(URL url)

Constructs an XML document from its string representation from a URL. Assumes UTF-8 encoding. (The global and thread local namespace declarations are not considered, and gaps are not recognized.)

Throws:

XMLTemplateException - if the string is not a syntactically wellformed XML document

See Also:

parseDocument(InputStream, String, Origin), parseDocument(String), toDocument(OutputStream, String)

parseTemplate

public static XML parseTemplate(InputStream in)

Constructs an XML template from its string representation from an input stream. Assumes UTF-8 encoding. The program analysis requires the string to be constant. The global and thread local namespace declarations are used, and gaps are recognized.

Throws:

XMLTemplateException - if the string is not a syntactically wellformed XML template

See Also:

parseDocument(String)

parseTemplate

public static XML parseTemplate(InputStream in,
                                Origin origin)

Constructs an XML template from its string representation from an input stream. Assumes UTF-8 encoding. The program analysis requires the string to be constant. The global and thread local namespace declarations are used, and gaps are recognized.

Throws:

XMLTemplateException - if the string is not a syntactically wellformed XML template

See Also:

parseDocument(String)

parseTemplate

public static XML parseTemplate(String template)

Constructs an XML template from its string representation. The program analysis requires the string to be constant. The global and thread local namespace declarations are used, and gaps are recognized. Results are cached in memory.

Throws:

XMLTemplateException - if the string is not a syntactically wellformed XML template

See Also:

parseDocument(String), parseTemplate(String, Origin)

parseTemplate

public static XML parseTemplate(String template,
                                Origin origin)

Constructs an XML template from its string representation. The program analysis requires the string to be constant. The global and thread local namespace declarations are used, and gaps are recognized. Results are cached in memory (using the template string as key).

Throws:

XMLTemplateException - if the string is not a syntactically wellformed XML template

See Also:

parseDocument(String), parseTemplate(InputStream, Origin)

parseTemplateResource

public static XML parseTemplateResource(Class<?> base,
                                        String name)

Constructs an XML template from its string representation located in a resource. Assumes UTF-8 encoding. The program analysis requires the string to be constant. The global and thread local namespace declarations are used, and gaps are recognized. Uses base.getResourceAsStream to load the string. Results are cached in memory.

Throws:

XMLTemplateException - if the string is not a syntactically wellformed XML template or the resource is not found

See Also:

parseDocument(String)

parseTemplateResource

public static XML parseTemplateResource(String name)

Constructs an XML template from its string representation located in a resource. Assumes UTF-8 encoding. The program analysis requires the string to be constant. The global and thread local namespace declarations are used, and gaps are recognized. Uses XML.class.getResourceAsStream to load the string. Results are cached in memory.

Throws:

XMLTemplateException - if the string is not a syntactically wellformed XML template or the resource is not found

See Also:

parseDocument(String)

plug

public final XML plug(String gap,
                      Object v)

Constructs a new XML template by plugging the given value into each template gap of the given name in this template.

Throws:

NullPointerException - if the value is null

See Also:

plugList(String, Iterable), plugWrap(String, Iterable), close()

plugList

public final XML plugList(String gap,
                          Iterable<?> vs)

Constructs a new XML template by plugging the given list of values into the list of template gaps of the given name in this template. If too many values are provided, the remaining ones are ignored. If too few are provided, the remaining gaps are removed.

Throws:

NullPointerException - if one of the values is null

See Also:

plug(String, Object), plugWrap(String, Iterable), close()

plugWrap

public final XML plugWrap(String gap,
                          Iterable<?> vs)

Constructs a template by wrapping each value from the given list into the gaps of the given name in this template and concatenating the results.

Throws:

NullPointerException - if one of the values is null

See Also:

plug(String, Object), plugList(String, Iterable), close()

prepend

public XML prepend(Object v)

Inserts the given value in front of this template.

See Also:

insertBefore(String, Object), append(Object)

prependContent

public XML prependContent(Object v)

Inserts the given value before the content of this element.

Throws:

ClassCastException - if this is not an element node

See Also:

prependContent(String, Object), appendContent(Object)

prependContent

public XML prependContent(String xpath,
                          Object v)

Inserts the given value before the content of each selected element node.

See Also:

prependContent(Object), appendContent(String, Object)

remove

public XML remove(String xpath)

Removes the nodes selected by the given XPath expression.

See Also:

gapify(String, String)

set

public XML set(AttrNode a)

Sets an attribute at this element.

Throws:

ClassCastException - if this is not an element node

See Also:

set(String, AttrNode)

set

public XML set(NamespaceDecl d)

Sets a namespace declaration at this element.

Throws:

ClassCastException - if this is not an element node

set

public XML set(String xpath,
               AttrNode a)

Sets an attribute at each selected element node.

See Also:

set(AttrNode)

set

public XML set(String xpath,
               Object v)

Replaces each selected content node by the given value.

See Also:

appendContent(Object), prependContent(String, Object), setContent(String, Object), set(String, AttrNode)

setContent

public XML setContent(Object v)

Sets the content of this element to the given value.

Throws:

ClassCastException - if this is not an element node

See Also:

appendContent(String, Object), prependContent(Object)

setContent

public XML setContent(String xpath,
                      Object v)

Sets the content of each selected element node to the given value.

See Also:

appendContent(Object), prependContent(String, Object), set(String, Object)

toDocument

public String toDocument()

Converts this XML template to its string representation with all gaps removed. Uses UTF-8 encoding. The output contains an XML declaration.

See Also:

toTemplate(), toDocument(String)

toDocument

public void toDocument(OutputStream out,
                       String encoding)
                throws UnsupportedEncodingException

Converts this XML template to its string representation with all gaps removed and prints the result to an output stream. The output contains an XML declaration.

Throws:

XMLWellformednessException - if the result is not a wellformed XML document

UnsupportedEncodingException - if the encoding is not supported

See Also:

parseDocument(InputStream)

toDocument

public String toDocument(String encoding)
                  throws UnsupportedEncodingException

Converts this XML template to its string representation with all gaps removed, using the given encoding. The output contains an XML declaration.

Throws:

XMLWellformednessException - if the result is not a wellformed XML document

UnsupportedEncodingException - if the encoding is not supported

See Also:

toDocument(), toTemplate(String)

toDocument

public String toDocument(XMLIndentation indentation)

Converts this XML template to its string representation with all gaps removed, using the given encoding. The output contains an XML declaration.

Throws:

XMLWellformednessException - if the result is not a wellformed XML document

See Also:

toDocument(), toTemplate(XMLIndentation)

toTemplate

public String toTemplate()

Converts this template to its string representation. Uses UTF-8 encoding. Unlike Node.toString(), gaps are preserved in the output.

See Also:

Node.toString(), toTemplate(String)

toTemplate

public String toTemplate(String encoding)
                  throws UnsupportedEncodingException

Converts this template to its string representation, using the given encoding. Unlike toDocument(), gaps are preserved in the output.

Throws:

UnsupportedEncodingException

See Also:

toDocument(String), toTemplate()

toTemplate

public String toTemplate(XMLIndentation indentation)

Converts this template to its string representation, using the specified indentation strategy. Uses UTF-8 encoding. Unlike toDocument(), gaps are preserved in the output.

See Also:

Node.toString(), toTemplate(String)

toXML

public XML toXML()

Returns this object.

Specified by:

toXML in interface ToXMLable

toXML

public static XML toXML(Object v)

Converts the given value to an XML template using ToXMLable.toXML() or Node.toString().

validate

public XML validate(String type)
             throws XMLValidationException

Checks that this template is valid according to the given schema type.

Returns:

this XML template

Throws:

XMLValidationException - if the template is invalid

See Also:

analyze(String)

visitBy

public final void visitBy(NodeVisitor v)

Description copied from class: Node

Visits this node by the given visitor.

Overrides:

visitBy in class Node

visitBy

public final <R,A> R visitBy(NodeVisitorParameterized<R,A> v,
                             A arg)

Description copied from class: Node

Visits this node by the given visitor.

Overrides:

visitBy in class Node