Saxon.Api
Class Serializer
-
public class Serializer
- implements IDestination
A Serializer
takes a tree representation of XML and turns
it into lexical XML markup.
Note that this is serialization in the sense of the W3C XSLT and XQuery specifications.
Unlike the class System.Xml.Serialization.XmlSerializer
, this object does not
serialize arbitrary CLI objects.
Field Summary |
|
---|---|
static QName | BUILD_TREE Build-tree option (XSLT only) |
static QName | BYTE_ORDER_MARK QName identifying the serialization parameter "byte-order-mark". The value is the string "yes" or "no". |
static QName | CDATA_SECTION_ELEMENTS QName identifying the serialization parameter "cdata-section-elements". The value of this parameter is given as a space-separated list of expanded QNames in Clark notation, that is "{uri}local". |
static QName | DOCTYPE_PUBLIC QName identifying the serialization parameter "doctype-public" |
static QName | DOCTYPE_SYSTEM QName identifying the serialization parameter "doctype-system" |
static QName | ENCODING QName identifying the serialization parameter "encoding" |
static QName | ESCAPE_URI_ATTRIBUTES QName identifying the serialization parameter "escape-uri-attributes". The value is the string "yes" or "no". |
static QName | HTML_VERSION HTML version number |
static QName | INCLUDE_CONTENT_TYPE QName identifying the serialization parameter "include-content-type". The value is the string "yes" or "no". |
static QName | INDENT QName identifying the serialization parameter "indent". The value is the string "yes" or "no". |
static QName | ITEM_SEPARATOR Set to a string used to separate adjacent items in an XQuery result sequence |
static QName | MEDIA_TYPE QName identifying the serialization parameter "media-type". |
static QName | METHOD QName identifying the serialization parameter "method". If the value is a user-defined method, then it is given as a QName in Clark notation, that is "{uri}local". |
static QName | NEXT_IN_CHAIN QName identifying the serialization parameter "saxon:next-in-chain". This is available only with XSLT, and identifies the URI of a stylesheet that is to be used to process the results before passing them to their final destination. |
static QName | NORMALIZATION_FORM QName identifying the serialization parameter "normalization-form" |
static QName | OMIT_XML_DECLARATION QName identifying the serialization parameter "omit-xml-declaration". The value is the string "yes" or "no". |
static QName | SAXON_ATTRIBUTE_ORDER Saxon extension: set to a space-separated list of attribute names, in Clark notation, indicating that attributes present in the list should be serialized in the order indicated, followed by attributes not present in the list(these are sorted first by namespace, then by local name). |
static QName | SAXON_CANONICAL Saxon extension: request canonical XML output. |
static QName | SAXON_CHARACTER_REPRESENTATION QName identifying the serialization parameter "saxon:character-representation" |
static QName | SAXON_DOUBLE_SPACE QName identifying the serialization parameter "saxon:double-space". The value of this parameter is given as a space-separated list of expanded QNames in Clark notation, that is "{uri}local"; each QName identifies an element that should be preceded by an extra blank line within indented output. |
static QName | SAXON_INDENT_SPACES QName identifying the serialization parameter "saxon:indent-spaces". The value is an integer (represented as a string) indicating the amount of indentation required. If specified, this parameter overrides indent="no". |
static QName | SAXON_LINE_LENGTH Saxon extension: set to an integer (represented as a string) giving the desired maximum length of lines when indenting.Default is 80. |
static QName | SAXON_NEWLINE Saxon extension: set to any string. Indicates the sequence of characters used to represent a newline in the text output method, and in newlines used for indentation in any output methods that use indentation. |
static QName | SAXON_RECOGNIZE_BINARY Saxon extension for use when writing to the text output method; this option causes the processing instructions hex and b64 to be recognized containing hexBinary or base64 data respectively. |
static QName | SAXON_REQUIRE_WELL_FORMED QName identifying the serialization parameter "saxon:require-well-formed". The value is the string "yes" or "no". If set to "yes", the output must be a well-formed document, or an error will be reported. ("Well-formed" here means that the document node must have exactly one element child, and no text node children other than whitespace-only text nodes). |
static QName | SAXON_STYLESHEET_VERSION Saxon extension for internal use: used in XSLT to tell the serializer whether the stylesheet used version="1.0" or version = "2.0" |
static QName | SAXON_SUPPRESS_INDENTATION QName identifying the serialization parameter "suppress-indentation". Retained as a synonym of SUPPRESS_INDENTATION for backwards compatibility. |
static QName | SAXON_WRAP Saxon extension, indicates that the output of a query is to be wrapped before serialization, such that each item in the result sequence is enclosed in an element indicating its type |
static QName | STANDALONE QName identifying the serialization parameter "standalone". The value is the string "yes" or "no" or "omit". |
static QName | SUPPLY_SOURCE_LOCATOR Saxon extension for interfacing with debuggers; indicates that the location information is available for events in this output stream |
static QName | SUPPRESS_INDENTATION QName identifying the serialization parameter "suppress-indentation" (introduced in XSLT/XQuery 3.0). Previously available as "saxon:suppress-indentation". The value is the string "yes" or "no". |
static QName | UNDECLARE_PREFIXES QName identifying the serialization parameter "undeclare-prefixes". The value is the string "yes" or "no". |
static QName | USE_CHARACTER_MAPS QName identifying the serialization parameter "use-character-maps". The value of the parameter is a list of expanded QNames in Clark notation giving the names of character maps defined in the XSLT stylesheet, or supplied programmatically. |
static QName | VERSION QName identifying the serialization parameter "version" |
Property Summary |
|
---|---|
Uri | BaseUri This property determines the base Uri of the constructed |
string | OutputFile Specify the destination of the serialized output, in the form of a file name |
Stream | OutputStream Specify the destination of the serialized output, in the
form of a |
TextWriter | OutputWriter Specify the destination of the serialized output, in the
form of a |
Processor | Processor The Processor from which this |
net.sf.saxon.s9api.Destination | UnderlyingDestination
The underlying |
Method Summary |
|
---|---|
void | Close () Close any resources associated with this destination. Note that this does not close any user-supplied OutputStream or Writer; those must be closed explicitly by the calling application. |
IDictionary<int, string> | GetCharacterMap (QName name) Get the character map with a given name |
void | OnClose (Action action) Define an action to be performed when writing to the Destination is complete. |
void | SerializeXdmNode (XdmNode node)
Serialize an |
void | SerializeXdmValue (XdmValue value)
Serialize an arbitrary |
void | SetCharacterMap (QName name, IDictionary<int, string> charMap) Set a character map to be used |
void | SetOutputProperty (QName name, string value) Set a serialization property |
Field Detail
BYTE_ORDER_MARK
QName identifying the serialization parameter "byte-order-mark". The value is the string "yes" or "no".
CDATA_SECTION_ELEMENTS
QName identifying the serialization parameter "cdata-section-elements". The value of this parameter is given as a space-separated list of expanded QNames in Clark notation, that is "{uri}local".
DOCTYPE_PUBLIC
QName identifying the serialization parameter "doctype-public"
DOCTYPE_SYSTEM
QName identifying the serialization parameter "doctype-system"
ENCODING
QName identifying the serialization parameter "encoding"
ESCAPE_URI_ATTRIBUTES
QName identifying the serialization parameter "escape-uri-attributes". The value is the string "yes" or "no".
INCLUDE_CONTENT_TYPE
QName identifying the serialization parameter "include-content-type". The value is the string "yes" or "no".
INDENT
QName identifying the serialization parameter "indent". The value is the string "yes" or "no".
ITEM_SEPARATOR
Set to a string used to separate adjacent items in an XQuery result sequence
MEDIA_TYPE
QName identifying the serialization parameter "media-type".
METHOD
QName identifying the serialization parameter "method". If the value is a user-defined method, then it is given as a QName in Clark notation, that is "{uri}local".
NEXT_IN_CHAIN
QName identifying the serialization parameter "saxon:next-in-chain". This is available only with XSLT, and identifies the URI of a stylesheet that is to be used to process the results before passing them to their final destination.
NORMALIZATION_FORM
QName identifying the serialization parameter "normalization-form"
OMIT_XML_DECLARATION
QName identifying the serialization parameter "omit-xml-declaration". The value is the string "yes" or "no".
SAXON_ATTRIBUTE_ORDER
Saxon extension: set to a space-separated list of attribute names, in Clark notation, indicating that attributes present in the list should be serialized in the order indicated, followed by attributes not present in the list(these are sorted first by namespace, then by local name).
SAXON_CANONICAL
Saxon extension: request canonical XML output.
SAXON_CHARACTER_REPRESENTATION
QName identifying the serialization parameter "saxon:character-representation"
SAXON_DOUBLE_SPACE
QName identifying the serialization parameter "saxon:double-space". The value of this parameter is given as a space-separated list of expanded QNames in Clark notation, that is "{uri}local"; each QName identifies an element that should be preceded by an extra blank line within indented output.
SAXON_INDENT_SPACES
QName identifying the serialization parameter "saxon:indent-spaces". The value is an integer (represented as a string) indicating the amount of indentation required. If specified, this parameter overrides indent="no".
SAXON_LINE_LENGTH
Saxon extension: set to an integer (represented as a string) giving the desired maximum length of lines when indenting.Default is 80.
SAXON_NEWLINE
Saxon extension: set to any string. Indicates the sequence of characters used to represent a newline in the text output method, and in newlines used for indentation in any output methods that use indentation.
SAXON_RECOGNIZE_BINARY
Saxon extension for use when writing to the text output method; this option causes the processing instructions hex and b64 to be recognized containing hexBinary or base64 data respectively.
SAXON_REQUIRE_WELL_FORMED
QName identifying the serialization parameter "saxon:require-well-formed". The value is the string "yes" or "no". If set to "yes", the output must be a well-formed document, or an error will be reported. ("Well-formed" here means that the document node must have exactly one element child, and no text node children other than whitespace-only text nodes).
SAXON_STYLESHEET_VERSION
Saxon extension for internal use: used in XSLT to tell the serializer whether the stylesheet used version="1.0" or version = "2.0"
SAXON_SUPPRESS_INDENTATION
QName identifying the serialization parameter "suppress-indentation". Retained as a synonym of SUPPRESS_INDENTATION for backwards compatibility.
SAXON_WRAP
Saxon extension, indicates that the output of a query is to be wrapped before serialization, such that each item in the result sequence is enclosed in an element indicating its type
STANDALONE
QName identifying the serialization parameter "standalone". The value is the string "yes" or "no" or "omit".
SUPPLY_SOURCE_LOCATOR
Saxon extension for interfacing with debuggers; indicates that the location information is available for events in this output stream
SUPPRESS_INDENTATION
QName identifying the serialization parameter "suppress-indentation" (introduced in XSLT/XQuery 3.0). Previously available as "saxon:suppress-indentation". The value is the string "yes" or "no".
UNDECLARE_PREFIXES
QName identifying the serialization parameter "undeclare-prefixes". The value is the string "yes" or "no".
USE_CHARACTER_MAPS
QName identifying the serialization parameter "use-character-maps". The value of the parameter is a list of expanded QNames in Clark notation giving the names of character maps defined in the XSLT stylesheet, or supplied programmatically.
VERSION
QName identifying the serialization parameter "version"
Property Detail
BaseUri
This property determines the base Uri of the constructed Serializer
.
OutputFile
Specify the destination of the serialized output, in the form of a file name
Value:
Throws:
SaxonApiException
if it is not possible to
create an output stream to write to this file, for example, if the filename is in
a
directory that does not exist.OutputStream
Specify the destination of the serialized output, in the
form of a Stream
. This must be a stream that allows writing.
Saxon will not close the stream on completion; this is the caller's responsibility.
OutputWriter
Specify the destination of the serialized output, in the
form of a TextWriter
.
Note that when writing to a TextWriter
, character encoding is
the responsibility of the TextWriter
, not the Serializer
. This
means that the encoding requested in the output properties is ignored; it also
means that characters that cannot be represented in the target encoding will
use whatever fallback representation the TextWriter
defines, rather than
being represented as XML character references.
Saxon will not close the
TextWriter
on completion; this is the caller's responsibility.
UnderlyingDestination
The underlying Saxon.Hej.s9api.Destination
object in the Saxon implementation
This property provides access to internal methods in the Saxon engine that are not specifically exposed in the .NET API. In general these methods should be considered to be less stable than the classes in the Saxon.Api namespace.
The internal methods follow Java naming conventions rather than .NET conventions.
Information about the returned net.sf.saxon.s9api.Destination object (and the objects it provides access to) is included in the Saxon JavaDoc documentation.
Value:
Method Detail
Close
GetCharacterMap
Get the character map with a given name
Parameters:
name
- The name of the character map, as a QNameReturns:
OnClose
Define an action to be performed when writing to the Destination is complete.
Parameters:
action
- The action to be performed.SerializeXdmNode
Serialize an XdmNode
to the selected output destination using this serializer.
since 9.8
Parameters:
node
- The node to be serializedSerializeXdmValue
Serialize an arbitrary XdmValue
to the selected output destination using this serializer.
The supplied sequence is first wrapped in a document node according to the rules given
in section 2
(Sequence Normalization) of the XSLT/XQuery serialization specification; the resulting
document node
is then serialized using the serialization parameters defined in this serializer.
A call on this
method will close the writer or output stream internally.
since 9.8
Parameters:
value
- The value to be serializedSetCharacterMap
IDictionary<int, string> charMap)
Set a character map to be used
Note that the character map is used by the serializer only if the
USE_CHARACTER_MAPS
output property includes the name of this character map.
Parameters:
name
- the name of the character mapcharMap
- the content of the character map, supplied as
a dictionary that maps integer Unicode codepoint values to stringsSetOutputProperty
Set a serialization property
In the case of XSLT, properties set within the serializer override
any properties set in xsl:output
declarations in the stylesheet.
Similarly, with XQuery, they override any properties set in the Query
prolog using declare option output
.
Parameters:
name
- The name of the serialization property to be setvalue
- The value to be set for the serialization property. May be null
to unset the property (that is, to set it back to the default value).Example:
Serializer qout = processor.NewSerializer(); qout.SetOutputProperty(Serializer.METHOD, "xml"); qout.SetOutputProperty(Serializer.INDENT, "yes"); qout.SetOutputProperty(Serializer.SAXON_INDENT_SPACES, "1");
Close any resources associated with this destination. Note that this does not close any user-supplied OutputStream or Writer; those must be closed explicitly by the calling application.