##language:zh
'''
系统说明书 文章模板
'''

Otter Tool系统说明

-- hd [<<DateTime(2004-08-14T22:48:06Z)>>]
<<TableOfContents>>
= 系统概述 =
''Otter Tool是一个代码自动生成工具，它通过解析一个描述我们所需协议的XML文件来自动生成我们这个协议的Python代码，这样我们为Otter Base添加一个新的协议的时候，只需要把协议的XML描述文件填好，然后运行一下Otter tool，一切就出现在眼前了：P－－just filling and running''

它将我们从代码的重复工作中解脱出来，让基于二进制流协议的开发更为简单，让开发人员更关注于业务逻辑而不是基础的twisted、窗口这些复杂的事务。

= 系统功能 =

Otter tool完成以下几项工作：
 1. 解析协议的XML描述文件
 2. 将从XML解析出来的数据结合模板填充成我们所需的Otter代码

而实际上我们真正需要做的工作就是：
 1. 按otter tools的规范填写XML文件
 2. 运行Otter tool生成相关代码
 3. 写你的服务器和客户端的业务逻辑罢

= 系统处理流程 =

在运行Otter Tool程序的时候我们需要输入一个协议的XML描述文件，Otter tool通过解析这个XML文件，调用预制的Python代码模板，填充后生成出这个协议的四个Python代码文件。它们分别是：
 * *pmsg.py 消息定义
 * *p.py 协议定义
 * *c.py 服务器端定义
 * *s.py 客户端定义

*号代表协议的名称。

这四个文件中，*msg.py是对协议的报文格式进行定义的，*p.py是对协议的传送协议进行定义的，*c.py是该协议的客户端，*s.py是该协议的服务器端。

在对新协议进行开发的时候，我们需要在XML文件中对协议的各个部分进行描述，运行Otter tool生成上述四个文件。*msg.py和*p.py是协议的定义文件，我们不需要再改动它们。对新功能的扩展，我们通过扩展*c.py和*s.py来完成。

= 系统静态结构和动态结构 =
== 系统静态结构 ==
Otter tool的静态结构分为三个部分，两个输入结构，一个输出结构。

=== XML描述文件结构 ===
XML描述文件的结构，其定义如下：
 * {{attachment:schemaMap.gif}}

==== 根元素 ====
根元素为<Otter>，它有三个属性，分别为：
||属性名||类型||状态||说明||
||Version||字符串||必须||标明协议的版本号||
||Persistent``Connection||布尔值||必须||是否为长连接协议||
||Protocol``Name||字符串||必须||协议名称。生成的协议代码将会存放在以次命名的子目录中||

 * {{attachment:040816-otter-00.jpg}}

==== 子元素 ====
子元素有两个，分别为<Message>和<Protocol>

<Message>属性：
||属性名||类型||状态||说明||默认值||
||Message``Name||字符串||可选||指定报文定义代码的名称||协议名+pmsg.py||
||Message``Head``Class||字符串||可选||报文头定义需继承的类||bytemsg.Byte``Message``Head||
||Message``Body``Class||字符串||可选||报文体定义需继承的类||bytemsg.Byte``Message``Body||

<Protocol>属性：
||属性名||类型||状态||说明||默认值||
||Protocol``Name||字符串||可选||传送协议代码的名称||协议名+p.py||
||Liseten``Port||整型||必须||传送协议使用的端口||||

==== 孙子元素 ====
<Message>有两个子元素，<Commands>和<Message``Head>。<Commands>元素负责描述报文中的命令列表，<Message``Head>元素负责描述报文头中包括那些内容。这两个元素没有属性。

<Commands>元素包含一个子元素<Command>，负责描述每个报文的命令。
<Command>属性：
||属性名||类型||状态||说明||
||Command``Name||字符串||必须||定义命令的名称||
||Command``ID||字符串||必须||定义命令的ID||

<Message``Head>元素包含一个子元素<Field>,负责对报文头中的每个内容进行描述
||属性名||类型||状态||说明||
||Field``Name||字符串||必须||定义域的名称||
||Field``Type||字符串||必须||定义域的类型||
||Field``Size||字符串||可选||定义域的大小||

<Command>元素包括一个子元素<Field>，这个元素的定义与<Message``Head>的子元素<Field>是相同的。

<Protocol>有两个子元素，<Client``Protocol>和<Server``Protocol>分别负责描述客户端传送协议中使用的命令和服务器端传送协议使用的命令。这两个子元素都没有属性。它们的子元素都是<Command>，在这里这个元素负责标识客户端的Protocol和服务器端的Protocol分别需要使用在<Message>元素中定义的那些<Command>，而不是声明一个新的<Command>。


=== 代码模板的结构 ===
=== 输出的代码结构 ===


== 系统动态结构 ==

= 系统模块及结构 =
 * 暂定:
{{{
+--OtterTool     OtterTool 主目录
|  +--OtterBaseTemplet    模板化的 OtterBase 代码库
|  +--doc     文档目录
|  |  +--api  epydoc生成的API文件目录
|  +--web     预备的 b/s 处理脚本目录
|  +--OtCUI.py     class ottcui:Otter Tools Commend User Interface;命令行用户界面;用以处理各种命令行的响应操作
|  +--OtFiler.py   class ottfp:文件伺候包;专门用以进行文件，目录的操作
|  +--OtTemplet.py class otttp:模板解析器;用以进行代码模板的处理，现在纯用 正则表达式 操作
|  +--OtTool.py    class ottools:Otter Tools main script;主类入口
|  +--OtXML.py     class ottxml:XML解析伺候包;专门用以进行XML的解析，操作
|  \--timer.py   class timer:通用Python 程序运行计时器
+--ottertools.xsd OtterTool XML Schema
\--uss.xml       处理目标 XML 示例
}}}
== 开发日志及资料 ==
 * [[zqOtterDevLog]] -- Otter 核心开发日志
 * [[http://220.248.2.35:7080/share/Python/OpenUSS/Otter/OtterTool/|Zoomq版本OtterTool浏览]]--包含API文档,随时更新!
 * [[http://www-900.ibm.com/developerWorks/cn/xml/x-matters/part28/index.shtml|使用 ElementTree，以 Python 语言处理 XML]]

= 系统外部接口与外部系统 =