nux.xom.xquery
Class ResultSequenceSerializer

java.lang.Object
  nux.xom.xquery.ResultSequenceSerializer

public class ResultSequenceSerializer
extends Object

Serializes an XQuery/XPath result sequence onto a given output stream, using various configurable serialization options such encoding, indentation and algorithm. The semantics of options are identical to the XOM Serializer, except the "algorithm" option.

The W3C algorithm serializes each item in the result sequence according to the XML Output Method of the W3C XQuery/XSLT2 Serialization Spec, with sequence normalization as defined therein. As such, it may output data that is not a well-formed document. For example, if the result sequence contains more than one element then a document with more than one root element will be output. However, for some use cases the algorithm does indeed output a well-formed XML document. For example, if the result sequence contains a single document or element node. Finally, note that an exception is thrown if the result sequence contains a (top-level) attribute node.

In contrast, the wrap algorithm wraps each item in the result sequence into a decorated element wrapper, thereby ensuring that any arbitrary result sequence can always be output as a well-formed XML document. This enables easy processing in subsequent XML processing pipeline stages. Unlike the W3C algorithm, the wrap algorithm does not perform sequence normalization. Thus, wrapping is better suited for XQuery debugging purposes, because one can see exactly what items a query does (or does not) return.

Example usage:

 Document doc = new Builder().build(new File("samples/data/p2pio-receive.xml"));
 Nodes results = XQueryUtil.xquery(doc, "//*");
 // Nodes results = XQueryUtil.xquery(doc, "//node(), //@*, 'Hello World!'");
 ResultSequenceSerializer ser = new ResultSequenceSerializer();
 ser.setEncoding("UTF-8");
 ser.setIndent(4);
 ser.setAlgorithm(ResultSequenceSerializer.W3C_ALGORITHM);
 // ser.setAlgorithm(ResultSequenceSerializer.WRAP_ALGORITHM);
 ser.write(results, System.out);
 

Author:

whoschek.AT.lbl.DOT.gov, $Author: hoschek3 $

Field Summary

static String	W3C_ALGORITHM Serializes each item in the result sequence according to the XML Output Method of the W3C XQuery/XSLT2 Serialization Draft Spec, with sequence normalization as defined therein.
static String	WRAP_ALGORITHM Serializes each item in the result sequence by wrapping it into a decorated element, without sequence normalization.

Constructor Summary

ResultSequenceSerializer()
Constructs and returns a serializer with default options.

Method Summary

String	getAlgorithm() Returns the current serialization algorithm; Can be W3C_ALGORITHM or WRAP_ALGORITHM; Defaults to W3C_ALGORITHM.
String	getEncoding() Returns the current serialization character encoding; Defaults to "UTF-8"; For details, see Serializer.Serializer(OutputStream, String).
int	getIndent() Returns the number of spaces to insert for each nesting level for pretty printing purposes; Defaults to zero; For details, see Serializer.setIndent(int).
boolean	getUnicodeNormalizationFormC() Returns whether or not to perform Unicode normalization form C (NFC); Defaults to false; For details, see Serializer.setUnicodeNormalizationFormC(boolean)
void	setAlgorithm(String algorithm) Sets the serialization algorithm.
void	setEncoding(String encoding) Sets the character encoding for the serialization.
void	setIndent(int indent) Sets the number of spaces to insert for each nesting level.
void	setUnicodeNormalizationFormC(boolean nfc) Sets whether or not to perform Unicode normalization form C (NFC).
String	toString() Returns a string representation for debugging purposes.
void	write(Nodes nodes, OutputStream out) Serializes the given result sequence onto the given output stream.

Methods inherited from class java.lang.Object

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

Field Detail

W3C_ALGORITHM

public static final String W3C_ALGORITHM

Serializes each item in the result sequence according to the XML Output Method of the W3C XQuery/XSLT2 Serialization Draft Spec, with sequence normalization as defined therein.

See Also:

Constant Field Values

WRAP_ALGORITHM

public static final String WRAP_ALGORITHM

Serializes each item in the result sequence by wrapping it into a decorated element, without sequence normalization.

See Also:

Constant Field Values

Constructor Detail

ResultSequenceSerializer

public ResultSequenceSerializer()

Constructs and returns a serializer with default options.

Method Detail

getAlgorithm

public String getAlgorithm()

Returns the current serialization algorithm; Can be W3C_ALGORITHM or WRAP_ALGORITHM; Defaults to W3C_ALGORITHM.

Returns:

the current algorithm

getIndent

public int getIndent()

Returns the number of spaces to insert for each nesting level for pretty printing purposes; Defaults to zero; For details, see Serializer.setIndent(int).

Returns:

the current the number of spaces

getEncoding

public String getEncoding()

Returns the current serialization character encoding; Defaults to "UTF-8"; For details, see Serializer.Serializer(OutputStream, String).

Returns:

the current encoding

getUnicodeNormalizationFormC

public boolean getUnicodeNormalizationFormC()

Returns whether or not to perform Unicode normalization form C (NFC); Defaults to false; For details, see Serializer.setUnicodeNormalizationFormC(boolean)

Returns:

whether or not to perform NFC

setAlgorithm

public void setAlgorithm(String algorithm)

Sets the serialization algorithm.

Parameters:

algorithm - the serialization algorithm to use

setEncoding

public void setEncoding(String encoding)

Sets the character encoding for the serialization.

Parameters:

encoding - the encoding to use

setIndent

public void setIndent(int indent)

Sets the number of spaces to insert for each nesting level.

Parameters:

indent - the indentation to use (must be >= 0)

setUnicodeNormalizationFormC

public void setUnicodeNormalizationFormC(boolean nfc)

Sets whether or not to perform Unicode normalization form C (NFC).

Parameters:

nfc - true to normalize with NFC, false otherwise.

toString

public String toString()

Returns a string representation for debugging purposes.

Overrides:

toString in class Object

Returns:

a string representation

write

public void write(Nodes nodes,
                  OutputStream out)
           throws IOException

Serializes the given result sequence onto the given output stream. This method does not auto-close the output stream.

Parameters:

nodes - the result sequence to serialize

out - the stream to write to

Throws:

IOException - if an I/O error occured