专注于blackberry » api

每周一技：HyperLinkField

Taigoo — Tue, 14 Jul 2009 11:35:11 +0000

这是每周一技的第二篇了。

前一篇介绍了从BES读取contacts的技术以及遇到相关问题的解决方案（via 每周一技:从BES服务器上lookup联系人）。

本篇将介绍如何编写自定义的超级链接控件。

背景

在很多情况下，我们都会遇见超级连接的显示，遗憾的是在Blackberry没有提供类似于HyperLinkField的组件，这给我们增加了很多麻烦，如果能够解决该问题，将会是一个不错的选择。

分析

既然Blackberry API没有，我们自己可以写一个该Field，在这里，我们将之命名为HyperLinkField，以符合Blackberry API命名的规则。

实现

先看几张效果图：

图1，当focus在其他field时HyperLinkField的样式.

图2 当光标移到该field上时，颜色会变蓝，当然你也可以更改颜色。

图3，当点击该Field时，

图4，其菜单如下

该Get Page就会打开连接。

在编写代码需要注意一下几个地方：

参数的设置
Layout的处理
如何paint
菜单的处理
点击该field如何处理

下面给出部分重要的代码。

package com.taigoo.blackberry.weekskills.hyperlink;

import net.rim.device.api.ui.Color;
import net.rim.device.api.ui.DrawStyle;
import net.rim.device.api.ui.Field;
import net.rim.device.api.ui.MenuItem;
import net.rim.device.api.ui.ContextMenu;
import net.rim.device.api.ui.Font;
import net.rim.device.api.ui.Graphics;
import net.rim.device.api.ui.XYRect;
import net.rim.device.api.system.Display;
import net.rim.blackberry.api.browser.*;

public class HyperLinkField extends Field {

    private String _displayName ;
    private String _url;
    private Font _font;
    private MenuItem _openMenuItem;

    /**
     * Create a field for the hyperlink to implement the behaviour.
     * @param text  The text to display
     * @param url  The url to navigation
     */
    public HyperLinkField(String text, String url) {
        super();
        this._displayName = text;
        this._url = url;
        this._font = Font.getDefault().
                  derive(Font.DOTTED_UNDERLINED).
                  derive(Font.UNDERLINED);

        //create the menu item
        this._openMenuItem = new MenuItem("Get Page",100000,10) {
            public void run() {
                openUrl();
                }
               };
        }

        /**
         * set the display name
         * @param name
         */
        public void setDisplayName(String name) {
                this._displayName = name;
        }

        /**
         * Get the url
         * @return returns the url
         */
        public String getURL() {
                return this._url;
        }

        /**
         * @see net.rim.device.api.ui.Field#paint(Graphics)
         */
        protected void paint(Graphics g) {

                //draw text
                g.setColor(Color.BLUE);
                g.setFont(_font);
                g.drawText(this._displayName, 0, 0,(int)(
                        getStyle() & DrawStyle.ELLIPSIS |
                        DrawStyle.HALIGN_MASK ),
                        this.getPreferredWidth() );

                this.invalidate();
        }

        /**
         * @see net.rim.device.api.ui.Field#layout(int, int)
         */
        protected  void layout(int width , int height) {
                width = Math.min(this.getPreferredWidth(), width) ;
                height = getPreferredHeight() ;
                 // set dimensions
        setExtent( width, height );
        }

     protected void drawFocus(Graphics graphics,boolean on){
         XYRect rect = new XYRect();
         getFocusRect(rect);
         graphics.setColor(Color.RED);
         graphics.setDrawingStyle(Graphics.DRAWSTYLE_FOCUS, true);
         drawHighlightRegion(graphics, Field.HIGHLIGHT_FOCUS, on,
          rect.x, rect.y, rect.width, rect.height);
         this.invalidate();

     }

     protected  boolean navigationClick(int status, int time){
            openUrl();
             return true;

        }

     private void openUrl() {
         BrowserSession visitSession = Browser.getDefaultSession();
         visitSession.displayPage(_url);
         }

     protected  void  makeContextMenu(ContextMenu contextMenu){
          contextMenu.addItem(_openMenuItem);
          contextMenu.setDefaultItem(_openMenuItem);
     }
}

上面的代码已经很能说明问题了，我就不多解释了。

Field写好之后就是调用。调用也非常简单，和普通的代码一样，代码如下

 HyperLinkField _hyperlinkField = new HyperLinkField(
                      "Click here to visit Inbalckberry",
                      "http://www.inblackberry.com/blog/wap");
        this.add(_hyperlinkField);

每周一技术系列

每周一技:从BES服务器上lookup联系人

故技重施：Blackberry Push API

Taigoo — Mon, 29 Jun 2009 11:46:20 +0000

大概是6月初，RIM以很强的声势推出一个新服务，名曰Blackberry Push API。在没有看文档前，我非常憧憬RIM能给我们带来惊喜。但是我看完之后，发现RIM仅仅把原来的技术重新包装了一遍。

从商业的角度讲，我非常赞成RIM的这种做法，现在的很多新概念有很多都是把N年以前的东西拿出来翻新一下，例如AJax，SaaS等，都取得了不错的效果。

但是从技术角度上讲，也确实没什么。

我将该服务总结为一句话，即将Blackberry最具特色的PUSH功能应用到客户的需求上。

即便如此，我还是将我N年以前使用过的技术重温一下，顺便也说说PUSH API 的应用。

应用背景：

先举个例子，未必是真实的。假如上海有家出租车公司小众（不是大众），要通知司机小张，有个客户在人民广场的来福士广场有个客户于14：00需要车，那么小众通过何种方式将这个信息传给小张呢?假如小众公司正在使用Blackberry的服务，那么可以通过Alert的方式来实现。

现在总结一下：

alert
新闻
财经
定单
文档
体育

服务不仅仅限于上面。

原理：

先看张图

简要解释一下：

先解释身份角色：

Push Initiator：相当于小众公司，后面见车简称PI

Blackberry Push Data Server：相当于部署在小众公司的Blackberry服务基础架构，后面简称BPIS

Mobile Client：司机小张的Blackberry终端，简称，MC

再解释一下流程：

PI发送一个push请求，即客户信息
BPIS给出一个返回给PI
BPIS就请求push给MC
MC收到后给出一个ACKnowledge，确认
BPIS给PI一个通知
PI收到后给BPIS一个返回

类似的机制和互联网的三次握手类似，就是Request/ACK/Response.目的就是为了保证大家都收到。

优点

很显然，省电，能够及时送达，安全，包括传送，以及安全送达。

实现

PAP
XML HTTP 请求
几种push，例如submit，cancel，query等，具体技术细节不讲，因为这些又可以单独拿出来了。

综合上述，如果您熟悉PUSH，是不是觉得似曾相识呢。

不管怎么说，从中，我们可以进一步，也更清晰了解Blackberry PUSH这个概念。这在以后的解决方案中提供不少思路。

黑莓通过编程的方式挂电话

Taigoo — Mon, 13 Oct 2008 09:56:25 +0000

最近使用了很多在Blackberry运行的来电防火墙软件。其实他们的实现方式很简单。

先分析一下，如何挂断电话呢？如果你在RIM提供的API里找一圈，你会特别失望，因为它根本没有提供对应的API。这点上，我觉得RIM特别不道德。

但是是不是没有方法了呢？我觉得办法还是有的。

我想出的办法就是模拟挂电话这个操作。

3个步骤：

按下去:press down
按住，哪怕0.1s:Hold on
松开: press up

代码如下：

EventInjector.KeyEvent pressEndKey=
    new EventInjector.KeyEvent(EventInjector.KeyEvent.KEY_DOWN,
Keypad.map(Keypad.KEY_END),KeypadListener.STATUS_NOT_FROM_KEYPAD,100);

EventInjector.KeyEvent releaseEndKey=
                new EventInjector.KeyEvent(
                    EventInjector.KeyEvent.KEY_UP,
                    Keypad.map(Keypad.KEY_END),
                     KeypadListener.STATUS_NOT_FROM_KEYPAD,100);

EventInjector.invokeEvent(pressEndKey);
EventInjector.invokeEvent(releaseEndKey);

是不是觉得很简单呢。

不过，这个方法，包括我上面说的几个软件都有一个共同的缺点，而且我认为是一个特别不好的方式，那就是当对方拨通电话之后，响了一声就挂断。这对于打电话的人来说是特别不友好的。

试想一下，你如果打电话给对方，然后啪一声挂了，接着你又打，又是啪一声。你什么感觉？

BlackBerry 应用程序开发者指南第二卷：高级–第12章管理应用程序

Taigoo — Mon, 28 Apr 2008 22:17:57 +0000

第12章管理应用程序

应用程序管理器

管理代码模块

应用程序管理器

BlackBerry设备VM有一个应用程序管理器,它的功能和对于其他Java程序的操作系统事件调动中心一样.

net.rim.device.api.system.ApplicationManager类使应用程序可以和应用程序管理器交互,并完成下面的操作:

与进程交互,例如获取前台应用程序的ID.
发送一个全局事件给系统.
锁住或解锁BlackBerry设备,或判断BlackBerry设备是否锁住.
立即运行一个程序,或者在一个特定的时间运行应用程序.

为了使用ApplicationManager类的任何方法,你必须获取一个当前应用程序管理器的引用.调用getApplicationManager()获得当前应用程序管理器.

ApplicationManager manager = ApplicationManager.getApplicationManager();

获取应用程序的相关信息

调用静态方法ApplicationManager.getVisibleApplications()获取当前运行的进程信息.例如,你可以编写一个系统管理应用程序来记录BlackBerry设备的状态,以决定用户使用每个应用程序所花费的时间.

对于正在运行的可见应用程序,为获取一组ApplicationDescriptor对象,调用getVisibleApplications().一个ApplicationDescriptor对象包含了应用程序的描述性信息,例如它的名称,图标,主(Home)屏幕的位置,以及资源包(bundle).使用ApplicationDescriptor方法获取这个信息.例如,为获取一个运行应用程序的名称,调用一个应用程序描述(descriptor)上的getName()方法.

ApplicationManager manager = ApplicationManager.getApplicationManager();

ApplicationDescriptor descriptors[] = manager.getVisibleApplications();

// Retrieve the name of a running application.

String appname1 = descriptors[0].getName()

为当前应用程序获取一个ApplicationDescriptor,调用

ApplicationDescriptor.currentApplicationDescriptor().

ApplicationDescriptor descriptor =

ApplicationDescriptor.currentApplicationDescriptor();

String appname = descriptor.getName();

发布一个全局事件

使用ApplicationManager.postGlobalEvent()作为基本机制和其他进程进行通讯.

注:你也可以使用运行时存储发送和接收进程间的消息.为获得更多信息,参看135页的”在应用程序之间共享运行时对象”.

为了发布一个全局事件到指定的应用程序中,调用postGlobalEvent(int, long, int, int, Object, Object).

processID参数指定了进程的ID发送事件.为获取一个进程ID,调用getProcessId(ApplicationDescriptor). guid参数为事件指定一个GUID值.数据和对象为事件指定附加的信息.

为了对所有应用程序发送一个全局事件,使用下面形式之一的postGlobalEvent()方法:

方法	描述
boolean postGlobalEvent(long)	发布一个带有唯一标志符的全局事件.
boolean postGlobalEvent(long, int, int)	发布一个带有附加数据的全局事件.
abstract boolean postGlobalEvent(long, int, int, Object, Object)	发送一个带有附加整数和对象数据的全局事件.

接收一个全局事件

net.rim.device.api.system.GlobalEventListener接口的实现接收全局事件. GlobalEventListener.eventOccurred()的实现定义了当一个全局事件发生时所发生的事情.

调用Application.addGlobalEventListener(GlobalEventListener)注册你的实现.

锁住一个BlackBerry设备

>调用 ApplicationManager.lockSystem(true).

决定一个BlackBerry设备是否锁住

>调用ApplicationManager.isSystemLocked().

解锁一个BlackBerry设备

>调用ApplicationManager.unlockSystem(true).

用不同的参数运行一个应用程序

创建一个新的应用程序描述

.使用已经存在的ApplicationDescriptor作为一个模板.在main()里指定使用的参数.

ApplicationDescriptor template = ApplicationDescriptor.currentApplicationDescriptor();

String[] args = { "admin", "secure" };

ApplicationDescriptor newdescriptor = new ApplicationDescriptor(template, args);

ApplicationDescriptor 构造子有其他2种格式:

签名	描述
ApplicationDescriptor(ApplicationDescriptor, String, String[])	此格式允许你为新的ApplicationDescriptor指定一个名称.
ApplicationDescriptor(ApplicationDescriptor, String, String[], Bitmap, int, String, int)	此格式允许你指定一个名称,初始设置,包括一个应用程序图标,主屏幕的位置,以及资源包,还有应用程序标题的ID.

运行应用程序

使用一个新的ApplicationDescriptor对象运行应用程序.

ApplicationManager appmanager = ApplicationManager.getApplicationManager();

try {

appmanager.runApplication(newdescriptor);

}

catch(ApplicationManagerException) {

// Handle the error.

}

runApplication()方法创建一个新的进程,并且调用一个指定的描述上的导出main()方法,以及使用它的参数.如果可能,新进程会转移到前台来.

在指定的时间运行一个应用程序

>调用scheduleApplication()代替runApplication().

try {

appmanager.scheduleApplication(newdescriptor, 1728000, false);

}

catch(ApplicationManagerException) {

// Handle the error.

}

scheduleApplication(ApplicationDescriptor, int, Boolean) 方法需要下面的参数:

ApplicationDescriptor对象.
启动应用程序的时间,毫秒计.
Boolean值,true表示时间是绝对的(从January 1, 1970 UTC午夜开始计算),false表示时间相对于本地午夜的时间.

注:在指定的时间前如果重启或关闭BlackBerry设备,此应用程序不会执行.

管理代码模块

CodeModuleManager类在net.rim.device.api.system里,它允许你获取相关信息,并且管理BlackBerry设备上的代码模块.

一个代码模块是一个.cod文件,它是BlackBerry IDE里单个工程编译的文件.为了查看安装在BlackBerry设备上的第三方应用程序列表,单击Appication.单击Propoerties菜单项查看关于每一个应用程序的信息.

获取模块信息

CodeModuleManager类提供方法使应用程序可以获取BlackBerry设备上的相关信息,例如名称,类型,描述,版本以及创建日期.

为获取一个模块的句柄,调用getModuleHandle().将代码模块名作为一个参数.

int handle = CodeModuleManager.getModuleHandle("test_module");

调用CodeModuleManager类的方法获取指定的信息.

将模块句柄作为参数传给这些方法.

String name = CodeModuleManager.getModuleName( handle );

String vendor = CodeModuleManager.getModuleVendor( handle );

String description = CodeModuleManager.getModuleDescription( handle );

int version = CodeModuleManager.getModuleVersion( handle );

int size = CodeModuleManager.getModuleCodeSize( handle );

int timestamp = CodeModuleManager.getModuleTimestamp( handle );

获取一组句柄

为获取BlackBerry设备上所有存在的模块句柄,调用getModuleHandles()

int handles[] = CodeModuleManager.getModuleHandles();

String name = CodeModuleManager.getModuleName( handles[0]);

net.rim.device.api.system.CodeModuleManager类提供方法创建,保存,删除代码模块.这些功能允许一个BlackBerry设备上的应用程序可以无线接收.cod文件.

代码模块管理器方法

方法	描述
int handle = CodeModuleManager.getModuleHandleForObject( anObject );	此方法获取一个对象模块的句柄,在此模块里定义一个对象.
boolean library = CodeModuleManager.isLibrary( handle );	此方法决定一个模块是否为类库,如果是返回true,如果是应用程序返回false.
int size = CodeModuleManager.getModuleHandleForObject( anObject);	决定了模块包含的代码的大小(字节).
ApplicationDescriptor descriptors[] = CodeModuleManager.getApplicationDescriptiors( handle );	获得一组代码模块包含的所有描述.

创建一个模块

>调用createNewModule().将模块的大小(字节)作为参数:

int handle = CodeModuleManager.createNewModule( 3000 );

此方法返回模块的句柄,否则,如果不能创建模块,返回0.

当你创建模块时,为了将数据增加到其中,调用下面形式的createNewModule().将整个模块的时长度(字节)作为参数,一个字节数据将加到模块中, length参数指定了从增加的字节数组到模块开始的字节数.

static int createNewModule(int, byte[], int);

将数据写入模块

>调用writeNewModule().将数据的字节数组作为参数提供给本方法.

boolean success = CodeModuleManager.writeNewModule( handle, data, 0, data.length );

saveNewModule(int)返回CodeModuleManager类定义的结果代码之一,例如如果模块保存成功,返回CMM_OK.

从BlackBerry设备数据库删除一个模块

调用deleteModuleEx(int, Boolean).将模块的句柄作为参数删除,一个Boolean值指定是否删除模块和它包含的数据,或仅删除没有相关数据的模块.如果模块正在使用,它将在BlackBerry下次重启时删除.

int handle = CodeModuleManager.getModuleHandle("test_module");

if( handle != 0 ) {

Boolean success = CodeModuleManager.deleteModule( handle, true );

}

Last Updated:2007年2月6日

BlackBerry 应用程序开发者指南第二卷：高级–第13章应用程序间共享运行时对象

Taigoo — Mon, 28 Apr 2008 22:15:32 +0000

第13章应用程序间共享运行时对象

共享运行时对象

共享运行时对象

注: 当应用程序第一次访问运行时存储时,检查一个 NoClassDefFoundError.如果系统管理员通过应用程序控制限制访问运行时存储,将抛出此错误. 为获得更多信息,参看BlackBerry应用程序开发者指南 第2卷:高级第1卷:基础.

BlackBerry设备使用一个运行时存储提供一个中心位置,在此位置上应用程序可以共享运行时对象.缺省的,仅由RIM数字签名的应用程序才可以访问运行时存储上的数据.联系RIM获得关于如何控制访问你的数据的信息.

获取运行时存储

>调用RuntimeStore.getRuntimeStore().

RuntimeStore store = RuntimeStore.getRuntimeStore();

为增加或获得运行时对象,调用RuntimeStore上的方法.

注:运行时存储不是持久的,如果BlackBerry重启,运行时存储的数据将丢失.

增加一个运行时对象

>调用RuntimeStore.put(long, String). 将一个唯一long ID和存储的对象作为参数.

RuntimeStore store = RuntimeStore.getRuntimeStore();

// Create an object and a unique number to identify the object.

String msg = "Some shared text";

long ID = 0×60ac754bc0867248L;

// put() throws an IllegalArgumentException if an object with the same ID exists.

try {

store.put( ID, msg );

}

catch(IllegalArgumentException e) {

// Handle exception - an object with the same ID exists.

}

替换一个运行时对象

>调用 replace().

RuntimeStore store = RuntimeStore.getRuntimeStore();

String newmsg = "Some new text";

try {

// Returns the existing object with the specified ID if it exists; null

// otherwise.

Object obj = store.replace( 0×60ac754bc0867248L, newmsg);

}

catch(ControlledAccessException e) {

// Handle exception - insufficient permissions.

}

获取一个注册的运行时对象

>调用RuntimeStore.get(). 将对象ID作为参数.

RuntimeStore store = RuntimeStore.getRuntimeStore();

// get() throws a ControlledAccessException if your application does not have read access to the specified object.

try {

// get() returns the objectm with the specified ID if it exists; null

// otherwise.

Object obj = store.get(0×60ac754bc0867248L);

}

catch(ControlledAccessException e) {

// Handle exception.

}

获取一个未注册的运行时对象

>调用RuntimeStore.waitFor() 等待一个运行时对象注册.

RuntimeStore store = RuntimeStore.getRuntimeStore();

try {

Object obj = store.waitFor(0×60ac754bc0867248L);

}

catch(ControlledAccessException e) {

// Handle exception - insufficient permissions.

}

catch(RuntimeException e) {

// Handle exception - time out.

}

注如果指定ID的对象不存在, waitFor()会阻止一个MAX_WAIT_MILLIS的最大数.如果此时对象还没有注册, waitFor()将会抛出一个RuntimeException异常.

Last Updated:2007年2月6日

BlackBerry 应用程序开发者指南第二卷：高级–第11章管理通知(Notification)

Taigoo — Mon, 28 Apr 2008 22:04:50 +0000

第11章管理通知(Notification)

通知API

增加事件

响应事件

自定义系统的通知

通知API

通知API(net.rim.device.api.notification)让你可以为你的应用程序增加自定义事件,并且当自定义事件发生时,又允许你定义用户接收的通知类型.

注:当你的应用程序第一次访问通知API时,它将检查一个ControlledAccessException.如果系统管理员使用应用程序控制限制访问通知API,一将抛出个运行时异常.为获取更多信息,参看”BlackBerry应用程序开发者指南 第2卷:高级 第一卷:基础”.

通知事件类型	描述
短暂事件	系统通知,例如LED闪烁,振动或铃声.
延续事件	应用程序指定的通知,例如一个UI.

对于短暂事件,只要事件一发生,BlackBerry设备就会使用一个系统通知, 例如LED闪烁,振动或铃声,尽快将消息发送给用户.应用程序不可以请求一指定类型的通知.在手持设备配置(Profile)列表里,用户通过选择一个活动的配置和设置配置选项来控制它们如何接收短暂事件的通知.为了将一个自定义的系统通知加入到短暂事件,请实现Consequence接口.

在延续的事件里,BlackBerry设备根据事件的优先级将它们安排在一个队列里.当事件发生时,事件影响的应用程序可能为用户提供一个自定义的通知,一般是通过显示一个用户界面(UI)元素,例如一个对话框来完成.为了监听延续的事件,实现NotificationsEngineListener接口.BlackBerry设备不会为延续事件提供一个系统级的通知.

增加事件

注册一个新的事件源

创建一个唯一long ID

为每个通知事件定义一个long ID.

public static final long ID_1 = 0xdc5bf2f81374095L;

注:使用BlackBerry IDE将一个String转化为一个long,为你的应用程序创建一个long的标记符:

1.在BlackBerry IDE文本里,输入一个字符串.
2.选择字符串,右击,然后单击Convert “string” to Long.

定义一个源对象

定义一个为事件提供源的对象. toString()的实现返回显示在配置列表里的字符串.

Object event = new Object() {

public String toString() {

return "Notification Demo";

}

将你的应用程序注册一个通知源

为了将你的应用程序作为一个事件源加入到手持设备的配置列表里,调用NotificationsManager.registerSource().在此方法里,指定一个唯一的事件ID,源对象以及通知级别.

通知级别设置了事件的优先级,它决定了延续事件发生的顺序.以最高级到最低级的顺序,级别如下:

NotificationsConstants.CRITICAL
NotificationsConstants.SENSITIVE
NotificationsConstants.IMPORTANT
NotificationsConstants.DEFAULT_LEVEL
NotificationsConstants.CASUAL

注:优先级仅适用于延续事件.只要短暂事件触发,它们就会发生.当触发一个延续事件时,指定一个过期时间.如果事件在最高级事件之前已经过期,用户可能不会接收到此最低级事件的通知.

当BlackBerry设备启动时注册事件源

为了注册一个事件源,创建一个带有libMain()的工程,在BlackBerry设备启动时进行注册.

创建一个类库工程

1.在BlackBerry IDE, 创建一个工程.

2.右击工程,单击Properties.

3.单击 Application标签.

4.在Project type 下拉列里,单击Library.

5.选择Auto-run on startup.

6.单击OK.

7.定义libMain().

public static final long ID_1 = 0xdc5bf2f81374095L;

public static final Object event = new Object() {

public String toString()

{

return "Sample Notification Event #1";

}

};

public static void libMain(String[] args) {

NotificationsManager.registerSource(ID_1, event,

NotificationsConstants.CASUAL);

}

触发一个短暂事件

调用triggerImmediateEvent().短暂事件由标准的系统通知描述,例如铃声,振动,或LED.

NotificationsManager.triggerImmediateEvent(ID_1, 0, this, null);

triggerImmediateEvent方法接受下面的参数:

参数	描述
sourceID	启动事件(当调用registerSource()时指定)的应用程序的标志符.
eventID	应用程序事件标志符.
eventReference	应用程序事件cookie.
context	可选的上下文对象.

在大多数情况下,不要使用短暂事件,因为BlackBerry设备事件通知不会充分说明发生了什么事情.例如,如果BlackBerry设备振动,对于用户来说,它将很难知道到底是在你的应用程序里发生了一个事件,还是一个新消息已经到达了.如果你使用了短暂消息,考虑实现一个自定义的通知,例如一个特殊的铃声,来区分你的应用程序事件和其他BlackBerry设备事件.为获取更多信息,参看122页的”自定义系统通知”.

触发一个延续事件

调用negotiateDeferredEvent().一个延续事件让你的应用程序以一个UI元素,例如一个对话框通知用户

NotificationsManager.negotiateDeferredEvent(ID_1, 0, this, -1,

NotificationsConstants.MANUAL_TRIGGER, null);

negotiateDeferredEvent(long, long, Object, long, int, Object) 方法接受下面的参数:

参数	描述
sourceID	启动事件(当调用registerSource()时指定)的应用程序的标志符.
eventID	应用程序事件标志符.
eventReference	应用程序事件cookie.
timeout	事件过期时间,以毫秒计,当调用方法时的相对时间(忽略过期时间,除非trigger是OUT_OF_HOLSTER_TRIGGER)
trigger	要么是NotificationsConstants.OUT_OF_HOLSTER_TRIGGER,它指定了当BlackBerry设备和计算机断开时的事件,要么是NotificationsConstants.MANUAL_TRIGGER,它指定了应用程序本身触发事件.
context	可选对象,可以存储附加的,任意的参数来控制事件通知的状态或者行为.

如果你调用negotiateDeferredEvent(long, long, Object, long, int, Object),你的应用程序必须实现NotificationEventListener来监听事件并充分响应它.为获取更多信息,参看121页的”响应事件”.

取消一个事件

取消一个短暂事件

调用cancelImmediateEvent(long, long, Object, Object), 然后指定源以及事件ID．

NotificationsManager.cancelImmediateEvent(ID_1, 0, this, null);

取消一个延续事件

调用 cancelDeferredEvent(long, long, Object, int, Object), 然后指定源以及事件ID．

NotificationsManager.cancelDeferredEvent(ID_1, 0, this, NotificationsConstants.MANUAL_TRIGGER, null);

取消所有延续事件

调用cancelAllDeferredEvents(long, int, Object)方法取消所有应用程序启动的是延续事件.

NotificationsManager.cancelAllDeferredEvents(ID_1, NotificationsConstants.MANUAL_TRIGGER, null);

注.如果你调用negotiateDeferredEvent()方法,但没有指定过期事件,你必须调用cancelDeferredEvent()方法取消事件,否则事件永远不过期.

代码实例

例: NotificationDemo.java

/**

* NotificationsDemo.java

package com.rim.samples.docs.notifications;

import net.rim.device.api.notification.*;

import net.rim.device.api.ui.*;

import net.rim.device.api.ui.component.*;

import net.rim.device.api.ui.container.*;

import net.rim.device.api.system.*;

import net.rim.device.api.util.*;

import com.rim.samples.docs.baseapp.*;

public class NotificationsDemo extends BaseApp {

public static final long ID_1 = 0xdc5bf2f81374095L;

private long _eventIdGenerator;

private static Object er;

public static final Object event = new Object() {

public String toString() {

return "Sample Notification Event #1";

}

};

public static void main(String[] args) {

NotificationsManager.registerSource(ID_1, event, NotificationsConstants.CASUAL);

NotificationsManager.registerConsequence(ConsequenceDemo.ID,

new ConsequenceDemo());

NotificationsDemo app = new NotificationsDemo();

app.enterEventDispatcher();

}

public NotificationsDemo() {

MainScreen mainScreen = new MainScreen();

mainScreen.setTitle("Notification Demo App");

mainScreen.addKeyListener(this);

mainScreen.addTrackwheelListener(this);

NotificationsManager.registerNotificationsEngineListener(ID_1,

new NotificationsEngineListenerImpl(this));

pushScreen(mainScreen);

}

private MenuItem triggerItem = new MenuItem(null, 0, 100, 10) {

public void run() {

NotificationsManager.triggerImmediateEvent(ID_1, 0, this, null);

}

public String toString() {

return "Trigger event";

}

};

private MenuItem deferItem = new MenuItem(null, 0, 100, 10) {

public void run() {

long timeout = -1; // Ignored unless trigger is OUT_OF_HOLSTER_TRIGGER.

int trigger = NotificationsConstants.MANUAL_TRIGGER;

Object er = new Object();

NotificationsManager.negotiateDeferredEvent(ID_1, ++_eventIdGenerator,

er, timeout, trigger, null);

}

public String toString() {

return "Start deferred event";

}

};

private MenuItem cancelItem = new MenuItem(null, 0, 100, 10) {

public void run() {

int trigger = NotificationsConstants.MANUAL_TRIGGER;

NotificationsManager.cancelDeferredEvent(ID_1, _eventIdGenerator, er,

trigger, null);

}

public String toString() {

return "Cancel deferred event";

}

};

public void makeMenu( Menu menu, int instance ) {

menu.add(triggerItem);

menu.add(deferItem);

menu.add(cancelItem);

super.makeMenu(menu, instance);

}

public void onExit() {

System.exit(0);

}

private static class NotificationsEngineListenerImpl implements

NotificationsEngineListener {

private UiApplication _app;

}

public NotificationsEngineListenerImpl(UiApplication app) {

_app = app;

}

public void deferredEventWasSuperseded(long sourceID, long eventID,

Object eventReference, Object context) {

final long _eventID = eventID;

er = eventReference;

_app.invokeLater(new Runnable() {

public void run() {

NotificationsManager.cancelDeferredEvent(ID_1, _eventID, er,

NotificationsConstants.MANUAL_TRIGGER, null);

}

});

}

public void notificationsEngineStateChanged(int stateInt, long sourceID,

long eventID, Object eventReference, Object context) {

if(stateInt == NotificationsConstants.OUT_OF_HOLSTER_ENGINE_STATE) {

// Perform some action if handheld is removed from holster.

}

if(stateInt == NotificationsConstants.IN_HOLSTER_ENGINE_STATE) {

// Perform some action if handheld is inserted into holster.

}

public void proceedWithDeferredEvent(long sourceID, long eventID,

Object eventReference, Object context) {

final long _eventID = eventID;

}

_app.invokeLater(new Runnable() {

public void run() {

String s = "This event has occurred: " + _eventID;

Dialog d = new Dialog(Dialog.D_OK, s, Dialog.OK,

Bitmap.getPredefinedBitmap(Bitmap.INFORMATION), 0);

};

private MenuItem cancelItem = new MenuItem(null, 0, 100, 10) {

public void run() {

int trigger = NotificationsConstants.MANUAL_TRIGGER;

NotificationsManager.cancelDeferredEvent(ID_1,

_eventIdGenerator, er,trigger, null);

}

public String toString() {

return "Cancel deferred event";

}

};

public void makeMenu( Menu menu, int instance ) {

menu.add(triggerItem);

menu.add(deferItem);

menu.add(cancelItem);

super.makeMenu(menu, instance);

}

public void onExit() {

System.exit(0);

}

private static class NotificationsEngineListenerImpl

implements NotificationsEngineListener {

private UiApplication _app;

public NotificationsEngineListenerImpl(UiApplication app) {

_app = app;

}

public void deferredEventWasSuperseded(long sourceID,

long eventID,Object eventReference, Object context)

{

final long _eventID = eventID;

er = eventReference;

_app.invokeLater(new Runnable() {

public void run() {

NotificationsManager.cancelDeferredEvent(ID_1,

_eventID, er,

NotificationsConstants.MANUAL_TRIGGER, null);

}

});

}

public void notificationsEngineStateChanged(int stateInt, long sourceID,

long eventID, Object eventReference, Object context) {

if(stateInt == NotificationsConstants.OUT_OF_HOLSTER_ENGINE_STATE) {

// Perform some action if handheld is removed from holster.

}

if(stateInt == NotificationsConstants.IN_HOLSTER_ENGINE_STATE) {

// Perform some action if handheld is inserted into holster.

}

public void proceedWithDeferredEvent(long sourceID, long eventID,

Object eventReference, Object context) {

final long _eventID = eventID;

_app.invokeLater(new Runnable() {

public void run() {

String s = "This event has occurred: " + _eventID;

Dialog d = new Dialog(Dialog.D_OK, s, Dialog.OK,

Bitmap.getPredefinedBitmap(Bitmap.INFORMATION), 0);

d.show();

}

});

}

响应事件

NotificationsEngineListener的实现定义了自定义的通知.调用negotiateDeferredEvent()注册你的实现.如果你触发一个短暂事件,你没有必要为每个BlackBerry设备提供的标准系统通知实现监听者.

为延续事件提供一个自定义的UI通知

NotificationsEngineListener接口的实现为延续事件提供了一个自定义的UI通知.为获取关于创建UI的更多信息,参看BlackBerry应用程序开发者指南 第2卷:高级 第一卷基础.

private static class ListenerImpl implements NotificationsEngineListener

{…}

定义挂起事件的行为

deferredEventWasSuperseded()的实现定义了当一个延续事件挂起时发生的事情.当一个事件由另外一个相同的或者优先级更高的事件挂起时,调用此方法.例如,如果事件挂起时,你可以取消此事件.

public void deferredEventWasSuperseded(long sourceID, long eventID,

Object eventReference, Object context) {

final long _eventID = eventID;

er = eventReference;

_app.invokeLater(new Runnable() {

public void run() {

NotificationsManager.cancelDeferredEvent(ID_1, _eventID, er,

NotificationsConstants.MANUAL_TRIGGER, null);

}

});

}

定义套座(holstering)行为

notificationsEngineStateChanged()的实现定义了套座的行为.当BlackBerry设备插入到套座或从套座移出时,调用此方法.例如,当安排了一个延续事件,并且BlackBerry设备和计算机已经相连或断开时,你可以完成一个指定的操作.

public void notificationsEngineStateChanged(int stateInt, long sourceID, long eventID, Object eventReference, Object context) {

if(stateInt == otificationsConstants.OUT_OF_HOLSTER_ENGINE_STATE) {

// Perform action if BlackBerry device is removed from holster.

}

if(stateInt == NotificationsConstants.IN_HOLSTER_ENGINE_STATE) {

// Perform action if BlackBerry device is inserted into holster.

}

定义通知

proceedWithDeferredEvent()的实现定义了当发生事件时如何通知用户,例如显示一个对话框.当监听者处理一个事件(没有其他更高优先级的事件在队列里)时,调用此方法.

public void proceedWithDeferredEvent(long sourceID, long eventID, Object eventReference,Object context) {

final long _eventID = eventID;

_app.invokeLater(new Runnable() {

public void run() {

String s = "This event has occurred: " + _eventID;

Dialog d = new Dialog(Dialog.D_OK, s, Dialog.OK,

Bitmap.getPredefinedBitmap(Bitmap.INFORMATION), 0);

d.show();

_eventHashtable.put(_eventID, d);

}

});

}

注册通知监听者

调用registerNotificationsEngineListener(int, NotificationsEngineListener)在NotificationsManager注册监听者.提供应用程序的事件源ID以及实现NotificationsEngineListener接口的类的实例作为参数.

NotificationsManager.registerNotificationsEngineListener( ID_1, new ListenerImpl(this));

注:每个应用程序只能注册一个NotificationsEngineListener

自定义系统通知

Consequence接口的实现为短暂事件创建了一个系统通知,例如特殊的铃声,或当发生事件,例如创建一个日志记录接收到的通知数时,进行其他的操作.

注:Consequence接口仅使用在需要系统通知的短暂事件上.延续事件需要你的应用程序实现NotificationsEngineListener接口,并且以一个特定的应用程序回应作为响应.

在主屏幕上提供一个应用程序,使用户可以设置通知选项.

响应一个通知事件

Consequence 和SyncConverter接口的实现对通知事件做出响应. Consequence接口定义了一个对通知事件做出的应用程序响应.SyncConverter接口定义了需要的功能将一个对象转化为序列化格式.这需要使BlackBerry设备可以备份和恢复Profile配置.为获得更多信息,参看90页的”BlackBerry持久存储”.

private static class ConsequenceImpl implements Consequence,SyncConverter {…}

定义一个唯一ID

为结果(consequence)定义一个唯一ID.

public static final long ID = 0xbd2350c0dfda2a51L;

定义常量

为应用程序定义DATA和TYPE常量.当convert()调用时,为了标记从SyncConverter进来的数据类型,使用这些常量.对于适合的应用程序的数据来说,它们是任意的标志符.

private static final int TYPE = ‘n’ << 24 | ‘o’ << 16 | ‘t’ << 8 | ‘d’;

private static final byte[] DATA = new byte[] {‘m’, ‘y’, ‘-’, ‘c’,

‘o’, ‘n’, ‘f’, ‘i’, ‘g’, ‘-’, ‘o’, ‘b’, ‘j’, ‘e’, ‘c’, ‘t’};

private static final Configuration CONFIG = new Configuration(DATA);

创建一个铃声

作为事件通知的一部分,创建一个铃声来播放.

private static final short BFlat = 466; // 466.16

private static final short TEMPO = 125;

private static final short d16 = 1 * TEMPO;

private static final short dpause = 10; // 10 millisecond pause

private static final short[] TUNE = new short[] {BFlat, d16, pause, BFlat};

private static final int VOLUME = 80; // Percentage volume.

定义一个通知

startNotification()的实现为本结果定义了通知.下面的代码实例里,LED将会闪烁,并且会播放一个铃声.

public void startNotification(long consequenceID, long sourceID, long eventID, Object configuration, Object context) {

LED.setConfiguration(500, 250, LED.BRIGHTNESS_50);

LED.setState(LED.STATE_BLINKING);

Alert.startAudio(TUNE, VOLUME);

Alert.startBuzzer(TUNE, VOLUME);

}

停止一个通知

stopNotification()的实现停止本结果的通知.

public void stopNotification(long consequenceID, long sourceID,

long eventID, Object configuration, Object context) {

LED.setState(LED.STATE_OFF);

Alert.stopAudio();

Alert.stopBuzzer();

}

设置用户Profile选项

newConfiguration()的实现创建一个新的配置对象来存储用户资料的设置.此对象传到结果的实现中,以决定用户指定的结果类型是否合适事件.下面的代码实例返回早期定义的CONFIG对象

public Object newConfiguration(long consequenceID, long sourceID,

byte profileIndex, int level, Object context) {

return CONFIG;

}

启动BlackBerry设备数据备份

SyncConverter.convert()的实现可以备份BlackBerry设备数据.当把BlackBerry设备上的数据备份到用户计算机上时,调用此方法.下面的实例从DatBuffer读取进入的数据,并且对未经处理的数据应用一个4个字节的类型和长度.

public SyncObject convert(DataBuffer data, int version, int UID) {

try {

int type = data.readInt();

int length = data.readCompressedInt();

if ( type == TYPE ) {

byte[] rawdata = new byte[length];

data.readFully(rawdata);

return new Configuration(rawdata);

}

catch (EOFException e) {

System.err.println(e);

}

return null;

}

启动BlackBerry设备数据恢复

SyncConverter.convert()的实现恢复BlackBerry设备上的数据.当数据从用户计算机上恢复到BlackBerry设备上时,调用此方法.

public boolean convert(SyncObject object, DataBuffer buffer, int version) {

boolean retval = false;

if ( object instanceof Configuration ) {

Configuration c = (Configuration)object;

buffer.writeInt(TYPE);

buffer.writeCompressedInt(c._data.length);

buffer.write(c._data);

retval = true;

}

return retval;

}

定义通知配置

创建一个类描述通知配置信息.此类实现了SyncObject和Persistable.你必须实现SyncObject.getUID()方法,但是如果数据同步不需要,你的实现可以返回0,正如下面的例子.

private static final class Configuration implements SyncObject, Persistable {

public byte[] _data;

public Configuration(byte[] data) {

_data = data;

}

public int getUID() {

return 0;

}

注册一个结果

如果你创建一个自定义的Consequence,调用registerNotificationsObjects(long, Consequence)方法将之在NotificationsManager上注册.

NotificationsManager.registerConsequence(ConsequenceImpl.ID, new ConsequenceImpl());

当BlackBerry设备启动时,为了注册consequence,在一个类库工程里完成这个注册.为获得更多信息,参看116页的”当BlackBerry启动时注册一个事件源”.

代码实例

例: ConsequenceDemo.java

/**

* ConsequenceDemo.java

package com.rim.samples.docs.notifications;

import net.rim.device.api.synchronization.*;

import net.rim.device.api.notification.*;

import net.rim.device.api.system.*;

import net.rim.device.api.util.*;

import java.io.*;

public class ConsequenceDemo implements Consequence, SyncConverter {

public static final long ID = 0xbd2350c0dfda2a51L;

private static final int TYPE = ‘n’ << 24 | ‘o‘ << 16 | ‘t‘ << 8 | ‘d‘;

private static final byte[] DATA = new byte[] {

‘m’, ‘y’, ‘-’, ‘c’, ‘o‘, ‘n‘, ‘f‘, ‘i’,

‘g’, ‘-‘, ‘o‘, ‘b‘, ‘j‘, ‘e‘, ‘c‘, ‘t‘ };

private static final Configuration CONFIG = new Configuration(DATA);

private static final short BFlat = 466; // The actual value is 466.16.

private static final short TEMPO = 125;

private static final short d16 = 1 * TEMPO;

private static final short pause = 10; // 10 millisecond pause.

private static final short[] TUNE = new short[] {BFlat, d16, pause, BFlat};

private static final int VOLUME = 80; // Percentage volume.

public void startNotification(long consequenceID, long sourceID, long eventID,

Object configuration, Object context) {

LED.setConfiguration(500, 250, LED.BRIGHTNESS_50);

LED.setState(LED.STATE_BLINKING);

Alert.startAudio(TUNE, VOLUME);

Alert.startBuzzer(TUNE, VOLUME);

}

public void stopNotification(long consequenceID, long sourceID, long eventID,

Object configuration, Object context) {

LED.setState(LED.STATE_OFF);

Alert.stopAudio();

Alert.stopBuzzer();

}

public Object newConfiguration(long consequenceID, long sourceID,

byte profileIndex, int level, Object context) {

return CONFIG;

}

public SyncObject convert(DataBuffer data, int version, int UID) {

try {

int type = data.readInt();

int length = data.readCompressedInt();

if ( type == TYPE ) {

byte[] rawdata = new byte[length];

data.readFully(rawdata);

return new Configuration(rawdata);

}

catch (EOFException e) {

System.err.println(e);

}

return null;

}

public boolean convert(SyncObject object, DataBuffer buffer, int version) {

boolean retval = false;

if ( object instanceof Configuration ) {

Configuration c = (Configuration)object;

buffer.writeInt(TYPE);

buffer.writeCompressedInt(c._data.length);

buffer.write(c._data);

retval = true;

}

return retval;

}

/* Inner class to store configuration profile. */

private static final class Configuration implements SyncObject, Persistable {

public byte[] _data;

public Configuration(byte[] data) {

_data = data;

}

public int getUID() {

return 0;

}

Last Updated:2007年2月5日

BlackBerry 应用程序开发者指南第二卷：高级–第10章访问安装和配置信息

Taigoo — Mon, 28 Apr 2008 22:00:56 +0000

第10章访问安装和配置信息

服务定制API

服务定制API(Service Book API)

服务定制API(net.rim.device.api.servicebook)使应用程序可以和BlackBerry基础(infrastructure)进行交互.服务定制由服务记录组成,每个服务定义了一个在BlackBerry设备上有效的服务.

服务记录定义了通讯协议(WAP或IPPP),网关,以及配置信息,例如浏览器设置.

服务定制API功能	描述
管理MDS服务连接	浏览器应用程序API可以使用任何一个带有BrowserConfig 的UID的ServiceBook入口,连接到一个无线网络.例如, Browser类使用服务定制获取一个BrowserSession. Browser.getTransportUid()查询一个服务定制来获取和一个给定服务记录相关联的UID.
管理mail信息	允许应用程序指定一个频道, 它引用合适的服务记录并通过此频道发送一个email.例如,应用程序可以使用BES或一个BlackBerry Internet Service选择发送消息..为获取更多信息,参看12页的”Mail API”.

为了查看BlackBerry设备上的服务定制,单击选项下的Service Book.

ServiceBook类维护一个ServiceRecord对象的集合.每个ServiceRecord对象由一个唯一的ID(UID)和连接ID(CID)标识.

CID	描述
CMIME	CMIME(compressed multi-purpose mail extensions,压缩多意图邮件扩展) CID定义了消息连接
ALP	ALP(address lookup protocol,地址查询协议) CID为无线GAL(Global Address List,全局地址列表)查询定义连接.
IPPP	IPPP(IP Proxy Protocol)使用BlackBerry® MDS Services定义HTTP连接.
BrowserConfig	BrowserConfig(浏览器配置)CID定义BlackBerry和WAP浏览器连接.
Sync	数据同步(Sync) CID为无线数据同步定义连接.
WAP	WAP(wireless application protocol) CID定义了WAP网关连接.
CICAL	CICAL(compressed iCalendar,压缩的iCalendar)为无线日历同步定义连接.

服务记录	描述
Desktop [CMIME]	此服务记录包含了使用桌面发送消息需要的信息.,也包含了完成其他功能需要的消息,例如无线消息调解.
Desktop [ALP]	此服务记录包含了完成无线GAB(Global Address Book)查询所需要的信息.
Desktop [IPPP]	此服务记录包含了通过MDS服务使用并且浏览Internet所要的信息.
Desktop [CICAL]	此服务包含了进行无线日历操作所需要的信息.
Desktop [BrowserConfig]	此服务记录包含了BlackBerry浏览器的配置信息.
Web Client [CMIME]	此服务记录包含了发送消息需要的信息.,也包含了使用BlackBerry Internet Service.进行其他功能(例如无线消息调解)所需要的消息.
WAP Secure Transport [WAP]	此服务记录包含了连接到服务商WAP网关所需要的信息.
WAP Browser [BrowserConfig]	此服务记录包含了WAP浏览器的配置信息.
Desktop [Sync]	此服务记录包含了完成数据同步所需要的信息.

监听服务定制事件

GlobalEventListener接口(在net.rim.device.api.system 包里)的实现使应用程序可以监听服务定制事件. 当接收到一个全局事件时,GlobalEventListener.eventOccurred()的实现指定了进行的操作.

为了注册一个全局事件监听者,调用Application.addGlobalEventListener(GlobalEventListener).

ServiceBook类定义了下面的事件,它们由一个GUID标识.

GUID	描述
GUID_SB_ADDED	当增加一个服务定制时发送的全局事件的GUID.
GUID_SB_BR_END	当服务定制备份或恢复结束时发送的全局事件的GUID.
GUID_SB_BR_START	当服务定制备份或恢复开始时发送的全局事件的GUID.
GUID_SB_CHANGED	当一个服务定制改变时发送的全局事件的GUID.
GUID_SB_OTA_SWITCH	当所有服务记录因为一个移动的BES命令OTA而被插入时发送的全局事件的GUID.
GUID_SB_OTA_UPDATE	当OTA为一个UID更新所有服务记录时发送的全局事件的GUID.
GUID_SB_REMOVED	当删除一个服务定制时发送的全局事件的GUID.

Last Updated:2007年2月5日

BlackBerry 应用程序开发者指南第二卷：高级–第9章备份和恢复持久数据

Taigoo — Mon, 28 Apr 2008 21:58:06 +0000

第9章备份和恢复持久数据

同步API

增加备份持久数据的支持

同步API

在net.rim.device.api.synchronization包里的同步API可以使应用程序和BlackBerry桌面软件集成以完成2个任务:

将一个数据库备份到桌面文件,以后可以恢复它.
和桌面应用程序同步数据.

注::BlackBerry桌面软件需要备份的数据使用下面的格式:

Length<2> Type<1> Data

为了验证数据是否有合适的格式,使用net.rim.device.api.synchronization.ConverterUtilities类里的任何一个写方法;

数据备份

桌面软件提供一个Backup and Restore工具,它允许用户将BlackBerry设备上的数据保存到桌面上的一个文件,并且使用此桌面文件将数据恢复到BlackBerry设备上.

当一个应用程序实现了同步API,桌面软件将应用程序数据库备份和恢复到其他的BlackBerry设备数据库.你也可以使用同步API创建数据备份(archives),或者当BlackBerry设备第一次连接到计算机时跳出应用程序数据库.

数据同步

桌面软件提供一个Intellisync的工具,此工具将BlackBerry设备和用户计算机上的应用程序同步.

当备份和恢复加载BlackBerry设备和一个桌面备份文件之间的数据时,同步比较桌面应用程序存在的数据和BlackBerry设备上的数据,然后合并这些数据..

为了和桌面应用程序进行数据同步,使用BlackBerry桌面API为桌面软件编写一个插件.BlackBerry JDE也包含了一个同步实例应用程序作为桌面的一个插件.
注:你存储数据进行备份的格式是没有限制的.唯一的要求就是应用程序应该使用桌面插件应用程序使用的格式进行读写数据.

同步API

实现下面同步API提供的接口:

接口	描述
SyncConverter	转化BlackBerry设备需要的SyncObject格式和桌面需要的序列化格式之间的数据.
SyncCollection	代表了一个应用程序同步对象的集合.
SyncObject	代表了一个可以备份和恢复到用户计算机的对象.

SerialSyncManager类可以访问同步管理器,特别的,它可以为同步注册新的对象
注:为了备份和恢复非常少的数据,例如应用程序设置选项,你可以扩展SyncItem类,并实现它的抽象方法. SyncItem类为你已经实现了SyncCollection, SyncConverter, 和 SyncObject接口.

增加备份持久数据的支持

为了支持备份,修改一个实现了Persistable接口的类,实现SyncObject接口.

修改应用程序的主类以实现SyncCollection和SyncConverter接口.
注: SyncCollection和SyncConverter接口可以由相同的类或者由单独的类实现,这决定于你的应用程序.下面的章节将解释如何再相同的类里实现这些接口.

定义一个唯一ID

定义一个_uid变量. getUID()的实现为同步操作返回一个唯一ID.

定义一个构造子

你的构造子的实现接受一个唯一ID作为参数,并且将之设置为_uid变量的值.
注:每一个存储在BlackBerry设备上的同步对象,必须有一个关联的ID,此ID对于它的应用程序来说必须是唯一的. UIDGenerator缺省的设置此ID值.

注册一个同步集合

在main()方法里,在同步管理器上注册你的SyncCollection., 当BlackBerry设备第一次启动时,创建一个独立的工程传入初始化参数.为获的更多的信息,参看108页的”当BlackBery设备启动时注册一个同步集合”.

public static void main(String[] args) {

boolean startup = false;

for (int i=0; i

if (args[i].startsWith("init")) {

startup = true;

}

if (startup) {

//enable application for synchronization on startup

SerialSyncManager.getInstance().enableSynchronization(new RestaurantsSync());

}

else {

RestaurantsSync app = new RestaurantsSync();

app.enterEventDispatcher();

}

当BlackBery设备启动时注册一个同步集合

当BlackBery设备启动时,为了注册一个同步集合, 为你的主要应用程序创建一个独立的工程来完成一个可选的入口.在BlackBerry第一次启动时,此工程传递一个参数到你的应用程序中,这样你的应用程序仅注册一次.

创建一个初始化工程

1.在BlackBerry IDE里,创建一个工程.

2.右击工程,点击Properties

3.单击Application标签.

4.在Project type 下拉列里, 点击Alternate CLDC Application Entry Point.

5.在Alternate entry point for的下拉列里, 单击实现同步的工程. 在Arguments passed to 域, 输入 init.

7.选择Auto-run on startup选项.

8.选择System module 选项.

9.单击OK.
注:在启动时,可以将参数传入BlackBerry CLDC的应用程序里.尽管这样,此功能在MIDlet应用程序里不会存在.

代码实例

此代码实例描述如何使桌面软件为你的应用程序备份和恢复持久数据.此实例修改了Restaurants.java的代码,用来实现同步API.

例: RestaurantsSync.java

/**

* RestaurantsSync.java

package com.rim.samples.docs.restaurantssync;

import java.io.*;

import net.rim.device.api.ui.*;

import net.rim.device.api.ui.component.*;

import net.rim.device.api.ui.container.*;

import net.rim.device.api.system.*;

import net.rim.device.api.util.*;

import java.util.*;

import net.rim.device.api.i18n.*;

import net.rim.device.api.synchronization.*;

import com.rim.samples.docs.resource.*;

import com.rim.samples.docs.baseapp.*;

public class RestaurantsSync extends BaseApp

implements RestaurantsSyncResource,SyncCollection, SyncConverter,

KeyListener, TrackwheelListener {

private static final long KEY = 0xdec6a67096f833cL;

private AutoTextEditField namefield;

private AutoTextEditField addressfield;

private EditField phonefield;

private EditField specialtyfield;

private static PersistentObject store;

private static Vector _data;

private static ResourceBundle _resources;

private static final int FIELDTAG_NAME = 1;

private static final int FIELDTAG_PHONE = 2;

private static final int FIELDTAG_ADDRESS = 3;

private static final int FIELDTAG_SPECIALTY = 4;

private static RestaurantsSync _instance;

private MenuItem saveItem = new MenuItem(_resources, MenuItem.SAVE_CLOSE, 110, 10) {

public void run() {

RestaurantInfo info = new RestaurantInfo();

info.setElement(RestaurantInfo.NAME, namefield.getText());

info.setElement(RestaurantInfo.ADDRESS, addressfield.getText());

info.setElement(RestaurantInfo.PHONE, phonefield.getText());

info.setElement(RestaurantInfo.SPECIALTY, specialtyfield.getText());

_data.addElement(info);

synchronized(store) {

store.setContents(_data);

store.commit();

}

Dialog.inform(_resources.getString(APP_SUCCESS));

namefield.setText(null);

adressfield.setText(null);

phonefield.setText("");

specialtyfield.setText("");

}

};

private MenuItem getItem = new MenuItem("Get", 110, 11) {

public void run() {

synchronized(store) {

_data = (Vector)store.getContents();

if (!_data.isEmpty()) {

RestaurantInfo info = (RestaurantInfo)_data.lastElement();

namefield.setText(info.getElement(RestaurantInfo.NAME));

addressfield.setText(info.getElement(RestaurantInfo.ADDRESS));

phonefield.setText(info.getElement(RestaurantInfo.PHONE));

specialtyfield.setText(info.getElement(

RestaurantInfo.SPECIALTY));

}

};

static {

_resources = ResourceBundle.getBundle(RestaurantsSyncResource.BUNDLE_ID,

RestaurantsSyncResource.BUNDLE_NAME);

store = PersistentStore.getPersistentObject(KEY);

synchronized (store) {

_data = (Vector)store.getContents();

if ( _data == null )

{

data = new Vector();

store.setContents( _data );

store.commit();

}

public static void main(String[] args) {

boolean startup = false;

for (int i=0; ilength; ++i) {

if (args[i].startsWith("init"))

{

startup = true;

}

if (startup) {

// Enable application for synchronization on startup.

SyncManager.getInstance().enableSynchronization(

RestaurantsSync.getInstance());

}

else {

RestaurantsSync app = new RestaurantsSync();

app.enterEventDispatcher();

}

public static RestaurantsSync getInstance() {

if (_instance == null) {

_instance = new RestaurantsSync();

}

return _instance;

}

private static final class RestaurantInfo implements Persistable, SyncObject {

private String[] _elements; // Data.

public static final int NAME = 0;

public static final int ADDRESS = 1;

public static final int PHONE = 2;

public static final int SPECIALTY = 3;

private int _uid;

public int getUID() {

return _uid;

}

public RestaurantInfo() {

_elements = new String[4];

for ( int i = 0; i < _elements.length; ++i) {

_elements[i] = "";

}

public RestaurantInfo(int uid) {

_elements = new String[4];

for (int i = 0; i < _elements.length; ++i) {

_elements[i] = "";

}

_uid = uid;

}

public String getElement(int id) {

return _elements[id];

}

public void setElement(int id, String value) {

_elements[id] = value;

}

// SyncConverter methods.

public SyncObject convert(DataBuffer data, int version, int UID) {

try {

RestaurantInfo info = new RestaurantInfo(UID);

while(data.available() > 0) {

int length = data.readShort();

byte[] bytes = new byte[length];

switch (data.readByte()) {

case FIELDTAG_NAME:

data.readFully(bytes);

//trim null-terminator

info.setElement(RestaurantInfo.NAME,

new String(bytes).trim());

break;

case FIELDTAG_PHONE:

data.readFully(bytes);

info.setElement(RestaurantInfo.PHONE,

new String(bytes).trim());

break;

case FIELDTAG_ADDRESS:

data.readFully(bytes);

info.setElement(RestaurantInfo.ADDRESS,

new String(bytes).trim());

break;

case FIELDTAG_SPECIALTY:

data.readFully(bytes);

info.setElement(RestaurantInfo.SPECIALTY,

new String(bytes).trim());

break;

default:

data.readFully(bytes);

break;

}

return info;

}

catch (EOFException e) {

System.err.println(e.toString());

}

return null;

}

public boolean convert(SyncObject object, DataBuffer buffer, int version) {

if (version == getSyncVersion()) {

if (object instanceof RestaurantInfo )

{

String name = ((RestaurantInfo)object).getElement(

RestaurantInfo.NAME);

String phone = ((RestaurantInfo)object).getElement(

RestaurantInfo.PHONE);

String address = ((RestaurantInfo)object).getElement(

RestaurantInfo.ADDRESS);

String specialty = ((RestaurantInfo)object).getElement(

RestaurantInfo.SPECIALTY);

buffer.writeShort(name.length()+1);

buffer.writeByte(FIELDTAG_NAME);

buffer.write(name.getBytes());

buffer.writeByte(0);

buffer.writeShort(phone.length()+1);

buffer.writeByte(FIELDTAG_PHONE);

buffer.write(phone.getBytes());

buffer.writeByte(0);

buffer.writeShort(address.length()+1);

buffer.writeByte(FIELDTAG_ADDRESS);

buffer.write(address.getBytes());

buffer.writeByte(0);

buffer.writeShort(specialty.length()+1);

buffer.writeByte(FIELDTAG_SPECIALTY);

buffer.write(specialty.getBytes());

buffer.writeByte(0);

return true;

}

return false;

}

public void beginTransaction() {

store = PersistentStore.getPersistentObject(KEY);

_data = (Vector)store.getContents();

}

public void endTransaction() {

store.setContents(_data);

store.commit();

}

public SyncConverter getSyncConverter() {

return this;

}

public String getSyncName() {

return "Restaurant Synchronization Demo";

}

public String getSyncName(Locale locale) {

return getSyncName();

}

public int getSyncObjectCount() {

store = PersistentStore.getPersistentObject(KEY);

_data = (Vector)store.getContents();

return _data.size();

}

public SyncObject[] getSyncObjects() {

SyncObject[] array = new SyncObject[_data.size()];

for (int i = _data.size() - 1; i >= 0; –i) {

array[i] = (SyncObject)_data.elementAt(i);

}

return array;

}

public SyncObject getSyncObject(int uid) {

for (int i = _data.size() -1; i>= 0; –i) {

SyncObject so = (SyncObject)_data.elementAt(i);

if (so.getUID() == uid ) return so;

}

return null;

}

public int getSyncVersion() {

return 1;

}

public boolean addSyncObject(SyncObject object) {

_data.addElement(object);

return true;

}

public boolean removeAllSyncObjects() {

_data.removeAllElements();

return true;

}

public void clearSyncObjectDirty(SyncObject object) {

// Not applicable.

}

public boolean isSyncObjectDirty(SyncObject object) {

return false;

}

public boolean removeSyncObject(SyncObject object) {

return false;

}

public void setSyncObjectDirty(SyncObject object) {

}

public boolean updateSyncObject(SyncObject oldObject, SyncObject newObject) {

return false;

}

public RestaurantsSync() {

MainScreen mainScreen = new MainScreen();

mainScreen.setTitle(new LabelField( _resources.getString(APPLICATION_TITLE)));

namefield = new AutoTextEditField(_resources.getString(FIELD_NAME), "");

addressfield = new AutoTextEditField( _resources.getString(FIELD_ADDRESS),"");

phonefield = new EditField( _resources.getString(FIELD_PHONE), "",

Integer.MAX_VALUE, BasicEditField.FILTER_PHONE);

specialtyfield = new EditField(_resources.getString(FIELD_SPECIALTY), "",

Integer.MAX_VALUE, BasicEditField.FILTER_DEFAULT);

mainScreen.add(namefield);

mainScreen.add(addressfield);

mainScreen.add(phonefield);

mainScreen.add(specialtyfield);

mainScreen.addKeyListener(this);

mainScreen.addTrackwheelListener(this);

pushScreen(mainScreen);

}

public void makeMenu( Menu menu, int instance) {

menu.add(saveItem);

menu.add(getItem);

super.makeMenu(menu, instance);

}

public void onExit() {

Dialog.alert(_resources.getString(APP_EXIT));

}

Last Updated:2007年2月2日

BlackBerry 应用程序开发者指南第二卷：高级–第8章存储持久数据

Taigoo — Mon, 28 Apr 2008 21:54:00 +0000

第8章存储持久数据

持久数据选项

管理持久数据

内存管理以及持久对象

管理客户对象

持久数据选项

在BlackBerry设备上，以下面的方式可以存储数据:

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

如果你想让你的应用程序可以在多个与Java ME兼容的设备上运行,那么采用MIDP的实现.如果你编写应用程序仅仅为BlackBerry设备,使用BlackBerry持久存储模型,因为它提供了一个更为灵活有效的方式存储数据,

MIDP存储记录

javax.microedition.rms包提供了MIDP记录存储的实现.持久数据存储在RecordStore对象里.一个记录存储最大可以为64KB.

数据的离散单元称为记录.一个记录是一个字节数组,赋给它一个唯一标志数.

创建一个记录存储

调用openRecordStore().指定true来描述当记录存储不存在时应该创建此记录存储.

RecordStore store = RecordStore.openRecordStore("Contacts", true);

注:当从BlackBerry设备删除一个应用程序时,所有此应用程序创建的记录存储都会删除.每个在MIDlet包(suite)的记录存储都有一个唯一名.MIDlet仅可以访问一个在相同包里的由MIDlet创建的记录存储.

增加一个记录

调用addRecord().

int id = store.addRecord(_data.getBytes(), 0, data.length());

获取一个记录

调用getRecord(int, byte[], int).给本方法提供一个记录ID,字节数组,以及一个偏移作为参数.

byte[] data = new byte[store.getRecordSize(id)];

store.getRecord(id, data, 0);

String dataString = new String(data);

获取所有记录

打开存储,然后获取其迭代.

RecordStore store = RecordStore.openRecordStore("Contacts", false);

RecordEnumeration e = store.enumerateRecords(null, null, false);

enumerateRecords(RecordFilter filter, RecordComparator comparator, Boolean keepUpdated) 方法有如下参数:

参数	描述
filter	此参数指定一个RecordFilter对象获取记录存储结果的子集(如果为null,将返回所有记录存储).
comparator	此参数指定一个RecordComparator对象决定返回记录所在的顺序位置(如果为null.将返回无序的记录).
keepUpdated	此参数决定对于记录存储,迭代保持当前的改变.

BlackBerry持久存储

在MIDP中的记录存储(RecordStore)与BlackBerry持久模型(PersistentStore)有2处主要的区别.

特性	描述
数据存储	MIDP记录仅以字节数组存储数据.相比之下,BlackBerry API允许你在持久存储中保存任何对象.这样,查询存储数据就会比记录模型更快一些.为了存储一个自定义的对象类型,自定义类型的类必须要实现Persistable接口.
数据共享	在MIDP中,每个RecordStore属于单个MIDlet包,并且MIDlet也只能访问由相同包的MIDlet创建的记录存储.尽管如此,在BlackBerry持久模型中,数据可以在应用程序之间共享,在创建数据的离散应用程序中共享.代码签名指定只有被认证的应用程序才可以访问这些数据.

注:BlackBerry持久性API在手持设备软件3.6或后期版本可用.对于早期的版本,你必须使用MIDP记录存储.

保留存储空间

BlackBerry的存储空间是有限的.你应该小心设计你的程序,将需要存储持久数据的闪存数量最小化.

在一般的BlackBerry里,对于一个标准的BlackBerry应用程序,不需要的存储空间必须在所有应用程序之间共享,用来存储用户数据,包含日历约会,联系人,以及消息.

如果BlackBerry设备在一个小内存情况下操作,它有可能完成下面的动作释放内存空间:

从BlackBerry上删除以前的消息.
从BlackBerry 设备上删除超过一个星期的日历约会(如果启动了无线日历同步).

如果因低内存而BlackBerry设备删除了消息或者日历约会,那么在桌面消息程不会删除数据.为获的更多信息,参看96页的”内存管理以及持久对象”.

注:用户点击设备选项的Status可以查看当前可用的数据空间.

备份与恢复

在net.rim.device.api.synchronization包中,同步(synchronization)API允许你备份以及恢复BlackBerry设备上的持久数据.为获取更多信息,参看104页的”增加支持备份持久数据”.

安全

缺省的,BlackBerry上由RIM数字签名的应用程序可以访问持久存储上的数据,联系RIM获取关于控制数据访问的信息.

管理工具

在BES 3.5 Microsoft® Exchange SP2或 BES 2.2 M® Lotus® Domino®里,系统管理员可以使用IT策略控制第三方应用程序访问持久存储.

管理员可以设置应用程序控制项ALLOW_USE_PERSISTENT_STORE为TRUE或FALSE.缺省的,第三方应用程序可以使用持久存储(ALLOW_USE_PERSISTENT_STORE为TRUE)

注:这个策略对MIDP记录存储没有影响.

数据完整性

为了维护持久存储数据的完整性,如果在提交时发生一个错误,不会更新局部.

注:因低内存VM完成一个紧要的垃圾回收时,数据完整性会折中.在这样的情况下,当BlackBerry设备提交时,部分完成的事务会提交.在正常垃圾回收下未提交的事务不会提交.

管理持久数据

持久数据类型

如果一个自定义数据类型类实现了Persistable类接口,那么此数据类型可以持久保存.小面原生数据类型也可以持久存储.

java.lang.Boolean
java.lang.Byte
java.lang.Character
java.lang.Integer
java.lang.Long
java.lang.Object
java.lang.Short
java.lang.String
java.util.Vector
java.util.Hashtable

注:当你持久化一个对象时,此对象引用的任何对象也可以持久化.

创建一个持久化数据库

每个应用程序一般可以创建单个PersistentObject.此对象是应用程序的持久化数据以及索引的根数据库.应用程序将保存数据到此PersistentObject中.

注:使用一个静态的构造子,这样PersistentObject只创建一次,即此类的一个对象第一次创建时.每次一个进程开始时,它包含的静态块再一次运行.

一个唯一的long键标志了每个PersistentObject.此键一般为一个全权包名的哈希

注:当一个应用程序从BlackBerry删除时,所有此应用程序创建的持久化对象也将删除.

创建一个唯一的long键

1. 在BlackBerry IDE里,输入一个字符串,例如com.rim.samples.docs.userinfo.

2. 选择此字符串.

3. 右击,然后单击Convert ‘com.rim.samples.docs.userinfo’ to long. long值将会出现.
注:在你的代码加入注释表明用来生成long键的字符串..

static PersistentObject store;

static {

store = PersistentStore.getPersistentObject( 0xa1a569278238dad2L );

}

持久存储数据

为了将数据保存到持久存储里,调用PersistentObject上的setContents().此方法用新的值替代已存在的值.调用commit()保存到持久存储里,
注:如果在提交的过程中发生一个错误,已经完成的更新不会提交.在PersistentObject里的数据从最后一次提交中获取值,以保持数据的完整性.

String[] userinfo = {username, password};

synchronized(store) {

store.setContents(userinfo);

store.commit();

}

如果你有许多对象需要提交到存储里,你可以以一个批事务的形式提交它们.为了实现此,调用PersistentStore.getSynchObject()方法获取持久存储监视器紧锁对象.然后同步对象,如果必要,调用commit()方法.当你释放监视对象的同步时,你的所有事务一次性被提交.如果批处理有任何提交失败,整个批提交也失败.当你同步监视器对象时,如果你调用forceCommit(),这个对象立即提交,并且它不再时批事务中的一部分了.

获取持久数据

调用 PersistentObject 上的getContents() 方法.

将 PersistentObject.getContents()返回的对象显式的转化为你需要的类型.

synchronized(store) {

String[] currentinfo = (String[])store.getContents();

if(currentinfo == null) {

Dialog.alert(_resources.getString(APP_ERROR));

}

else {

currentusernamefield.setText(currentinfo[0]);

currentpasswordfield.setText(currentinfo[1]);

}

注:当一个应用程序第一次访问数据据,它应该验证任何索引的顺序,如果出现一个问题,重新创建索引.应用程序应该能够识别并更正任何毁坏的或者丢失的数据的问题.为获得更对信息,参看91页的”数据完整性”.

删除一个数据库

为了删除一个数据库,调用PersistentStore.destroyPersistentObject().提供一个PersistentObject的唯一键作为参数,
注: PersistentObject作为应用程序的根数据库使用.你删除它,你将删除所有此应用程序存储的持久化数据如果定义了一个PersistentStore.cod文件删除了,所有由此.cod文件创建的持久化对象也将删除.

为了删除单独的数据,把它们简单的当成普通数据看待,并删除这些数据的引用.垃圾数据会自动回收。

代码实例

本代码实例描述了如何为用户创建一个应用程序来查看它们当前的用户名和密码,输入一个新的用户名和密码,然后保存变化.

例: UserInfo.java

/**

* UserInfo.java

package com.rim.samples.docs.userinfo;

import net.rim.device.api.ui.*;

import net.rim.device.api.ui.component.*;

import net.rim.device.api.ui.container.*;

import net.rim.device.api.system.*;

import net.rim.device.api.util.*;

import java.util.*;

import net.rim.device.api.i18n.*;

import com.rim.samples.docs.baseapp.*;

import com.rim.samples.docs.resource.*;

public class UserInfo extends BaseApp

implements UserInfoResource,KeyListener, TrackwheelListener {

private static PersistentObject store;

private static ResourceBundle _resources;

private AutoTextEditField usernamefield;

private PasswordEditField passwordfield;

private AutoTextEditField currentusernamefield;

private AutoTextEditField currentpasswordfield;

static {

_resources = ResourceBundle.getBundle(

UserInfoResource.BUNDLE_ID, UserInfoResource.BUNDLE_NAME);

store = PersistentStore.getPersistentObject(0xa1a569278238dad2L);

}

private MenuItem saveItem = new MenuItem( _resources.getString(MENUITEM_SAVE), 110, 10) {

public void run() {

String username = usernamefield.getText();

String password = passwordfield.getText();

String[] userinfo = {username, password};

synchronized(store) {

store.setContents(userinfo);

store.commit();

}

Dialog.inform(_resources.getString(APP_SUCCESS));

usernamefield.setText(null);

passwordfield.setText(null);

}

};

private MenuItem getItem = new MenuItem( _resources.getString(MENUITEM_GET), 110, 11 ) {

public void run() {

synchronized(store) {

String[] currentinfo = (String[])store.getContents();

if(currentinfo == null) {

Dialog.alert(_resources.getString(APP_ERROR));

}

else {

currentusernamefield.setText(currentinfo[0]);

currentpasswordfield.setText(currentinfo[1]);

}

};

public static void main(String[] args) {

UserInfo app = new UserInfo();

app.enterEventDispatcher();

}

public UserInfo() {

MainScreen mainScreen = new MainScreen();

mainScreen.setTitle(new LabelField(

_resources.getString(APPLICATION_TITLE)));

usernamefield = new AutoTextEditField(

_resources.getString(FIELD_NAME), "");

passwordfield = new PasswordEditField(

_resources.getString(FIELD_PASSWORD),"");

currentusernamefield = new AutoTextEditField(

_resources.getString(FIELD_CURRENTNAME), "");

currentpasswordfield = new AutoTextEditField(

_resources.getString(FIELD_CURRENTPASSWORD),"");

SeparatorField separator = new SeparatorField();

mainScreen.add(usernamefield);

mainScreen.add(passwordfield);

mainScreen.add(separator);

mainScreen.add(currentusernamefield);

mainScreen.add(currentpasswordfield);

mainScreen.addKeyListener(this);

mainScreen.addTrackwheelListener(this);

pushScreen(mainScreen);

}

public void makeMenu( Menu menu, int instance ) {

menu.add(saveItem);

menu.add(getItem);

super.makeMenu(menu, 0);

}

public void onExit() {

Dialog.alert(_resources.getString(APP_EXIT));

}

内存管理和持久化对象

在BlackBerry设备上有固定数量的持久化对象句柄以及对象句柄.

闪存	持久化对象句柄	对象句柄
8 MB	12,000	24,000
16 MB	27,000	56,000
32 MB	65,000	132,000

BlackBerry设备上的每个持久化对象都会要求一个持久化对象句柄以及一个对象句柄.例如,一个记录包含了10个String字段,那么它将要求11个对象句柄-一个为记录,一个为每个String.如果记录是持久化的,它将需要额外的11个持久化对象句柄.

使用下面的技术限制应用程序需要的持久化对象句柄数:

如果可能,使用原始类型代替对象.一个原始类型,例如一个int或者一个char,它们不需要一个对象句柄.
使用对象分组API (net.rim.device.api.system.ObjectGroup)将对象分组.一个分组的对象仅需要一个对象句柄.

注:分组的对象是可读的.在做出改变之前调用ObjectGroup.expandGroup()撤销对象的分组.在完成改变之后,调用ObjectGroup.createGroup()将对象分组.必要时仅撤销对象的分组,当撤销对象分组时有性能将受到损耗,因为系统创建了分组对象的一个拷贝,并且将句柄分配给每个组里的对象.

为获取更多信息,参看”BlackBerry JDE最佳内存实践”白皮书.

管理自定义对象

创建一个数据库

创建一个Vector对象存储多个对象.创建一个PersistentObject作为应用程序的根数据库.

private static Vector _data;

PersistentObject store;

static {

store = PersistentStore.getPersistentObject( 0xdec6a67096f833cL );

//key is hash of test.samples.restaurants

_data = (Vector)store.getContents();

synchronized (store) {

if (_data == null) {

_data = new Vector();

store.setContents(_data);

store.commit();

}

持久存储数据

可以持久化实现了Persistable接口的对象.

下面的代码实例作为inner类实现Persistable接口.它定义了一个带有4个Object的数组来存储餐厅名,地址,电话号码,以及特色.并且定义了方法来获取和设置Object元素值.

注:一个类为了其对象,必须显式的实现Persistable接口来也就存储. 甚至其子类也适用这个需求.例如类A实现了Persistable接口,并且A有一个子类B,B的对象不能持久存储,除非B也实现Persistable接口.

private static final class RestaurantInfo implements Persistable {

private String[] _elements;

public static final int NAME = 0;

public static final int ADDRESS = 1;

public static final int PHONE = 2;

public static final int SPECIALTY = 3;

public RestaurantInfo() {

_elements = new String[4];

for ( int i = 0; i < _elements.length; ++i) {

_elements[i] = new String("");

}

public String getElement(int id) {

return _elements[id];

}

public void setElement(int id, String value) {

_elements[id] = value;

}

创建扩展的对象

下面的方法允许你加入字段到对象中:

在一个int中,存储Boolean值做为bit.保留多余的位供将来使用.
直接存储String,但是使用一个键/值对的Vector或Hashtable,这样附加的(或很少使用的)的字段也可以增加.
如果你由一个表的索引,将他们存储在一个Vector或数组里,这样你可以增加未来的索引了.

保存一个对象

定义一个对象

下面的代码实例创建一个RestaurantInfo对象,并且使用它的设置方法来定义他的组件.

RestaurantInfo info = new RestaurantInfo();

info.setElement(RestaurantInfo.NAME, namefield.getText());

info.setElement(RestaurantInfo.ADDRESS,addressfield.getText());

info.setElement(RestaurantInfo.PHONE, phonefield.getText());

info.setElement(RestaurantInfo.SPECIALTY, specialtyfield.getText());

将一个对象加到一个Vector

调用addElement().

_data.addElement(info);

保存一个更新的对象

调用PersistentObject的setContents(),然后调用commit()方法保存一个更新的对象

synchronized(store) {

store.setContents(_data);

store.commit();

}

注: 当你做出改变时,同步一个持久对象,这样其他的线程在同一时间就不能做出改变.

获取一个对象

为了获取最近保存的对象,调用_data.lastElement().

public void run() {

synchronized(store) {

_data = (Vector)store.getContents();

if (!_data.isEmpty()) { RestaurantInfo info = (RestaurantInfo)_data.lastElement();

namefield.setText(info.getElement(RestaurantInfo.NAME));

addressfield.setText(info.getElement(RestaurantInfo.ADDRESS));

phonefield.setText(info.getElement(RestaurantInfo.PHONE));

specialtyfield.setText(info.getElement(

RestaurantInfo.SPECIALTY));

}

代码实例

本实例描述了如何创建一个应用程序,它允许用户存储一个关于喜爱的餐厅信息.

本实例也允许用户保存多个餐厅的信息,并且可以查看最新保存的餐厅信息.

例: Restaurants.java

/* Restaurants.java

package com.rim.samples.docs.restaurants;

import net.rim.device.api.ui.*;

import net.rim.device.api.ui.component.*;

import net.rim.device.api.ui.container.*;

import net.rim.device.api.system.*;

import net.rim.device.api.util.*;

import java.util.*;

import net.rim.device.api.i18n.*;

import net.rim.blackberry.api.invoke.*;

import net.rim.blackberry.api.browser.*;

import com.rim.samples.docs.baseapp.*;

import com.rim.samples.docs.resource.*;

public class Restaurants extends BaseApp

implements RestaurantResource,KeyListener, TrackwheelListener {

private AutoTextEditField namefield;

private AutoTextEditField addressfield;

private EditField phonefield;

private EditField websitefield;

private EditField specialtyfield;

private static Vector _data;

private static PersistentObject store;

private static ResourceBundle _resources;

private MenuItem saveItem = new MenuItem(_resources.getString(MENUITEM_SAVE), 110, 10) {

public void run() {

RestaurantInfo info = new RestaurantInfo();

info.setElement(RestaurantInfo.NAME, namefield.getText());

info.setElement(RestaurantInfo.ADDRESS, addressfield.getText());

info.setElement(RestaurantInfo.PHONE, phonefield.getText());

info.setElement(RestaurantInfo.WEBSITE, phonefield.getText());

info.setElement(RestaurantInfo.SPECIALTY,

specialtyfield.getText());

_data.addElement(info);

synchronized(store) {

store.setContents(_data);

store.commit();

}

Dialog.inform(_resources.getString(APP_SUCCESS));

namefield.setText(null);

addressfield.setText(null);

phonefield.setText("");

websitefield.setText("");

specialtyfield.setText("");

}

};

private MenuItem getItem = new MenuItem(_resources.getString(MENUITEM_GET), 110, 11) {

public void run() {

synchronized(store) {

_data = (Vector)store.getContents();

if (!_data.isEmpty()) {

RestaurantInfo info = (RestaurantInfo)_data.lastElement();

namefield.setText(info.getElement(RestaurantInfo.NAME));

addressfield.setText(info.getElement(RestaurantInfo.ADDRESS));

phonefield.setText(info.getElement(RestaurantInfo.PHONE));

websitefield.setText(info.getElement(RestaurantInfo.WEBSITE));

specialtyfield.setText(info.getElement(RestaurantInfo.SPECIALTY));

}

};

private MenuItem phoneItem = new MenuItem(_resources.getString(MENUITEM_PHONE), 110, 12) {

public void run() {

synchronized(store) {

String phoneNumber = phonefield.getText();

if ( phoneNumber.length() == 0) {

Dialog.alert(_resources.getString(ALERT_NO_PHONENUMBER));

}

else {

PhoneArguments call =

new PhoneArguments(PhoneArguments.ARG_CALL, phoneNumber);

Invoke.invokeApplication(Invoke.APP_TYPE_PHONE, call);

}

};

private MenuItem browserItem =

new MenuItem(_resources.getString(MENUITEM_BROWSER), 110, 12) {

public void run() {

synchronized(store) {

String websiteUrl = websitefield.getText();

if (websiteUrl.length() == 0) {

Dialog.alert(_resources.getString(ALERT_NO_WEBSITE));

}

else {

BrowserSession visit = Browser.getDefaultSession();

visit.displayPage(websiteUrl);

}

};

static {

_resources = ResourceBundle.getBundle(

RestaurantResource.BUNDLE_ID,

RestaurantResource.BUNDLE_NAME);

store = PersistentStore.getPersistentObject(0xdec6a67096f833cL);

// Key is hash of test.samples.restaurants.

synchronized (store) {

_data = (Vector)store.getContents();

if (_data == null) {

_data = new Vector();

store.setContents( _data );

store.commit();

}

public static void main(String[] args) {

Restaurants app = new Restaurants();

app.enterEventDispatcher();

}

private static final class RestaurantInfo implements Persistable {

// Data.

private String[] _elements;

// Fields.

public static final int NAME = 0;

public static final int ADDRESS = 1;

public static final int PHONE = 2;

public static final int WEBSITE = 3;

public static final int SPECIALTY = 4;

public RestaurantInfo() {

_elements = new String[4];

for ( int i = 0; i < _elements.length; ++i) {

_elements[i] = new String("");

}

public String getElement(int id) {

return _elements[id];

}

public void setElement(int id, String value) {

_elements[id] = value;

}

public Restaurants() {

MainScreen mainScreen = new MainScreen();

mainScreen.setTitle(new LabelField(

_resources.getString(APPLICATION_TITLE)));

namefield = new AutoTextEditField(

_resources.getString(FIELD_NAME), "");

addressfield = new AutoTextEditField(

_resources.getString(FIELD_ADDRESS), "");

phonefield = new EditField(

_resources.getString(FIELD_PHONE), "", Integer.MAX_VALUE,

BasicEditField.FILTER_PHONE);

websitefield = new EditField(

_resources.getString(FIELD_WEBSITE), "",

Integer.MAX_VALUE,BasicEditField.FILTER_URL);

specialtyfield = new EditField(

_resources.getString(FIELD_SPECIALTY), "",

Integer.MAX_VALUE, BasicEditField.FILTER_DEFAULT);

mainScreen.add(namefield);

mainScreen.add(addressfield);

mainScreen.add(phonefield);

mainScreen.add(websitefield);

mainScreen.add(specialtyfield);

mainScreen.addKeyListener(this);

mainScreen.addTrackwheelListener(this);

pushScreen(mainScreen);

}

public void makeMenu( Menu menu, int instance ) {

menu.add(saveItem);

menu.add(getItem);

menu.add(phoneItem);

menu.add(browserItem);

super.makeMenu(menu, instance);

}

public void onExit() {

Dialog.alert(_resources.getString(APP_EXIT));

}

Last Updated:2007年2月1日

BlackBerry 应用程序开发者指南第二卷：高级–第7章与BlackBerry应用程序通信

Taigoo — Mon, 28 Apr 2008 21:49:49 +0000

第7章与BlackBerry应用程序通信

启动BlackBerry应用程序

加入一个菜单项到BlackBerry应用程序中

代码实例

启动BlackBerry应用程序

调用API(net.rim.blackberry.api.invoke)允许应用程序启动标注你的BlackBerry应用程序.
注: 当应用程序调用电话时,检查一个ControlledAccessException.如果系统管理员通过应用程序控制限制访问电话应用程序,将抛出一个运行时错误. 为获得更多信息,参看BlackBerry应用程序开发者指南 第2卷:高级第1卷:基础.

调用API新功能

从BlackBerry JDE 4.1起,有下面的功能:

可以改变AddressBookArguments (net.rim.blackberry.api.invoke.AddressBookArguments)来打开一个使用PIMContact的联系人.
可以改变CalendarArguments (net.rim.blackberry.api.invoke.CalendarArguments)查看存在的PIM事件.你不可以创建一个来自PIM对象的新事件.
可以改变MessageArguments (net.rim.blackberry.api.invoke.MessageArguments)创建一个包含主题和内容的消息
在Task应用程序无变化的情况下,不可以更新TaskArguments (net.rim.blackberry.api.invoke.TaskArguments).

为启动一个应用程序,调用带有合适常量和ApplicationArguments 子类的对象的Invoke.invokeApplication(int, ApplicationArguments)方法.

注:使用Invoke.invokeApplication(int, ApplicationArguments)将导致一个处理上下文的转化.当BlackBerry程序启动时,你的应用程序将失去控制.在启动的应用程序对话中止时,内容可能不会返回给你的应用程序.

应用程序	常量	类
Address book(地址本)	APP_TYPE_ADDRESSBOOK	AddressBookArguments
Calendar(日历)	APP_TYPE_CALENDAR	CalendarArguments
Memo pad(便笺)	APP_TYPE_MEMOPAD	MemoArguments
Messages(消息)	APP_TYPE_MESSAGES	MessageArguments
Phone(电话)	APP_TYPE_PHONE	PhoneArguments
Tasks(任务)	APP_TYPE_TASKS	TaskArguments

技巧:从浏览器应用程序API(net.rim.blackberry.api.browser)中调用BlackBerry浏览器.参看51页的”在浏览器中显示内容”获得更多信息.电话API (net.rim.blackberry.api.phone)提供访问电话应用程序的高级特性的能力. 参看77页的”电话API”获得更多信息

注: 当应用程序调用电话时,检查一个ControlledAccessException.如果系统管理员通过应用程序控制限制访问电话应用程序,将抛出一个运行时错误. 为获得更多信息,参看BlackBerry应用程序开发者指南 第2卷:高级第1卷:基础.

下面的Restaurants.java实例的摘录创建了一个菜单调用电话程序打电话给餐厅.

private MenuItem phoneItem = new MenuItem(_resources.getString(MENUITEM_PHONE), 110, 12) {

public void run() {

synchronized(store) {

String phoneNumber = phonefield.getText();

if ( phoneNumber.length == 0 ) {

Dialog.alert(_resources.getString(ALERT_NO_PHONENUMBER));

}

else {

PhoneArguments call = new PhoneArguments(PhoneArguments.ARG_CALL,

phoneNumber);

Invoke.invokeApplication(Invoke.APP_TYPE_PHONE, call);

}

};

加入一个菜单项到Blackberry应用程序中

应用程序菜单项API在net.rim.blackberry.api.menuitem包中.它使你可以增加一个菜单项到BlackBerry应用程序中.

例如,为了将一个客户关系管理程序集成到BlackBerry地址本程序中,加入一个View Sales Order菜单项.当用户单击View Sales Order菜单项时,应用程序将打开此联系人的销售订单列表.

ApplicationMenuItemRepository类让你可以加入或删除应用程序菜单项.它提供一些常量来定义一个菜单项显示的应用程序上下文.例如, 当一个消息窗口打开时,ApplicationMenuItemRepository.MENUITEM_MESSAGE_LIST常量指定了显示的菜单项.

ApplicationMenuItem抽象类定义了一个在应用程序菜单里显示的菜单项.

创建一个菜单项

扩展 ApplicationMenuItem 抽象类.

public class SampleMenuItem extends ApplicationMenuItem

{

…

}

指定菜单项在菜单的位置

你可以选择性的覆盖构造子.在下面的代码实例中,构造子调用了ApplicationMenuItem(),它带有一个菜单项在菜单里的相对位置.(一个较大的数字意味着菜单项在菜单的较低位置).

SampleMenuItem() {

super(20);

}

指定菜单项的文本

toString()的实现指定了菜单项在菜单中显示的文本.

public String toString() {

return "Open the Contacts Demo application";

}

指定菜单项的行为

run()的实现指定了某个菜单项的行为.

public Object run(Object context) {

Contact c = (Contact)context; // An error if this does not work.

}

if ( c ! null ) {

new ContactsDemo().enterEventDispatcher();

}

else

{

throw new IllegalStateException( "Context is null, expected a Contact instance");

}

Dialog.alert("Viewing a message in the messaging view");

return null;

}

注册应用程序菜单项

获取应用程序菜单项库(repository)

调用 ApplicationMenuItemRepository.getInstance().

ApplicationMenuItemRepository repository =

ApplicationMenuItemRepository.getInstance();

定义一个唯一值

使用包名的哈希值作为应用程序菜单项库的唯一ID.

long ID = 0×7cab1e23b72a0033L;

// Hash of com.rim.samples.docs.menuitem.

创建应用程序菜单项

调用构造函数.

TestApplicationMenuItem tami = new TestApplicationMenuItem();

加入一个菜单项到菜单库

调用addMenuItem().

repository.addMenuItem(ApplicationMenuItemRepository.MENUITEM_ADDRESSCARD_VIEW, tami);

代码实例

当用户在地址本里查看一个联系人时,下面的代码将创建一个菜单项.当用户点击此菜单项, 将显示Contacts Demo程序.

例: DemoAppMenuItem.java

/**

* DemoApplicationMenuItem.java

package com.rim.samples.docs.menuitem;

import net.rim.device.api.system.*;

import net.rim.device.api.ui.component.Dialog.*;

import net.rim.blackberry.api.menuitem.*;

import javax.microedition.pim.*;

import net.rim.device.api.pdap.*;

import com.rim.samples.docs.contactsdemo.*;

public final class DemoAppMenuItem extends Application {

private static long ID = 0×7cab1e23b72a0033L;

//com.rim.samples.docs.menuitem

public static void main(String[] args) {

DemoAppMenuItem app = new DemoAppMenuItem();

app.enterEventDispatcher();

}

DemoAppMenuItem() {

ApplicationMenuItemRepository amir =

ApplicationMenuItemRepository.getInstance();

amir.addMenuItem(ApplicationMenuItemRepository.MENUITEM_ADDRESSCARD_VIEW,

new SampleMenuItem());

}

private static class SampleMenuItem extends ApplicationMenuItem {

SampleMenuItem() {

super(20);

}

public String toString() {

return "Open the Contacts Demo";

}

public Object run(Object context) {

BlackBerryContact c = (BlackBerryContact)context; //an error if this doesn’t work

if ( c != null ) {

new ContactsDemo().enterEventDispatcher();

}

else {

throw new IllegalStateException( "Context is null, expected a Contact instance");

}

net.rim.device.api.ui.component.Dialog.alert("Viewing an email message in the email view");

return null;

}

Last Updated:2007年2月1日

专注于blackberry » api

每周一技：HyperLinkField

故技重施：Blackberry Push API

黑莓通过编程的方式挂电话

BlackBerry 应用程序开发者指南 第二卷：高级–第12章 管理应用程序

第12章 管理应用程序

锁住一个BlackBerry设备

决定一个BlackBerry设备是否锁住

解锁一个BlackBerry设备

从BlackBerry设备数据库删除一个模块

BlackBerry 应用程序开发者指南 第二卷：高级–第13章 应用程序间共享运行时对象

第13章 应用程序间共享运行时对象

BlackBerry 应用程序开发者指南 第二卷：高级–第11章 管理通知(Notification)

第11章 管理通知(Notification)

通知API

为延续事件提供一个自定义的UI通知

定义一个唯一ID

设置用户Profile选项

启动BlackBerry设备数据备份

启动BlackBerry设备数据恢复

BlackBerry 应用程序开发者指南 第二卷：高级–第10章 访问安装和配置信息

第10章 访问安装和配置信息

服务定制API(Service Book API)

BlackBerry 应用程序开发者指南 第二卷：高级–第9章 备份和恢复持久数据

第9章 备份和恢复持久数据

同步API

定义一个唯一ID

当BlackBery设备启动时注册一个同步集合

BlackBerry 应用程序开发者指南 第二卷：高级–第8章 存储持久数据

第8章 存储持久数据

MIDP存储记录

BlackBerry持久存储

创建一个唯一的long键

BlackBerry 应用程序开发者指南 第二卷：高级–第7章 与BlackBerry应用程序通信

第7章 与BlackBerry应用程序通信

启动BlackBerry应用程序

调用API新功能

加入一个菜单项到Blackberry应用程序中

BlackBerry 应用程序开发者指南第二卷：高级–第12章管理应用程序

第12章管理应用程序

BlackBerry 应用程序开发者指南第二卷：高级–第13章应用程序间共享运行时对象

第13章应用程序间共享运行时对象

BlackBerry 应用程序开发者指南第二卷：高级–第11章管理通知(Notification)

第11章管理通知(Notification)

BlackBerry 应用程序开发者指南第二卷：高级–第10章访问安装和配置信息

第10章访问安装和配置信息

BlackBerry 应用程序开发者指南第二卷：高级–第9章备份和恢复持久数据

第9章备份和恢复持久数据

BlackBerry 应用程序开发者指南第二卷：高级–第8章存储持久数据

第8章存储持久数据

BlackBerry 应用程序开发者指南第二卷：高级–第7章与BlackBerry应用程序通信

第7章与BlackBerry应用程序通信