JavaTM Platform
Standard Ed. 6

javax.xml.stream
接口 XMLStreamWriter


public interface XMLStreamWriter

XMLStreamWriter 接口指定如何编写 XML。XMLStreamWriter 不在其输入中检查格式是否良好。但是,writeCharacters 方法需要转义属性值的 &、< 和 >。writeAttribute 方法将转义上述字符以及 ",以确保所有字符内容和属性值都是格式良好的。 必须单独编写每个 NAMESPACE 和 ATTRIBUTE。

XML Namespaces、javax.xml.stream.isRepairingNamespaces 和写入方法行为
方法 isRepairingNamespaces == true isRepairingNamespaces == false
namespaceURI 绑定 namespaceURI 未绑定 namespaceURI 绑定 namespaceURI 未绑定
writeAttribute(namespaceURI, localName, value) prefix:localName="value" [1] xmlns:{generated}="namespaceURI" {generated}:localName="value" prefix:localName="value" [1] XMLStreamException
writeAttribute(prefix, namespaceURI, localName, value) 绑定到相同的前缀:
prefix:localName="value" [1]

绑定到不同的前缀:
xmlns:{generated}="namespaceURI" {generated}:localName="value"
xmlns:prefix="namespaceURI" prefix:localName="value" [3] 绑定到相同的前缀:
prefix:localName="value" [1][2]

绑定到不同的前缀:
XMLStreamException[2]
xmlns:prefix="namespaceURI" prefix:localName="value" [2][5]
writeStartElement(namespaceURI, localName)

writeEmptyElement(namespaceURI, localName)
<prefix:localName> [1] <{generated}:localName xmlns:{generated}="namespaceURI"> <prefix:localName> [1] XMLStreamException
writeStartElement(prefix, localName, namespaceURI)

writeEmptyElement(prefix, localName, namespaceURI)
绑定到相同的前缀:
<prefix:localName> [1]

绑定到不同的前缀:
<{generated}:localName xmlns:{generated}="namespaceURI">
<prefix:localName xmlns:prefix="namespaceURI"> [4] 绑定到相同的前缀:
<prefix:localName> [1]

绑定到不同的前缀:
XMLStreamException
<prefix:localName> 
注:
  • [1] 如果 namespaceURI == default Namespace URI,则不写入任何前缀
  • [2] 如果 prefix == "" || null && namespaceURI == "",则不生成或写入任何前缀或 Namespace 声明
  • [3] 如果 prefix == "" || null,则随机生成前缀
  • [4] 如果 prefix == "" || null,则将其视为默认 Namespace,且不生成或写入任何前缀,如果 namespaceURI 是未绑定的,则生成并写入一个 xmlns 声明
  • [5] 如果 prefix == "" || null,则试图定义默认 Namespace 将被视为无效,且将抛出 XMLStreamException

从以下版本开始:
1.6
另请参见:
XMLOutputFactory, XMLStreamReader

方法摘要
 void close()
          关闭此 writer 并释放与 writer 关联的所有资源。
 void flush()
          将所有缓存数据写入底层输出机制。
 NamespaceContext getNamespaceContext()
          返回当前名称空间上下文。
 String getPrefix(String uri)
          获取绑定 URI 的前缀
 Object getProperty(String name)
          从底层实现获取功能/属性值
 void setDefaultNamespace(String uri)
          将 URI 绑定到默认名称空间。
 void setNamespaceContext(NamespaceContext context)
          设置前缀和 URI 绑定的当前名称空间上下文。
 void setPrefix(String prefix, String uri)
          设置绑定 URI 的前缀。
 void writeAttribute(String localName, String value)
          向输出流写入一个不带前缀的属性。
 void writeAttribute(String namespaceURI, String localName, String value)
          向输出流写入一个属性
 void writeAttribute(String prefix, String namespaceURI, String localName, String value)
          向输出流写入一个属性
 void writeCData(String data)
          编写 CData 节
 void writeCharacters(char[] text, int start, int len)
          向输出写入文本
 void writeCharacters(String text)
          向输出写入文本
 void writeComment(String data)
          编写一个包含数据的 XML 注释
 void writeDefaultNamespace(String namespaceURI)
          向流写入默认名称空间
 void writeDTD(String dtd)
          编写 DTD 节。
 void writeEmptyElement(String localName)
          向输出写入一个空元素标记
 void writeEmptyElement(String namespaceURI, String localName)
          向输出写入一个空元素标记
 void writeEmptyElement(String prefix, String localName, String namespaceURI)
          向输出写入一个空元素标记
 void writeEndDocument()
          关闭所有开始标记并写入相应的结束标记。
 void writeEndElement()
          向依赖于 writer 内部状态的输出写入一个结束标记,以此确定事件的前缀和本地名称。
 void writeEntityRef(String name)
          编写一个实体引用
 void writeNamespace(String prefix, String namespaceURI)
          向输出流写入一个名称空间。
 void writeProcessingInstruction(String target)
          编写一条处理指令
 void writeProcessingInstruction(String target, String data)
          编写一条处理指令
 void writeStartDocument()
          编写 XML 声明。
 void writeStartDocument(String version)
          编写 XML 声明。
 void writeStartDocument(String encoding, String version)
          编写 XML 声明。
 void writeStartElement(String localName)
          向输出写入一个开始标记。
 void writeStartElement(String namespaceURI, String localName)
          向输出写入一个开始标记
 void writeStartElement(String prefix, String localName, String namespaceURI)
          向输出写入一个开始标记
 

方法详细信息

writeStartElement

void writeStartElement(String localName)
                       throws XMLStreamException
向输出写入一个开始标记。所有 writeStartElement 方法都在内部名称空间上下文中打开一个新的作用域。编写相应的 EndElement 导致作用域被关闭。

参数:
localName - 标记的本地名称,不可以为 null
抛出:
XMLStreamException

writeStartElement

void writeStartElement(String namespaceURI,
                       String localName)
                       throws XMLStreamException
向输出写入一个开始标记

参数:
namespaceURI - 要使用的前缀的 namespaceURI ,不可以为 null
localName - 标记的本地名称,不可以为 null
抛出:
XMLStreamException - 如果名称空间 URI 未绑定到前缀并且 javax.xml.stream.isRepairingNamespaces 未设置为 true

writeStartElement

void writeStartElement(String prefix,
                       String localName,
                       String namespaceURI)
                       throws XMLStreamException
向输出写入一个开始标记

参数:
localName - 标记的本地名称,不可以为 null
prefix - 标记的前缀,不可以为 null
namespaceURI - 要绑定前缀的 URI,不可以为 null
抛出:
XMLStreamException

writeEmptyElement

void writeEmptyElement(String namespaceURI,
                       String localName)
                       throws XMLStreamException
向输出写入一个空元素标记

参数:
namespaceURI - 要绑定标记的 URI,不可以为 null
localName - 标记的本地名称,不可以为 null
抛出:
XMLStreamException - 如果名称空间 URI 未绑定到前缀并且 javax.xml.stream.isRepairingNamespaces 未设置为 true

writeEmptyElement

void writeEmptyElement(String prefix,
                       String localName,
                       String namespaceURI)
                       throws XMLStreamException
向输出写入一个空元素标记

参数:
prefix - 标记的前缀,不可以为 null
localName - 标记的本地名称,不可以为 null
namespaceURI - 要绑定标记的 URI,不可以为 null
抛出:
XMLStreamException

writeEmptyElement

void writeEmptyElement(String localName)
                       throws XMLStreamException
向输出写入一个空元素标记

参数:
localName - 标记的本地名称,不可以为 null
抛出:
XMLStreamException

writeEndElement

void writeEndElement()
                     throws XMLStreamException
向依赖于 writer 内部状态的输出写入一个结束标记,以此确定事件的前缀和本地名称。

抛出:
XMLStreamException

writeEndDocument

void writeEndDocument()
                      throws XMLStreamException
关闭所有开始标记并写入相应的结束标记。

抛出:
XMLStreamException

close

void close()
           throws XMLStreamException
关闭此 writer 并释放与 writer 关联的所有资源。此方法不得关闭底层输出流。

抛出:
XMLStreamException

flush

void flush()
           throws XMLStreamException
将所有缓存数据写入底层输出机制。

抛出:
XMLStreamException

writeAttribute

void writeAttribute(String localName,
                    String value)
                    throws XMLStreamException
向输出流写入一个不带前缀的属性。

参数:
localName - 属性的本地名称
value - 属性的值
抛出:
IllegalStateException - 如果当前状态不允许 Attribute 写入
XMLStreamException

writeAttribute

void writeAttribute(String prefix,
                    String namespaceURI,
                    String localName,
                    String value)
                    throws XMLStreamException
向输出流写入一个属性

参数:
prefix - 此属性的前缀
namespaceURI - 此属性前缀的 URI
localName - 属性的本地名称
value - 属性的值
抛出:
IllegalStateException - 如果当前状态不允许 Attribute 写入
XMLStreamException - 如果名称空间 URI 未绑定到前缀且 javax.xml.stream.isRepairingNamespaces 未设置为 true

writeAttribute

void writeAttribute(String namespaceURI,
                    String localName,
                    String value)
                    throws XMLStreamException
向输出流写入一个属性

参数:
namespaceURI - 此属性前缀的 URI
localName - 属性的本地名称
value - 属性的值
抛出:
IllegalStateException - 如果当前状态不允许 Attribute 写入
XMLStreamException - 如果名称空间 URI 未绑定到前缀且 javax.xml.stream.isRepairingNamespaces 未设置为 true

writeNamespace

void writeNamespace(String prefix,
                    String namespaceURI)
                    throws XMLStreamException
向输出流写入一个名称空间。如果此方法的 prefix 参数为空字符串、"xmlns" 或 null,则此方法将委托给 writeDefaultNamespace。

参数:
prefix - 要绑定名称空间的前缀
namespaceURI - 要绑定前缀的 URI
抛出:
IllegalStateException - 如果当前状态不允许 Namespace 写入
XMLStreamException

writeDefaultNamespace

void writeDefaultNamespace(String namespaceURI)
                           throws XMLStreamException
向流写入默认名称空间

参数:
namespaceURI - 要绑定默认名称空间的 URI
抛出:
IllegalStateException - 如果当前状态不允许 Namespace 写入
XMLStreamException

writeComment

void writeComment(String data)
                  throws XMLStreamException
编写一个包含数据的 XML 注释

参数:
data - 包含在注释中的数据,可以为 null
抛出:
XMLStreamException

writeProcessingInstruction

void writeProcessingInstruction(String target)
                                throws XMLStreamException
编写一条处理指令

参数:
target - 处理指令的目标,不可以为 null
抛出:
XMLStreamException

writeProcessingInstruction

void writeProcessingInstruction(String target,
                                String data)
                                throws XMLStreamException
编写一条处理指令

参数:
target - 处理指令的目标,不可以为 null
data - 处理指令中包含的数据,不可以为 null
抛出:
XMLStreamException

writeCData

void writeCData(String data)
                throws XMLStreamException
编写 CData 节

参数:
data - CData 节中包含的数据,不可以为 null
抛出:
XMLStreamException

writeDTD

void writeDTD(String dtd)
              throws XMLStreamException
编写 DTD 节。此字符串代表 XML 1.0 规范的整个 doctypedecl 产品。

参数:
dtd - 要编写的 DTD
抛出:
XMLStreamException

writeEntityRef

void writeEntityRef(String name)
                    throws XMLStreamException
编写一个实体引用

参数:
name - 实体的名称
抛出:
XMLStreamException

writeStartDocument

void writeStartDocument()
                        throws XMLStreamException
编写 XML 声明。默认 XML 版本为 1.0,默认编码为 utf-8

抛出:
XMLStreamException

writeStartDocument

void writeStartDocument(String version)
                        throws XMLStreamException
编写 XML 声明。默认 XML 版本为 1.0

参数:
version - xml 文档的版本
抛出:
XMLStreamException

writeStartDocument

void writeStartDocument(String encoding,
                        String version)
                        throws XMLStreamException
编写 XML 声明。注意,编码参数不能设置底层输出的实际编码。它必须在使用 XMLOutputFactory 创建 XMLStreamWriter 实例时进行设置

参数:
encoding - XML 声明的编码
version - XML 文档的版本
抛出:
XMLStreamException - 如果给定编码与底层流的编码不匹配

writeCharacters

void writeCharacters(String text)
                     throws XMLStreamException
向输出写入文本

参数:
text - 要写入的值
抛出:
XMLStreamException

writeCharacters

void writeCharacters(char[] text,
                     int start,
                     int len)
                     throws XMLStreamException
向输出写入文本

参数:
text - 要写入的值
start - 数组中的起始位置
len - 要写入的字符数
抛出:
XMLStreamException

getPrefix

String getPrefix(String uri)
                 throws XMLStreamException
获取绑定 URI 的前缀

返回:
前缀或 null
抛出:
XMLStreamException

setPrefix

void setPrefix(String prefix,
               String uri)
               throws XMLStreamException
设置绑定 URI 的前缀。前缀在当前 START_ELEMENT / END_ELEMENT 对的范围内绑定。如果在写入 START_ELEMENT 之前调用此方法,则前缀在根范围内绑定。

参数:
prefix - 要绑定到 URI 的前缀,不可以为 null
uri - 要绑定到前缀的 URI,不可以为 null
抛出:
XMLStreamException

setDefaultNamespace

void setDefaultNamespace(String uri)
                         throws XMLStreamException
将 URI 绑定到默认名称空间。此 URI 在当前 START_ELEMENT / END_ELEMENT 对的范围内绑定。如果在写入 START_ELEMENT 之前调用此方法,则 URI 在根范围内绑定。

参数:
uri - 要绑定到默认名称空间的 URI,不可以为 null
抛出:
XMLStreamException

setNamespaceContext

void setNamespaceContext(NamespaceContext context)
                         throws XMLStreamException
设置前缀和 URI 绑定的当前名称空间上下文。此上下文成为用于写入的根名称空间上下文,并将替换当前的根名称空间上下文。通过将传递到此方法的上下文用作解析名称空间的根上下文,对 setPrefix 和 setDefaultNamespace 的后续调用将绑定名称空间。此方法只能在文档开始处调用一次。这不会导致名称空间被声明。如果在名称空间上下文中存在前缀映射关系的名称空间 URI,则它将被视为已经声明,并且该前缀可以被 StreamWriter 使用。

参数:
context - 将用于此 writer 的名称空间上下文,不可以为 null
抛出:
XMLStreamException

getNamespaceContext

NamespaceContext getNamespaceContext()
返回当前名称空间上下文。

返回:
当前 NamespaceContext

getProperty

Object getProperty(String name)
                   throws IllegalArgumentException
从底层实现获取功能/属性值

参数:
name - 属性的名称,不可以为 null
返回:
属性的值
抛出:
IllegalArgumentException - 如果属性不受支持
NullPointerException - 如果名称为 null

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策