StarSuite 7
Developer's Guide
January 2004
This documentation is distributed under licenses restricting its use. You may
make copies of and redistribute it, but you may not modify or make derivative
works of this documentation without prior written authorization of Sun and its
licensors, if any.
Copyright 2004 Sun Microsystems, Inc.
Contents
1 读者指南
27
1.1 本手册包含的内容 .................................................................................................................. 27
1.2 本书的结构 ................................................................................................................................. 27
1.3 StarSuite 版本历史记录 ........................................................................................................... 28
1.4 相关文档 ..................................................................................................................................... 28
1.5 惯例 ............................................................................................................................................... 28
1.6 致谢 ............................................................................................................................................... 29
2 准备工作
31
2.1 使用 UNO 编程 .......................................................................................................................... 31
2.2 UNO 的应用程序领域 ............................................................................................................ 31
2.3 入门 ............................................................................................................................................... 32
2.3.1 所需的文件 ................................................................................................................... 32
2.3.2 安装集 ............................................................................................................................. 32
2.3.3 配置 ................................................................................................................................. 33
在 StarSuite 中开放 Java ...................................................................................... 33
使用 Java UNO 类文件 ........................................................................................ 33
使 Office 进行侦听 ............................................................................................... 33
将 API 参考加入到 IDE 中 ................................................................................ 34
2.3.4 首次连接 ........................................................................................................................ 34
连接 ........................................................................................................................... 34
服务管理器 ............................................................................................................ 36
失败的连接 ............................................................................................................ 38
2.4 如何在 StarSuite 中获得对象 ................................................................................................ 39
2.5 使用对象 ..................................................................................................................................... 39
2.5.1 服务 ................................................................................................................................. 40
使用接口 ................................................................................................................. 42
使用属性 ................................................................................................................. 44
2.5.2 示例:使用工作表文档 ........................................................................................... 44
2.5.3 常见类型 ........................................................................................................................ 46
简单类型 ................................................................................................................. 46
字符串 ...................................................................................................................... 46
枚举类型和常数组 .............................................................................................. 47
2.5.4
Struct ................................................................................................................................. 47
2.5.5 Any .................................................................................................................................... 48
2.5.6 序列 ................................................................................................................................. 49
2.5.7 元素访问 ........................................................................................................................ 50
名称访问 ................................................................................................................. 52
索引访问 ................................................................................................................. 53
枚举访问 ................................................................................................................. 53
2.6 如何判断类型? ....................................................................................................................... 54
2.7 示例:文字、表格、图形 .................................................................................................... 54
2.7.1 文字、表格和绘图的通用机制 ............................................................................. 55
2.7.2 建立文字、表格和图形 ........................................................................................... 59
Writer 中的文字、表格和绘图 ........................................................................ 59
Calc 中的文字、表格和绘图 ........................................................................... 60
Draw 中的绘图和文字 ........................................................................................ 61
3 专业 UNO
63
3.1 简介 ............................................................................................................................................... 63
3.2 API 概念 ....................................................................................................................................... 64
3.2.1 数据类型 ........................................................................................................................ 64
简单类型 ................................................................................................................. 64
any 类型 ................................................................................................................... 65
接口 ........................................................................................................................... 65
服务 ........................................................................................................................... 67
结构 ........................................................................................................................... 70
预设值 ...................................................................................................................... 70
序列 ........................................................................................................................... 71
模块 ........................................................................................................................... 71
异常 ........................................................................................................................... 72
singleton .................................................................................................................... 72
3.2.2 了解 API 引用 ............................................................................................................... 73
规范、实现和实例 .............................................................................................. 73
对象复合 ................................................................................................................. 73
3.3 UNO 概念 .................................................................................................................................... 74
3.3.1 UNO 进程间连接 ........................................................................................................ 74
以侦听模式启动 StarSuite .................................................................................. 74
导入 UNO 对象 ..................................................................................................... 75
进程间桥的特性 ................................................................................................... 76
打开连接 ................................................................................................................. 76
建立桥 ...................................................................................................................... 79
关闭连接 ................................................................................................................. 80
示例:识别连接的客户端 ............................................................................... 81
3.3.2 服务管理器和组件上下文 ...................................................................................... 83
服务管理器 ............................................................................................................ 83
组件上下文 ............................................................................................................ 84
3.3.3 使用 UNO 接口 ............................................................................................................ 87
3.3.4 属性 ................................................................................................................................. 90
3.3.5 集合与容器 ................................................................................................................... 93
3.3.6 事件模型 ........................................................................................................................ 96
3.3.7 异常处理 ........................................................................................................................ 96
使用者自定的异常 .............................................................................................. 97
运行时异常 ............................................................................................................ 98
好的异常处理 ...................................................................................................... 98
3.3.8 UNO 对象的生存期 .................................................................................................... 99
acquire() 和 release() ............................................................................................... 99
XComponent 接口 ................................................................................................ 100
XEventListener 接口的子接口 ......................................................................... 102
弱对象和弱引用 ................................................................................................. 102
C++ 对象与 Java 对象的生存期之间的差异 ............................................. 103
3.3.9 对象身»½ ...................................................................................................................... 104
3.4 UNO 语言绑定 ......................................................................................................................... 105
Java 语言绑定 ............................................................................................................. 105
获取服务管理器 ................................................................................................. 106
处理接口 ............................................................................................................... 107
类型映射 ............................................................................................................... 108
3.4.2 UNO C++ 绑定 ............................................................................................................ 117
程序库概述 .......................................................................................................... 117
系统抽象层 .......................................................................................................... 119
文件访问 ............................................................................................................... 119
线程安全的引用计数 ....................................................................................... 119
线程和线程同步 ................................................................................................. 119
建立进程间连接 ................................................................................................. 121
3.4.1
3.4.3
类型映射 ............................................................................................................... 122
使用弱引用 .......................................................................................................... 126
C++ 中的异常处理 ............................................................................................. 127
StarSuite Basic ............................................................................................................... 128
处理 UNO 对象 ................................................................................................... 129
UNO 和 Basic 类型的映射 ................................................................................ 135
区分大小写 .......................................................................................................... 141
异常处理 ............................................................................................................... 142
侦听者 .................................................................................................................... 143
3.4.4 Automation 桥 .............................................................................................................. 145
简介 ......................................................................................................................... 145
要求 ......................................................................................................................... 145
快速游览 ............................................................................................................... 146
服务管理器组件 ................................................................................................. 148
从 Automation 使用 UNO .................................................................................. 149
类型映射 ............................................................................................................... 156
具有 UNO 接口的 Automation 对象 ............................................................. 166
DCOM ...................................................................................................................... 169
桥服务 .................................................................................................................... 171
不支持的 COM 功能 ......................................................................................... 174
4 编写 UNO 组件
175
4.1 必需的文件 ............................................................................................................................... 176
4.2 使用 UNOIDL 指定新组件 .................................................................................................. 177
4.2.1 编写规范 ...................................................................................................................... 177
预处理 .................................................................................................................... 178
将定义分组为模块 ............................................................................................ 178
基本类型 ............................................................................................................... 179
定义接口 ............................................................................................................... 180
定义 服务 .............................................................................................................. 182
定义 序列 .............................................................................................................. 185
定义结构 ............................................................................................................... 185
定义 异常 .............................................................................................................. 186
预设的值 ............................................................................................................... 186
使用 注解 .............................................................................................................. 188
Singleton .................................................................................................................. 189
预留的类型 .......................................................................................................... 189
4.2.2 从 UNOIDL 定义生成源代码 ................................................................................ 189
4.3 组件 体系结构 ......................................................................................................................... 191
4.4 要实现的核心接口 ................................................................................................................ 192
4.4.1 XInterface ....................................................................................................................... 194
queryInterface() 的要求 ...................................................................................... 195
引用计数 ............................................................................................................... 195
4.4.2 XTypeProvider .............................................................................................................. 195
提供的类型 .......................................................................................................... 196
ImplementationID .................................................................................................. 196
4.4.3 XServiceInfo ................................................................................................................... 196
实现名称 ............................................................................................................... 196
支持的服务名称 ................................................................................................. 197
4.4.4 XWeak ............................................................................................................................ 197
4.4.5 XComponent .................................................................................................................. 197
XComponent 的处置 ........................................................................................... 198
4.4.6 XInitialization ................................................................................................................ 198
4.4.7 XMain ............................................................................................................................. 198
4.4.8 XAggregation ................................................................................................................ 199
4.4.9 XUnoTunnel .................................................................................................................. 199
Java 中的简单组件 ................................................................................................................. 199
4.5.1 使用 Helper 类定义类 .............................................................................................. 200
XInterface、XTypeProvider 和 XWeak ............................................................. 200
XServiceInfo ............................................................................................................ 201
4.5.2 实现您自己的接口 ................................................................................................... 201
4.5.3 使用 Helper 方法提供单个工厂 ........................................................................... 202
4.5.4 使用 Helper 方法编写注册信息 ........................................................................... 203
4.5.5 没有 Helper 的实现 ................................................................................................... 204
XInterface ................................................................................................................ 204
XTypeProvider ....................................................................................................... 205
XComponent ........................................................................................................... 206
4.5.6 存储服务管理器以备后用 .................................................................................... 207
4.5.7 使用参数建立实例 ................................................................................................... 207
Java 组件的可能结构 ............................................................................................... 207
4.5.8
一个组件文件一个实现 .................................................................................. 208
一个组件文件多个实现 .................................................................................. 209
4.5.9 运行和调试 Java 组件 .............................................................................................. 212
注册 ......................................................................................................................... 212
4.5
调试 ......................................................................................................................... 213
StarSuite 中的 Java 环境 .................................................................................... 214
疑难解答 ............................................................................................................... 215
4.6 C++ 组件 .................................................................................................................................... 216
4.6.1 使用 Helper 模板类定义类 .................................................................................... 217
XInterface、XTypeProvider 和 XWeak ............................................................. 217
XServiceInfo ............................................................................................................ 218
4.6.2 实现您自己的接口 ................................................................................................... 218
4.6.3 使用 Helper 方法提供单个工厂 ........................................................................... 219
4.6.4 使用 Helper 方法编写注册信息 ........................................................................... 221
4.6.5 提供实现环境 ............................................................................................................ 221
4.6.6 不使用 Helper 的实现 .............................................................................................. 221
XInterface 实现 ...................................................................................................... 221
XTypeProvider 实现 ............................................................................................ 223
提供单个工厂 ..................................................................................................... 223
编写注册信息 ..................................................................................................... 224
4.6.7 存储服务管理器已备后用 .................................................................................... 225
4.6.8 使用参数建立实例 ................................................................................................... 225
4.6.9 一个动态链接库中的多个组件 ........................................................................... 225
4.6.10 建立并测试 C++ 组件 .............................................................................................. 226
建立过程 ............................................................................................................... 226
测试注册并使用 ................................................................................................. 226
4.7 将组件集成到 StarSuite ......................................................................................................... 228
4.7.1 协议处理程序 ............................................................................................................ 229
概览 ......................................................................................................................... 230
实现 ......................................................................................................................... 230
配置 ......................................................................................................................... 239
安装 ......................................................................................................................... 241
4.7.2 作业 ............................................................................................................................... 241
概览 ......................................................................................................................... 241
执行环境 ............................................................................................................... 242
实现 ......................................................................................................................... 243
初始化 .................................................................................................................... 245
返回结果 ............................................................................................................... 247
配置 ......................................................................................................................... 248
安装 ......................................................................................................................... 250