JavaTM Platform
Standard Ed. 6

org.xml.sax.helpers
类 NamespaceSupport

java.lang.Object
  继承者 org.xml.sax.helpers.NamespaceSupport

public class NamespaceSupport
     
extends Object

封装名称空间逻辑,以便由使用 SAX 的应用程序使用,或由 SAX 驱动程序内部使用。

此模块(包括源代码和文档)位于公共域中,对该模块不提供担保有关更多信息,请参阅 http://www.saxproject.org

此类封装名称空间处理的逻辑:它可以跟踪当前对每个上下文强制使用的声明,并自动将限定的 XML 名称处理为其名称空间的一部分;它还可以反过来用于从名称空间生成 XML qname。

名称空间支持对象是可重用的,但是在每个会话之间必须调用 reset 方法。

下面是一个简单的会话:

String parts[] = new String[3];
 NamespaceSupport support = new NamespaceSupport();

 support.pushContext();
 support.declarePrefix("", "http://www.w3.org/1999/xhtml");
 support.declarePrefix("dc", "http://www.purl.org/dc#");

 parts = support.processName("p", parts, false);
 System.out.println("Namespace URI: " + parts[0]);
 System.out.println("Local name: " + parts[1]);
 System.out.println("Raw name: " + parts[2]);

 parts = support.processName("dc:title", parts, false);
 System.out.println("Namespace URI: " + parts[0]);
 System.out.println("Local name: " + parts[1]);
 System.out.println("Raw name: " + parts[2]);

 support.popContext();
 

注意,对于多数元素不包含名称空间声明的使用情况,必须优化此类:例如,如果对每个上下文都重复相同的前缀/URI 映射,则此类将会产生某种程度的低效率。

虽然 SAX 驱动程序(解析器)可以选择使用此类来实现名称空间处理,但是不要求它们这样做。如果应用程序要使用名称空间信息,则它们必须跟踪名称空间信息本身。

从以下版本开始:
SAX 2.0

字段摘要
static String NSDECL
          作为常量的名称空间声明 URI。
static String XMLNS
          作为常量的 XML 名称空间 URI。
 
构造方法摘要
NamespaceSupport()
          创建新的名称空间支持对象。
 
方法摘要
 boolean declarePrefix(String prefix, String uri)
          声明名称空间前缀。
 Enumeration getDeclaredPrefixes()
          返回此上下文中声明的所有前缀的枚举。
 String getPrefix(String uri)
          返回映射到名称空间 URI 的前缀之一。
 Enumeration getPrefixes()
          返回所有前缀的枚举,其声明在当前上下文中是活动的。
 Enumeration getPrefixes(String uri)
          返回给定 URI 的 所有前缀的枚举,给定 URI 的声明在当前上下文中是活动的。
 String getURI(String prefix)
          查找前缀,并获取当前映射的名称空间 URI。
 boolean isNamespaceDeclUris()
          如果将名称空间声明属性放置到名称空间中,则返回 true。
 void popContext()
          恢复到以前的名称空间上下文。
 String[] processName(String qName, String[] parts, boolean isAttribute)
          declarePrefix() 处理完当前上下文中的所有声明之后,处理原始 XML 限定名称。
 void pushContext()
          开始新的名称空间上下文。
 void reset()
          重设此名称空间支持对象,以便重新使用。
 void setNamespaceDeclUris(boolean value)
          控制是否通过 processName() 将名称空间声明属性放置到 NSDECL 名称空间中。
 
从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

字段详细信息

XMLNS

public static final String XMLNS
作为常量的 XML 名称空间 URI。值是 http://www.w3.org/XML/1998/namespace,在 "Namespaces in XML" * 推荐标准中定义。

这是自动映射到 "xml" 前缀的名称空间 URI。

另请参见:
常量字段值

NSDECL

public static final String NSDECL
作为常量的名称空间声明 URI。值是 http://www.w3.org/xmlns/2000/,在 "Namespaces in XML" 推荐标准的向后兼容勘误表中定义。因为勘误表晚于 SAX2,SAX2 默认为原始的推荐标准,并且通常不使用此 URI。

这是可以选择应用到 xmlnsxmlns:* 属性的名称空间 URI,使用它声明名称空间。

从以下版本开始:
SAX 2.1alpha
另请参见:
setNamespaceDeclUris(boolean), isNamespaceDeclUris(), 常量字段值
构造方法详细信息

NamespaceSupport

public NamespaceSupport()
创建新的名称空间支持对象。

方法详细信息

reset

public void reset()
重设此名称空间支持对象,以便重新使用。

在为新的会话重用名称空间支持对象之前,有必要调用此方法。如果要支持名称空间声明 URI,则还必须将标志设置为非默认值。

另请参见:
setNamespaceDeclUris(boolean)

pushContext

public void pushContext()
开始新的名称空间上下文。新的上下文将自动继承其父上下文的声明,但是它还将跟踪在此上下文中所做的声明。

事件回调代码应对每个元素启动一次新的上下文。这意味着已准备好在两个位置中的任何一个位置调用它。对于不包括名称空间声明的元素,ContentHandler.startElement() 回调是正确的位置。对于具有此类声明的元素,它在第一个 ContentHandler.startPrefixMapping() 回调中完成。可以使用布尔标志跟踪是否已启动上下文。当调用这些方法中的任何一个方法时,它会检查该标志以查看是否需要启动新的上下文。如果是,它会启动上下文,并设置标志。在 ContentHandler.startElement() 设置标志后,它总是清除该标志。

通常,SAX 驱动程序会在每个 XML 元素的开始处推送新的上下文。然后,它们执行属性上的第一个传递,以处理所有的名称空间声明,进行 ContentHandler.startPrefixMapping() 回调。然后,进行第二个传递,以便为所有属性和元素名称确定限定名称空间的名称。最后,ContentHandler.startElement() 回调的所有信息都是可用的,这样就可以完成。

名称空间支持对象总是以已经有效的基本上下文开始:在此上下文中,仅声明 "xml" 前缀。

另请参见:
ContentHandler, popContext()

popContext

public void popContext()
恢复到以前的名称空间上下文。

通常,应在每个 XML 元素的结束处弹出上下文。弹出上下文后,恢复以前有效的所有名称空间前缀映射。

弹出上下文后,不得尝试声明其他名称空间前缀,除非首先推送另一个上下文。

另请参见:
pushContext()

declarePrefix

public boolean declarePrefix(String prefix,
                             String uri)
声明名称空间前缀。在引用前缀之前,必须对它们进行声明。例如,SAX 驱动程序(解析器)将在下面两个过程中扫描元素的属性:第一个是名称空间声明,然后是第二个过程,它使用 processName() 根据(潜在预定义的)前缀解释前缀。

此方法在当前名称空间上下文中声明前缀;在弹出此上下文之前,前缀仍保持有效,除非它在后代上下文中映像。

要声明默认元素名称空间,请使用空字符串作为前缀。

注意,在此库中存在不对称:即使声明了默认元素名称空间,getPrefix 也不会返回 "" 前缀。要检查默认名称空间,必须使用 getURI 显式查找它。存在此不对称使查找属性名称的前缀更容易,其中不允许默认的前缀。

参数:
prefix - 要声明的前缀,或指示默认元素名称空间的空字符串。这不能有值“xml”或“xmlns”。
uri - 与前缀关联的名称空间 URI。
返回:
如果前缀是合法的,则返回 true;否则,返回 false
另请参见:
processName(java.lang.String, java.lang.String[], boolean), getURI(java.lang.String), getPrefix(java.lang.String)

processName

public String[] processName(String qName,
                            String[] parts,
                            boolean isAttribute)
declarePrefix() 处理完当前上下文中的所有声明之后,处理原始 XML 限定名称。

此方法通过移除前缀,并在当前声明的前缀之中查找它来处理当前上下文中的原始 XML 限定名称。返回值将是调用者提供的数组,按以下方式填写:

parts[0]
名称空间 URI,如果没有正在使用的,则为空字符串。
parts[1]
本地名称(不带前缀)。
parts[2]
最初的原始名称。

将内部化数组中的所有字符串。如果原始名称具有没有声明的前缀,那么返回值将为 null。

注意,处理属性名称与处理元素名称不同:未加前缀的元素名称将接收默认名称空间(如果有),而未加前缀的属性名称将不接收。

参数:
qName - 要处理的 XML 限定名称。
parts - 调用者提供的数组,至少能够保存三个成员。
isAttribute - 指示这是属性名称 (true) 或元素名称 (false) 的标志。
返回:
提供的数组,它持有三个内部化字符串,表示名称空间 URI(或空字符串)、本地名称和 XML 限定名称;如果存在未声明的前缀,则返回 null。
另请参见:
declarePrefix(java.lang.String, java.lang.String), String.intern()

getURI

public String getURI(String prefix)
查找前缀,并获取当前映射的名称空间 URI。

此方法查找当前上下文中的前缀。对于默认名称空间,使用空字符串 ("")。

参数:
prefix - 要查找的前缀。
返回:
关联的名称空间 URI,如果此上下文中未声明前缀,则返回 null。
另请参见:
getPrefix(java.lang.String), getPrefixes()

getPrefixes

public Enumeration getPrefixes()
返回所有前缀的枚举,其声明在当前上下文中是活动的。这包括来自没有被重写的父上下文的声明。

注:如果存在默认前缀,则在此枚举中将不返回它;使用带有参数 "" 的 getURI 检查默认前缀。

返回:
前缀的枚举(永远不为空)。
另请参见:
getDeclaredPrefixes(), getURI(java.lang.String)

getPrefix

public String getPrefix(String uri)
返回映射到名称空间 URI 的前缀之一。

如果当前有多个前缀映射到同一 URI,则此方法将进行任意选择;如果需要所有前缀,则改用 getPrefixes() 方法。

注:这将永不返回空(默认)前缀;要检查默认前缀,请使用带有参数 "" 的 getURI 方法。

参数:
uri - 名称空间 URI
返回:
当前映射到所提供的 URI 的前缀之一,如果没有映射内容,或者将 URI 分配到默认名称空间,则返回 null
另请参见:
getPrefixes(java.lang.String), getURI(java.lang.String)

getPrefixes

public Enumeration getPrefixes(String uri)
返回给定 URI 的 所有前缀的枚举,给定 URI 的声明在当前上下文中是活动的。这包括来自没有被重写的父上下文的声明。

此方法返回映射到特定名称空间 URI 的前缀。将包括前缀:xml。如果仅需要映射到名称空间 URI 的一个前缀,并且不关心获取哪一个前缀,请改用 getPrefix 方法。

注:此枚举中永不 包括空的(默认)前缀;要检查是否存在默认名称空间,请使用带有参数 "" 的 getURI 方法。

参数:
uri - 名称空间 URI。
返回:
前缀的枚举(永不为空)。
另请参见:
getPrefix(java.lang.String), getDeclaredPrefixes(), getURI(java.lang.String)

getDeclaredPrefixes

public Enumeration getDeclaredPrefixes()
返回此上下文中声明的所有前缀的枚举。

此枚举中将包括空的(默认)前缀;注意,此行为与 getPrefix(java.lang.String)getPrefixes() 的行为不同。

返回:
此上下文中声明的所有前缀的枚举。
另请参见:
getPrefixes(), getURI(java.lang.String)

setNamespaceDeclUris

public void setNamespaceDeclUris(boolean value)
控制是否通过 processName() 将名称空间声明属性放置到 NSDECL 名称空间中。在推送任何上下文之前,这是唯一可更改的。

抛出:
IllegalStateException - 当推送任何上下文之后尝试设置它时。
从以下版本开始:
SAX 2.1alpha

isNamespaceDeclUris

public boolean isNamespaceDeclUris()
如果将名称空间声明属性放置到名称空间中,则返回 true。此行为不是默认的行为。

从以下版本开始:
SAX 2.1alpha

JavaTM Platform
Standard Ed. 6

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

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