TM程序员手册
Ver 2.0
更新时间：2003-12-1 3:55 PM
翻译：ksu99@163.com
1. 引言（Introduction）
dbXML是一种本源数据库（Native XML Database，NXD）。NXD用内在化的格式存储XML以获得更快的整体处理速度。dbXML是基于J2SE 1.4开发的，也应该在J2SE 1.4上运行。
2. 在本文档中使用的约定（Conventions Used in this Document）
贯穿本文，利用格式化的约定转达特别的东西，比如源代码范例、终端会话和提示。这些格式化的约定定义如下：
2.1. 终端会话（Terminal Session）
终端会话用黑背景上的等宽字体示范。如：
Collection: /myCollection
/myCollection>
2.2. 终端指令（Terminal Instructions）
终端指令一般包括在终端会话中，来指导开发者的输入，用黄色粗体字显示。如：
Collection: /myCollection
/myCollection> ls test*.xml
test1.xml
test2.xml
test39.xml
2.3. 文档注释（Document Note）
文档注释对文档来说不是是必不可少的，但是可以提供其他的信息。如：
Reminder:
Don't forget to wash your hands after you delete your XML documents
2.4. 示例源码（Example Source Code）
实例源码用浅灰色背景上的等宽字体显示。如：
public static void main(String[] args) {
System.out.println("Hello world!");
}
3. 快速安装指南（Quick Installation Guide）
3.1. NUIX 用法说明（UNIX Instructions）（略）
3.2. Windows 用法说明（Windows Instructions）
Windows安装文件名是 dbXML-2.0-Beta.zip
1) 将文件解压到选定目录。展开的文件生成在名为 dbXML-2.0的子目录中。
2）设置环境变量 DBXML_HOME 为上述子目录，例如“C:\dbXML-2.0”。
C:\> set DBXML_HOME= C:\dbXML-2.0
3）添加设置 “%DBXML_HOME%\bin”到环境变量 PATH中。
C:\> set PATH="%DBXML_HOME%\bin;%PATH%"
4）启动服务器，调用脚本文件 startup.bat
C:\> cd %DBXML_HOME%
C:\dbXML-2.0> startup
5）与服务器连接彻底检验dbXML命令行工具：
C:\dbXML-2.0> dbxml
> connect user= scott pass= tiger
Connected
/> col /system/SysConfig
Collection: /system/SysConfig
/system/SysConfig> show database.xml
... a document should be displayed ...
/system/SysConfig> shutdown
/system/SysConfig> exit
注意！
默认的，dbXML安装有两个用户和两个角色。一个用户名为‘scott’，授权角色是‘admin’。另一个用于名为‘guest’，授权角色是‘guest’。这个‘guest’用户默认情况下可以读取dbXML stylesheet Collection。系统管理员可能希望删除这个用户和它被赋予的角色。
4. 核心概念（Core Concepts）
这一部分讨论dbXML中的一些核心概念。这包括dbXML如何管理文档集合，集合如何被索引，查询如何被执行，以及如何使用扩充和触发器对服务器进行强化。
4.1. 集合模型（The Collection Model）
dbXML以集合的方式管理文档。很多集合可以被同时创建和管理。集合也可以以分层的方式摆开，很像操作系统的目录结构。单个集合可以与多个索引、扩充、触发器和子集合关联。同样的，一个集合可以存储XML文档或者二进制流。
集合底层的存储引擎称为文件管理器。默认情况下，dbXML使用一个叫做BtreeFiler的本地文件管理器，但是其他的文件管理器会被用于特殊目的。这些filer包括MemFiler，FSFiler，和DBFiler。
BTreeFiler 为处理dbXML默认的本地filer。它支持事务和日志。
MemFiler 用于临时存储，当服务器重启的时候，filer内容被破坏。
FSFiler 用于管理位于操作系统目录里的内容。
DBFiler 用于完成到或者从关系数据库表的关系映象。
无论使用怎样的文件管理器，dbXML使用同样的程序接口现露内容，所以底层的filer对于开发者是透明的。
虽然一个集合里的文档不需要用一个通用的模式（schema）来约束，但是用单个集合包含相似的文档是个好习惯，这样易于进行针对集合的检索和查询。
注意：
当前，dbXML集合独立于模式，它胜任于对存储于一个集合中的文档执行基于模式的验证的应用开发。将来的dbXML版本将包括内部XML模式支持。
4.2. 文档与记录（Documents and Records）
dbXML可以存储XML文档或者二进制流（记录），但是不能同时进行。XML文档可以被存储为二进制流，但是将不能受益于标记化、压缩和检索。dbXML不是个多媒体数据库，所以不推荐存储大量的二进制流，理解这些是很重要的。限制二进制流不超过500k字节是个好主意。
4.3. 索引（Indexes）
集合可以允许多重索引与它们关联。索引是一个文件结构，用来允许对一个集合中的文档进行基于这些文档的结构或者值的最优化检索。dbXML当前提供三种索引。它们是ValueIndexer，NameIndexer和FullTextIndexer。索引是基于元素和/或属性模式创建的。
4.4. 查询解析器（Query Resolvers）
如果你没有一种方式去查询这些文档或者它们中的一部分，这些文档集合和文档中值的索引就没有太多用处。dbXML为您提供几种查询解析系统来达到这个目的。查询解析器向整个数据库注册。查询针对特定的集合或者一个集合中的文档来执行，并且以一个样式名引用。dbXML支持以下样式：
Xpath是一种简洁的路径语法，在某些方面与UNIX或DOS中的目录路径相似。它允许返回基于位置和赋值判定过滤的结果。
XSLT是一种把XML转换成其他格式的变换语言。这些格式包括XML、文本、超文本，当使用XSL格式化对行时，或者甚至可以是PDF格式。dbXML XSLT查询可以在单个文档上执行，也可以在整个集合或者一个Xpath查询结果上执行。
XUpdate也是一种和XSLT相似的变换，但是其语法相对简单，而且其目的是在适当位置修改文档内容。
FullText是一种搜索引擎样式查询，具有搜索多个用与、或赋值的词的能力。全文查询结果也可以使用Xpath表达式过滤。
4.5. 扩充（Extensions）
扩充是用来给dbXML服务器增加额外能力的方式。扩充是实现扩充接口的Java类，它的公用方法以web service端点的方式暴露。触发器和其他扩充也可以引用扩充。重要的是要记住，只有获取类属参数的特殊子节点的公用方法，可以以web service端点的方式暴露
4.6. 触发器（Triggers）
触发器是实现触发器接口的Java类。这个接口规定了几个方法，用来实现从一个集合触发的返回的处理。集合在下列事件前后激发触发器：
文档插入 – 当insertDocument，insertRecord，setDocument或者setRecord方法被调用时被激活
文档更新 – 当setDocument或者setRecord方法被调用时被激活
文档删除 – 当remove方法被调用时被激活
文档检索 – 当getDocument或者getRecord方法被调用时被激活
在插入、更新和删除前激发的触发事件会被触发器的实现禁止。触发器也给程序员机会来执行诸如确认和文档到达数据库前的文档修改这一类任务。
4.7. 事务（Transactions）
目前，dbXML在direct API级别提供事务日志处理能力。在这里级别，所有的数据库操作必须利用一个事务引用来执行，只有提交才允许。这些能力还没有通过dbXML的客户/服务器 API提供，这是一件好事，也不好。
对于客户/服务器任务来说，事务是一个应用开发者可以方便的忽略的细节。dbXML客服/服务器API自动例示并为每个数据库调用提交事务。
注意：
未来的dbXML版本将包括在客户服务器层全方位的事务处理，但是现在，日志事务处理只能用direct API控制。
5. 命令行工具（Command Line Tools）
dbXML命令行是个类似命令解释程序的界面，人机对话和脚本提供数据库、集合和文档的管理功能。要启动dbXML命令行工具，请确定你的DBXML_HOME环境变量已经正确设置（参考快速安装指南）而且你的PATH环境变量值包括了DBXML_HOME目录下的‘bin’路径。dbXML命令行包括一个帮助系统，来帮助你使用这些命令。
5.1. 与数据库连接
使用命令行工具与dbXML数据库连接相当容易，你只要使用connect命令就行。connect命令既控制使用的dbXML驱动类型，又控制使用这个驱动类型连接到一个服务器需要的主机和身份验证参数。默认情况下，connect命令会使用XML-RPC驱动以dbXML的标准端口不使用身份验证参数与本地计算机连接。这将是完美的，除了一下事实，dbXML的标准安全模型要求用户名和密码来验证关于数据库的身份，所以需要你提供一个用户名和密码。例如：
> connect user=scott pass=tiger
Connected
这将尝试以用户名‘scott’及密码‘tiger’登录并连接到本地数据库。在dbXML中，‘scott’是个自引导程序用户，其角色是管理新创建的数据库。
Did You Know?
For database history buffs (all three of you), the username 'scott' and password 'tiger' were once used to login to Oracle's demo schema, and refer to one of Oracle's founders (Bruce Scott) and his cat (Tiger).
你可以以添加主机和（随意地）端口参数的方法连接一个替代的计算机
> connect user=scott pass=tiger host=myhost.mydomain.com port=7280
Connected
dbXML连接命令
命令
说明
用法
CONNECT
与一个dbXML数据库服务器连接
CONNECT [connection properties]
DISCONNECT
断开与dbXML服务器的连接
DISCONNECT
5.2. 集合管理
管理和操纵一个dbXML数据库的集合，与下一步处理直接相关，而且在很多方面与UNIX目录管理与操纵相似。
创建一个集合与下面的例子相似：
/> mkcol myCollection
Collection 'myCollection' created
这将在数据库根目录下创建一个集合，名为‘myCollection’默认的集合类型存储压缩的XML文档。如果你意欲创建一个可以存储二进制流的集合，你可以在命令中增加type参数
/> mkcol myCollection type=binary
Collection 'myCollection' created
dbXML集合管理命令
命令
说明
用法
LSCOL
对一个集合的子集合列表
LSCOL [wildcard]
COL
设置默认集合
COL 'collection'
MKCOL
创建一个新的文档集合
MKCOL 'collection name' [properties]
RMCOL
从集合中删除特定的子集合
RMCOL 'collection name'
5.3. 管理安全
安全管理程序
dbXML当前支持三种安全管理程序。
NoSecurityManager 不提供安全保护，用于访问数据库不需要身份验证时。
SimpleSecurityManager 提供简易的安全保护，用于整个数据库用单一用户名和密码时。用户名和密码在数据库的system.xml配置文件中定义。
DefaultSecurityManager 被方便的命名，因为它时默认的安全管理程序。它提供基于存储于数据库系统集合中的用户和角色的访问控制。
命令集
有三组与安全有关的命令，是必须熟悉的。
Users – 用户相关的命令允许你管理数据库用户。这包括创造，删除，角色参与和密码设置。在第一次创造时，用户没有密码设置。在dbXML中，除非一个用户的密码已经被设置，否则他不能进入系统。用户示例将是默认dbXML用户‘scott'’。
Roles – 角色被指派访问控制列表。它们是一种抽象，允许数据库避免拥有特级粒度访问控制入口，这和基于个体用户不同。角色相关命令包括创建，删除和用户参与。角色的例子是默认dbXML角色‘admin’。
Access Control Lists – ACLs是对如何访问数据库的授权。访问被授权到集合水平 ，既不递归也不自动。简单地创建一个集合不授权创建用户访问此集合。同样的，访问父集合不蕴涵自动子集合。
注意：
命令行工具围绕默认安全管理程序建造。如果你没有使用默认安全管理程序，使用这些命令来修改用户，角色和访问控制数据将会成功，但是将会没有效果，因为另外两种安全管理程序没法以任何方式利用这些数据。
例子
当你在dbXML中创建集合时，那个集合最初对于外界将是不可访问的。数据库不会自动添加一系列默认权限给创建用户，管理员的角色也是如此。下面的例子示范这个过程：
/> mkcol myCollection
Collection 'myCollection' created
/> col myCollection
Collection: /myCollection
/myCollection> grant admin READ WRITE EXECUTE CREATE
Grant Successful (READ, WRITE, EXECUTE, CREATE)
dbXML 安全命令
命令
说明
用法
LSUSER
列出可用的数据库用户
LSUSER [wildcard]
ADDUSER
为数据库增加新的用户
ADDUSER 'user id'
USER
修改用户属性
USER 'user id' 'action' [parameter]
RMUSER
从数据库删除用户
RMUSER 'user id'
LSROLE
列出可用的数据库角色
LSROLE [wildcard]
ADDROLE
为数据库增加新的角色
ADDROLE 'role id'
ROLE
修改角色属性
ROLE 'role id' 'action' [parameter]
RMROLE
从数据库删除角色
RMROLE 'role id'
ACCESS
显示集合的访问控制列表
ACCESS [role id]
GRANT
给角色授权
GRANT 'role id' 'permissions'
REVOKE
撤消角色授权
REVOKE 'role id' 'permissions'
5.4. 索引管理
当使用dbXML开发应用程序时，有效的索引管理是性能的关键。一个良好放置的索引意味着查询解释器必须检验3个文档而不是300,000个这样的差别。使用的索引类型也很重要。
索引类型
dbXML目前有3种类型的Indexers。
ValueIndexer (type=) – ValueIndexer是最通用的indexer。当没有Indexer 被制定是，也是默认值。其目的对文档中元素或者属性的值提供索引。为了适当的索引关系，ValueIndexer可能把这些值强迫成特殊类型。例如，一个值会因为排序的目的，被强制转换为整数。如果一个值无法被强制，它将不能被索引。支持的类型是：
string – 字符串是ValueIndexer的默认类型。使用字符串类型索引的值被以逐字方式存储和查询。这意味着所有前面、中间和后面的空格都与精确查询字符串索引相关。（译者注：空格会影响索引）
trimmed – 裁剪类型与字符串类型相似，除了所以的索引值被正常化。首尾空白被去掉，所有的中间空白被转换成一个空格。这意味着空格差别不影响查询结果。
short, int, long – 整型在内部全部表示为一个64位的单长整数。
float, double – 所用的浮点类型在内部表现为一个128位复合（64位整数，64位小数）表示。
byte – 一个8位字节类型。
char – 一个16位字符类型。
boolean – 一个一位的布尔类型（true或者false，yes或者no, on或者off, 1或者0）。
NameIndexer (type=name) – NameIndexer索引文档中元素或者属性名实体。这对存储不同模式文档的集合特别有用，这种情况下，一个元素可能存在于某些文档中，而并非全部。
FullTextIndexer (type=fulltext) – FullTextIndexer获取元素和属性的值，把它们拆成单个词。改变这些词的格，抽取其主干用于索引。抽取主干是把像‘happening’和‘happen’这样的词取出来，转变成同样的词干。FullTextIndexer对基于内容的搜索特别有用，这类似于Google这样的搜索引擎提供的功能。
索引模式
索引模式是个简单的表达式，用来标识将被特殊索引计算的元素或属性。有6种可能的模式组合
Element Name (pattern=foo) – 索引所有元素值中名为‘foo’的（但不是它们的属性）。
Wildcard Element (pattern=*) – 索引所用元素的值（但不是它们的属性）。
Element Name with Attribute Name (pattern=foo@bar) – 索引属于名为‘foo’的元素的所有‘bar’属性的值。
Element Name with Wildcard Attribute (pattern=foo@*) – 索引所有属于名为‘foo’的元素的属性值。
Wildcard Element with Attribute Name (pattern=*@bar) – 索引属于任何元素属性名为‘bar’的所有值。
Wildcard Element with Wildcard Attribute (pattern=*@*) – 索引属于任何元素的所有属性值。
索引模式也支持名字空间限制能力。这通过预先挂起元素或属性名及其相对应的名字空间URI来实现，用方括号括起来(如： [http://www.w3.org/1999/xhtml]title)。这种模式类型不能包括名字空间前缀，因为它们在名字空间解析中不重要。而且，重要的是在这些模式中不包括空格。
注意：
很容易把索引模式误以为XPath 表达式。虽然语法故意类似Xpath表达式，索引模式不能被Xpath语法控制。这意味着‘/foo[status='active']/bar@id’这样的索引模式不运行。在这种情况下，试试‘bar@id’。
例子
下面的例子创建了关于一个集合的五个索引：
/myCollection> mkidx myElem_ID_Value pattern=myElem@id type=int
Index 'myElem_ID_Value' created
/myCollection> mkidx myElem_Name pattern=myElem type=name
Index 'myElem_Name' created
/myCollection> mkidx myElem_Text pattern=myElem type=fulltext
Index 'myElem_Text' created
/myCollection> mkidx anyElem_Status_Value pattern=*@status type=trimmed
Index 'anyElem_Status_Value' created
/myCollection> mkidx nsElem_Value pattern=[http://www.dbxml.com/uri]elem
Index 'nsElem_Value' created
第一个索引，‘myElem_ID_Value’，为集合中元素名为‘myElem’的‘id’属性创建一个强制整型索引。
第二个索引，‘myElem_Name’，为所有包含名为‘myElem’元素的文档建立名字索引。
第三个索引，‘myElem_Text’，为所有名为‘myElem’的元素创建一个关于集合的全文索引。
第四个索引‘anyElem_Status_Value’为集合中任意元素的所有‘status’属性创建裁剪字符串索引。
第五个索引‘nsElem_Value’为属于‘http://www.dbxml.com/uri’名字空间的所有‘elem’元素创建一个默认（字符串）值索引。
dbXML索引命令
命令
说明
用法
LSIDX
列出一个集合的Indexer
LSIDX [wildcard]
MKIDX
创建一个新的集合索引
MKIDX 'index name' [properties]
RMIDX
从集合中删除指定的Indexer
RMIDX 'indexer name'
5.5. 存取文档（Storing and Retrieving Documents）
管理和索引集合是一件极好的事情，但是如果在集合里没有可以被索引的东西，那么对你就是无益的。幸亏dbXML命令行工具也允许你输入到和从一个集合输出内容。
import和export命令有两个模式。都可以输入/输出单个文件，或使用通配符输入/输出多个文件。如果处理的是单个文件，命令允许你使用AS子句在文件系统与数据库之间改变文件的名字。如果处理的是多个文件，这个选项是不可用的。 import命令还允许你recurse一棵目录树来存储当前集合中所有匹配的文件。
下面的例子示范了输入一个单个文件并重命名它：
/myCollection> import myFile.xml AS myDocument.xml
接下来的例子示范了输入一整个目录到当前集合中：
/myCollection> import *.xml RECURSIVE
dbXML内容命令（dbXML Content Commands）
命令
说明
用法
LS
列出集合中的关键字
LS [wildcard]
SHOW
从一个集合中检索一个文档
SHOW 'document name'
IMPORT
往集合中输入内容
IMPORT 'filespec' [AS 'name'] [RECURSIVE]
EXPORT
从一个集合中输出内容
EXPORT 'filespec' [AS 'name']
RM
从集合中删除特定的内容
RM 'filespec'
5.6. 触发器和扩展（Triggers and Extensions）
触发器和扩展在dbXML中的管理基本相同，所以在一个合并的章节讨论它们是比较容易的。理解触发器和扩展最重要的事情是，它们的类对服务器必须是可用的，通过Java CLASSPATH或者在dbXML服务器启动前把它们打包到jar中并存储在DBXML_HOME/lib目录中。
这是一个往集合里添加触发器工具的例子：
/myCollection> mktrg name=myTrigger class=examples.ExampleTrigger
Trigger 'myTrigger' created
dbXML 触发器和扩展（Trigger and Extension）命令
命令
说明
用法
LSTRG
列出一个集合的触发器
LSTRG [wildcard]
MKTRG
注册一个集合触发器
MKTRG 'trigger name' [properties]
RMTRG
从集合中删除特定的触发器
RMTRG 'trigger name'
LSEXT
列出一个集合的扩展
LSEXT [wildcard]
MKEXT
注册一个集合的扩展
MKEXT 'extension name' [properties]
RMEXT
从集合中删除特定的扩展
RMEXT 'extension name'
5.7. 其他选项（Other Options）
有三种其他命令难于分类，所以它们被便利地放置在‘其他’选项类别中。这些命令包括设置命令行选项，关闭服务器，退出命令行等性能。
set命令有意思因为它允许你切换和改变不同的命令行选项。这些选项包括：
interactive – 默认设置为‘true’，它切换命令行交互模式。如果是false，命令行将不现实任何人机对话提示。
totals – 切换命令行是否显示列表总计。
durations – 切换命令行是否显示执行时间
verbose – 切换命令行在出错时是否显示详细的堆栈记录
confirm – 切换命令行在删除像集合这样的重要对象时是否确认询问
下例示范命令行选项设置：
/myCollection> set durations true
durations true
(Execution: 5ms)
其他dbXML命令（Other dbXML Commands）
命令
说明
用法
SET
设置或者显示交互模式特性
SET ['prop name' [value]]
VERSION
显示服务系统版本
VERSION
SHUTDOWN
关闭服务器
SHUTDOWN [exit code]
EXIT
退出交互模式
EXIT [exit code]
6. API概述（API Overview）
dbXML提供几个应用程序接口（application programmer interfaces，APIs）， 每一个都有自己的强项和弱点。一个应用程序开发者选择哪个API通常取决于他们特殊的工程的需求。本节将简要论述每一个API 及其好处。
dbXML API的完全设置资料可以在DBXML_HOME/docs/api 目录下找到。
注意：
贯穿这些部分，类和接口定义将被呈现。这些定义将几乎总是未完成的，通常忽略JavaDoc，非公用方法和字段，非必要方法和字段，以及发射子句（throws clauses）。它们的用意是成为一个快速的参考而不是一个完全的定义。
6.1. 直接的API（The Direct API）
直接的API是由dbXML的内在类层次定义的接口。开发者可以最近地接触到dbXML引擎的内部处理。用这个API暴露的类和方法是非常低层次的，开始时会令人畏缩。
直接API更难的一个方式是这个API使用内在化的dbXML DocumentTable表示来暴露XML文档。DocumentTables对于存储和索引是完美的，但是对于应用开发者来说难于操作。为了减轻潜在的挫折，直接API也提供一个允许开发者包围DocumentTable APIs的适配器系统（Adapter system）。dbXML为DOM Documents，SAX Handlers和JAXB捆绑类提供适配器。
6.2. dbXML客户API（Client API）
dbXML客户API为嵌入和客户/服务器情况下访问dbXML的通用接口。暴露的接口和方法在许多方面与直接API相似，但是为某些数据库的内部处理提供缓冲服务。这种缓冲的一个很好的例子是，dbXML客户API为处理文本或者文档DOM表示暴露专门的方法，而直接API只暴露内在化的dbXML DocumentTable 表示。
6.3. XML:DB API
XML:DB API是一个为了以一般方式访问XML数据库而提供的抽象接口。几个XML数据库实现了这个API，所以它为开发可移植的应用程序提供最大的潜力。
6.4. Web Services Access在覆盖下面，dbXML是一个web服务器，并且提供对其下面的功能的完全的HTTP访问。服务器的大多数功能可以使用XML-RPC协议访问。有些特征也可以直接使用REST协议（URL编码）访问。
