BlackBerry 应用程序开发者指南 第一卷：基础--第1章 BlackBerry API

使用 BlackBerry API
在BlackBerry设备上使用Java
应用程序控制
使用BlackBerry APIBlackBerry Java 开发环境（简称JDE）的设计提供了一套完整的API和工具,来开发在BlackBerry设备上运行的Java应用程序。
BlackBerry设备包含了一个基于CLDC1.1以及MIDP的Java ME（Java Platform Micro Edition）运行时环境。BlackBerry API扩展提供了额外的功能,并且和BlackBerry集成得更紧密。
你可以在你的应用程序中使用CLDC/MIDP和BlackBerry API。为了能让你的应用程序在任何采用JTWI（Java Technology for Wireless Industry，无线领域的Java技术）的设备上运行，你仅需要使用CLDC和MIDP API来编写标准的MIDP应用程序。
[if gte vml 1]>

BlackBerry手持设备软件组件

为了查看API 参考。点击任务栏的开始>程序>Research In Motion>BlackBerry JDE 4.1.0>API Java Doc Reference
BlackBerry APIBlackBerry API为访问BlackBerry特性提供了用户界面，本地化，网络，以及其他功能。
注：访问某些特性，如高级的加密，同步，以及消息的额外API，是受限制的。为了使用这些API,你必须收到专门来自Research In Motion的认证中心编写的许可。为了得到更多信息，参看 BlackBerry 应用程序开发者指南第一卷：基础第二卷：高级。

BlackBerry API 包
描述

net.rim.blackberry.api.browser
应用程序可以调用BlackBerry浏览器，为了得到更多信息，参看 BlackBerry 应用程序开发者指南 第二卷：高级。

net.rim.blackberry.api.invoke
允许应用程序调用BlackBerry应用程序，如任务，消息，备忘录以及电话。为了得到更多信息，参看 BlackBerry 应用程序开发者指南 第二卷：高级。

net.rim.blackberry.api.mail
定义了必要的功能来将内部的RIM消息系统对象组件转化为和Mail API兼容并可移植的对象。同时也提供了发送，接收，以及访问消息的功能。为了得到更多信息，参看 BlackBerry 应用程序开发者指南 第二卷：高级

net.rim.blackberry.api.mail.event
定义了消息事件以及监听者（Listener）接口来管理邮件事件。为了得到更多信息，参看 BlackBerry 应用程序开发者指南 第二卷：高级

net.rim.blackberry.api.menuitem
允许应用程序在BlackBerry的应用程序例如地址本，日历以及消息中增加客户定制的菜单项，为了得到更多信息，参看 BlackBerry 应用程序开发者指南 第二卷：高级

net.rim.blackberry.api.options
允许应用程序在BlackBerry设备的选项中增加选项条目。为了得到更多信息，参看 BlackBerry 应用程序开发者指南 第二卷：高级

net.rim.blackberry.api.pdap
允许应用程序和BlackBerry个人信息管理（PIM）交互，PIM包括地址本，任务，日历。MIDP包javax.microedition.pim提供了类似的功能。为了得到更多信息，参看 BlackBerry 应用程序开发者指南 第二卷：高级

net.rim.blackberry.api.phone
提供了访问电话应用程序的高级特性。为了得到更多信息，参看 BlackBerry 应用程序开发者指南 第二卷：高级

net.rim.blackberry.api.phone.phonelogs
提供了访问电话呼叫历史记录的功能。为了得到更多信息，参看 BlackBerry 应用程序开发者指南 第二卷：高级

net.rim.device.api.bluetooth
允许BlackBerry应用程序在一个蓝牙序列端口连接的基础上与打开蓝牙无线技术的设备进行通信。为了得到更多信息，参看103页的“使用蓝牙序列端口连接”.

net.rim.device.api.browser.field
允许程序在界面上显示浏览器的字段。为了得到更多信息，参看 BlackBerry 应用程序开发者指南 第二卷：高级

net.rim.device.api.browser.plugin
允许程序增加额外支持的MIME类型到BlackBerry浏览器上。为了得到更多信息，参看 BlackBerry 应用程序开发者指南 第二卷：高级

net.rim.device.api.collection
net.rim.device.api.collection.util
为管理数据集合定义了接口和实用类。为了得到更多信息，参看13页的“集合”.
net.rim.device.api.compress
提供实用类来进行GZip和ZLib数据压缩。[1]
net.rim.device.api.i18n
提供类来支持BlackBerry设备上应用程序的本地化。为了得到更多信息，参看13页的“本地化应用程序”.
net.rim.device.api.io
提供一个定制的BlackBerry类库来管理数据的输入和输出。
net.rim.device.api.mime
提供与MIME编码的数据流一起工作的类。
net.rim.device.api.notification
提供触发事件的通知以及响应系统以及程序的事件的方法。为了得到更多信息，参看 BlackBerry 应用程序开发者指南 第二卷：高级
net.rim.device.api.servicebook
允许程序增加，删除，以及访问服务约定（Service Book）[2]的接口。为了得到更多信息，参看 BlackBerry 应用程序开发者指南 第二卷：高级
net.rim.device.api.system
提供访问系统级的功能，包括键盘和滑轮的事件监听者，图像创建和支持，和应用程序控制。
net.rim.device.api.ui
提供增强的功能来控制BlackBerry用户界面，包括屏幕和控件布局管理，控件类型支持，焦点，滚动，以及改变监听者。为了得到更多信息，参看39页的“用户界面API”.
net.rim.device.api.ui.component
提供了创建UI程序的界面组件库。为了得到更多信息，参看39页的“显示用户界面组件”。
net.rim.device.api.ui.container
提供创建UI程序的界面管理组件的库。为了得到更多信息，参看49页的“管理用户界面组件”。
net.rim.device.api.ui.text
提供类对文本字符串进行过滤，包含多种类型的数据，例如电话号码或URL。
net.rim.device.api.util
提供实用的方法和接口，包含数组，哈希表，字符匹配。
CLDC APICLDC API 包
描述
java.io
提供数据流的系统输入和输出。
java.lang
提供Java编程语言基础类。
java.lang.ref
提供引用对象类，它们支持一定程度上的垃圾回收。
java.util
包含集合类，时间，以及多样的实用类。
javax.microedition.io
包含一般连接的类。
MIDP APIMIDP API 包
描述
javax.microedition.lcdui
包含MIDP 用户界面API，它为MIDP应用程序的用户界面实现提供了一组特性。
javax.microedition.lcdui.game
包含了可以为BlackBerry设备进行丰富游戏内容开发的类。
javax.microedition.midlet
定义了MIDP应用程序以及应用程序和应用程序运行的环境之间的交互。
注：BlackBerry IDE可以在启动时，使参数传递到一个BlackBerry CLDC应用程序中。
javax.microedition.pki
定义了用来验证安全连接信息的证书。
javax.microedition.rms
为MIDlet提供一种机制来存储和取得持久性数据。
PDAP APIMIDP API 包
描述
javax.microedition.pim
.提供标准机制来访问PIM信息。
在BlackBerry设备上使用Java编译源代码，打包为.cod文件，并将.cod文件加载到BlackBerry设备上，通过虚拟机运行。
[img,13,13]file:///C:/DOCUME%7E1/CONFAC%7E1.ZHA/LOCALS%7E1/Temp/msohtml1/01/clip_image002.gif[/img]注：.cod文件名控制在128字节。
如CLDC中描述的那样，BlackBerry IDE使用一个分割的VM架构。为了降低内存的数量以及BlackBerry设备需要的处理能力，部分类加载过程，称为预验证，它在Java代码加载到BlackBerry之前发生。在将源代码打包为.cod文件之前，自动验证它。在类加载到BlackBerry设备时完成验证的提示。
限制在CLDC1.1中描述的那样BlackBerry虚拟机有以下限制：

• 没有对象的析构（finalization）
• 没有用户类的加载
• 没有反射，因此不支持RMI和Jini网络技术。
• 没有原生方法（Native method）
• 没有Runtime.exec()执行外部的进程

多线程BlackBerry Java环境提供一个真正的多线程环境来运行应用程序。这个环境允许多个应用程序同时运行，允许事件广播到多个应用程序，以及长操作和监听线程在背后运行。
持久数据存储在闪存中的数据在BlackBerry重新设置之间持久保存。在BlackBerry设备上存储数据可以采用以下二种方式中的一种：

• 使用MIDP记录存储
• 使用BlackBerry持久模型

为了得到关于使用BlackBerry API存储持久数据的更多信息，参看BlackBerry应用程序开发者指南第一卷：基础 第二卷：高级。
网络通信BlackBerry JDE根据MIDP2.0，实现了网络通信。它提供多种连接选项，包括通过使用HTTP代理连接在公司防火墙背后安全连接的能力。
BlackBerry JDE提供了以下几种连接类型：

• 流连接（StreamConnection接口，包括：

1. HTTP 连接（HttpConnection接口）
2. HTTPS连接（HttpsConnection接口）
3. Socket连接（SocketConnection接口）
4. 安全socket连接（SecureConnection接口）
5. 序列连接到BlackBerry设备的一个通信接口（CoomConnection接口）

• 数据报连接（DtagramConnection接口），包含

1. UDP数据报连接（UDPDatagramConnection接口）
Javax.microedition.io.PushRegistry 类对BlackBerry设备保持了一些进入的连接。
流 BlackBerry JDE为包含在CLDC java.io包里的流提供了标准的接口和类。
MIME编码
BlackBerry IDE提供了MIMEInputStream和MIMEOutputStream类来读写一个MIME编码的数据流。
类
描述
MIMEInputStream
实现一个流来读取一个MIME消息，然后根据MIME标准格式化和分解这个消息为其部分
MIMEOutputStream

实现一个输出流，这个流可以根据MIME标准格式化输出为其部分。本类不会完成实际的数据编码，因此你必须在写入它到本数据流治安编码它。
压缩
在net.rim.device.api.compress包里，BlackBerry JDE提供类来读取使用Zlib或者GZip格式压缩的数据流。这些类的行为如Java标准版本里的java.util.zip包里对应的类一样。
缺省的，压缩是允许的，BlackBerry设备可以写有效的GZip和Zlib文件为这样压缩文件的内容。解压缩同样也是支持的。
集合BlackBerry IDE 提供了一组接口和实用类来管理BlackBerry设备上的集合。
net.rim.device.api.collection包包含了许多接口，这些接口为某些特定类型数据类型多定义了种类型的集合，例如列表，数组以及映射。这些接口定义了与Java标准版本集合框架的list,set和map接口类似的功能。
在你自己的类中实现这些接口，或者使用在net.rim.device.api.collection.util包里提供的使用类。
向量
标准的java.util.Vector实现了一个大小可以改变的对象数组。BlackBerry JDE也提供了合适的类，例如rim.device.api.util.IntVector和rim.device.api.util.ByteVector来对主要类型进行工作。这些类看起来和普通的Vector一样,除了它们优化了在任何位置上插入的项。相反，如果你使用标准的大Vector作随机的改变，大量的数据会在闪存和RAM移动。
列表
BlackBerry JDE在net.rim.device.api.collection.util包里提供了一些类来管理元素的列表
类
描述
SortedReadableList 和
UnsortedReadableList
使用这些类来维护已排序的和未排序的元素列表。SortedReadableList类需要你使用一个比较对象来排序列表中的元素。增加到列表中的每一个元素必须被比较对象视为有效的。
IntSortedReadableList 和LongSortedReadableList
使用这些类自动排序整形列表或与长整形关键字相关的元素。
BigSortedReadableList 和 BigUnsortedReadableList
使用这些类来存储大的数据集合（大于10或者15K).这些类不会存储数据到一个数组中，因此你可以对大数据集合更有效的做出随意改变。
ReadableListCombiner

使用这个类合并2个或者更多的ReadableList对象并且将他们作为一单个ReadableList来存储。
ReadableListUtil
此类提供一些有用的方法如getAt()和getIndex()。我们可以使用此类得到只读列表中的数

哈希表
除了CLDC提供的标准java.util.Hashtable 之外，BlackBerry JDE包含了特定的net.rim.device.api.collection.util.LongHashtableCollection类，这个类提供了使用长整形作为关键字的哈希表集合。一个LongHashtableCollection 对象，写操作作为一个映射（使用一个关键字-元素对），读操作作为一个映射或者作为一个集合（在集合里作为一个数组来得到数据）。
事件监听者事件监听者接口根据事件类型划分。每个应用程序注册来接收特定类型的事件。应用程序事件队列然后调度事件到一个合适的监听者。
应用程序可以实现合适的监听者接口或者在各种Screen对象里重写监听者方法。大多数应用程序实现了KeyListener 和TrackwheelListener 接口，而且注册了监听者来接收键盘和滑轮的事件。键盘和滑轮是用户和应用程序交互的主要方式。
下列的事件监听者放在 net.rim.device.api.system包中
监听者接口
事件类型
AlertListener
实现接口来监听alert事件
BluetoothSerialPortListener
实现接口来监听蓝牙序列端口事件，例如打开一个蓝牙序列端口连接作为服务器或者客户端。
GlobalEventListener

实现接口来监听可以广播到所有应用程序的全局事件。
HolsterListener
实现接口来监听套装事件，例如BlackBerry设备从套装中插入和移开。
IOPortListener
实现接口监听I/O端口事件。
KeyListener

实现接口监听键盘事件，例如用户按住或释放一个键。
RealTimeClockListener
实现本接口来监听实时时钟事件，例如时钟更新。
SerialPortListener
实现此接口监听序列化端口事件，例如对于一个已经和计算机序列端口连接的BlackBerry设备，一个在数据正在被发送到序列化端口连接状态中的改变。
SystemListener

实现此接口来监听系统事件，例如电池状态和电源的改变。
TrackwheelListener
实现本接口监听滑轮事件，例如按住滑轮。
USBPortListener
实现本接口监听USB端口事件，例如对于一个已经和计算机USB端口连接的BlackBerry设备，数据正被发送到USB端口连接的状态。
系统功能net.rim.device.api.system包的类提供了访问Java VM和BlackBerry设备上系统资源的能力。
得到信号信息
RadioInfo提供了访问信号状态信息的能力。
得到设备信息
DeviceInfo类可以访问下列BlackBerry设备的信息：

• 电池电源和状态
• Blackerry设备号
• 空闲时间
• 平台版本

系统事件通知用户
当一个事件，例如一条新消息到来的时候，Alert类允许应用程序通知用户。
监视内存使用情况
使用一个Memory类提供的静态方法来得到VM内存使用统计信息。
Memory类很多实用方法返回一个MemoryStats对象。使用MemoryStats类提供的实用方法得到BlackBerry设备上内存和可用存储空间的详细信息。
日志事件
EventLogger允许应用程序在持久存储里存储事件日志。BlackBerry设备维护事件队列，以至当日志满时，会删除最早的事件，并增加新的事件。用户可以按住Alt+lglg键来查看BlackBerry设备的系统事件日志。
使用工具BlackBerry JDE在net.rim.device.api.util包里提供了一组实用工具，这些类里的许多类提供了和Java标准版本里相似的功能

• Comparator接口定义了对象集合上的顺序的方法。
• Arrays提供方法来操作数组，例如排序，查找，以及作为列表来查看数组。
• BitSet 类维护bit的集合。

net.rim.device.api.util包包含了多个类来管理特定类型的数据集合，包括向量，哈希表，映射以及栈。
应用程序控制应用程序控制允许系统管理员操作以下动作：

• 控制内部连接（公司防火墙背后的连接）
• 控制外部连接
• 控制本地连接（序列和USB连接）
• 控制访问键存储(key store)
• 控制访问特殊的API.
• 阻止第三方应用程序存在BlackBerry设备上。

为了得到更多信息，参看BlackBerry Enterprise Server Handheld Management Guide的应用程序管理。
受限制访问的API, 类, 和方法
使用了下列受限的API,类，以及方法的应用程序可以加载到BlackBerry设备，但是如果他们访问了一个没有在应用程序控制下得到允许的API时，在运行时会抛出一个ControlledAccessException或者NoClassDefFoundError的异常。

类，方法或API
缺省值
应用程序菜单项API(net.rim.blackberry.api.menuitem)
允许
蓝牙API (net.rim.device.api.bluetooth)
允许
Connector.open() (javax.microedition.io)
提示
注:内部和外部的连接由不同的应用程序控制策略来管理
DeviceKeyStore 类 (net.rim.device.api.crypto.keystore)
允许
EventInjector 类 (net.rim.device.api.system)
不允许
HTTP Filter API (net.rim.device.api.io.http)
不允许
Notification API (net.rim.device.api.notification)
允许
电API 和 呼叫API (用来调用电话应用程序) (net.rim.blackberry.api.phone 和net.rim.blackberry.api.invoke)
允许(缺省，用户提示)
电话日志API (net.rim.blackberry.api.phone.phonelogs)
允许(缺省，用户提示)
PIM API (net.rim.blackberry.api.pdap)
允许
RuntimeStore 类 (net.rim.device.api.system)
允许
SerialPort 类 (net.rim.device.api.system)
允许
Session 类 (net.rim.blackberry.api.mail)
允许
StringPatternRepository 类 (net.rim.device.api.util)
允许
USBPort 类 (net.rim.device.api.system)
允许

[1] 也许有人会问，为什么BlackBerry需要压缩数据，又在什么地方用到呢?非常简单，就是减小数据所占用的空间,最好的一个例子是BES发送邮件，译者注。
[2] 服务约定，Service Book,这是BlackBerry使用中一个非常重要的概念。功能就是你订阅的服务，例如你订阅了MMS的功能，它会在你BlackBerry手持设备上出现。译者注。 <!--v:3.2-->