专注于blackberry » doc

好消息，Blackberry开发文档基础篇发布。

Taigoo — Mon, 28 Jul 2008 09:08:22 +0000

经过前期在3个位置的调查，最终选用PDF作为文档格式。

直接点击下面下载。

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 应用程序开发者指南第二卷：高级–第6章访问电话应用程序

Taigoo — Mon, 28 Apr 2008 21:47:38 +0000

第6章访问电话应用程序

电话API

监听电话事件

访问和管理电话记录

电话API

电话API((net.rim.blackberry.api.phone)可以访问电话应用程序的高级特性,例如允许应用程序将DTMF(双声多频)的音调(tone)到活动的通话中.
注:为了简单调用电话应用程序和拨打一个电话,使用调用API(net.rim.blackberry.api.invoke),为获得更多信息,参看83业的”启动应用程序”. 当应用程序第一次访问电话API时,检查一个 NoClassDefFoundError.如果系统管理员通过应用程序控制限制访问HTTP过滤器API,将抛出此错误. 为获得更多信息,参看BlackBerry应用程序开发者指南 第2卷:高级第1卷:基础.

接收一个电话

调用Phone.getActiveCall()接收一个活动的电话.根据电话ID获取一个电话, 调用 Phone.getCall(int).

PhoneCall call = Phone.getActiveCall();

获取电话信息

PhoneCall类提供方法使应用程序获取电话的信息.例如,下面的代码检验电话的通话时间,电话的状态,以及在显示来电显示消息之前它是否正在出去.

int threshold = 120; // Alert user if outgoing calls last longer than threshold.

int elapsedTime = call.getElapsedTime();

// Use getStatusString() to retrieve status as an string.

int status = call.getStatus();

if ((status == PhoneCall.STATUS_CONNECTED ||

status == PhoneCall.STATUS_CONNECTING) && call.isOutGoing()

&& elapsedTime > threshold) {

// Use getCallId() to retrieve the caller ID as as an integer.

String phoneNumber = call.getDisplayPhoneNumber();

Status.show("Your call to " + phoneNumber + " has lasted more than " +

(String)threshold + ".");

}

将DTMF音调增加到发送队列中

一个DTMF音调由在同一时间里播放的高低频率组成.

键	低音	高音
1	697	1209
2	697	1336
3	697	1477
4	770	1209
5	770	1336
6	770	1477
7	852	1209
8	852	1336
9	852	1477
0	941	1209
*	941	1336
#	941	1477

将单个DTMF音调加入到发送队列中

注:如果没有其他音调加入时,BlackBerry设备播放DTMF音,同时覆写对话.

调用sendDTMFTone().

将多个DTMF音调加入到发送队列中

调用sendDTMFTones().

为当前电话获取发送队列

调用getDTMFTones().

监听电话事件

PhoneListener接口的实现使应用程序可以监听电话的事件.

调用Phone.addPhoneListener()方法向系统注册你的实现.

为了注销一个电话监听者,调用removePhoneListener().

为了完成一个指定的事件,实现下面的方法.

方法	描述
callAdded(int)	当一个电话加入到一个会议电话时调用.
callAnswered(int)	当用户接听电话时调用(需用户驱动).
callConferenceCallEstablished(int)	当建立好一个电话会议时调用.
callConnected(int)	当网络指定一个连接事件时调用(网络驱动).
callDirectConnectConnected(int)	当一个直线电话(Direct-connect call)连接时调用
callDirectConnectDisconnected(int)	当一个直线电话断开时调用.
callDisconnected(int)	当断开一个电话时调用.
callEndedByUser(int)	当用户中止通话时调用.
callFailed(int, int)	当电话失败时调用.
callHeld(int)	当出去的电话锁住时调用.
callIncoming(int)	当一个新电话进来时调用.
callInitiated(int)	当BlackBerry设备初始化一个出去的电话时调用.
callRemoved(int)	当一个电话从会议电话里断开时调用.
callResumed(int)	当一个锁住的电话重启时调用.
callWaiting(int)	当一个电话正在等待时调用.
conferenceCallDisconnected(int)	.当会议电话中止时调用.(所有的成员都断开).

访问和管理电话日志

电话记录API(net.rim.blackberry.api.phone.phonelogs)允许应用程序访问电话应用程序记录文件.电话呼叫记录包含每个单独电话的记录,它们分组到一个电话日志里.
注: 应用程序第一次访问电话日API时,检查一个 NoClassDefFoundError.如果系统管理员通过应用程序控制限制访问电话日志,将抛出此错误. 为获得更多信息,参看BlackBerry应用程序开发者指南 第2卷:高级第1卷:基础.

获取一个电话日志

PhoneLogs类代表一个电话历史记录.它提供方法允许你打开,增加,删除,或交换呼叫记录.

>调用honeLogs.getInstance().

PhoneLogs _logs = PhoneLogs.getInstance

获取文件夹的电话呼叫数

电话日志分成2个文件夹: FOLDER_NORMAL_CALLS 和 FOLDER_MISSED_CALLS.

>调用 numberOfCalls(int).

int numberOfCalls = _logs.numberOfCalls(FOLDER_NORMAL_CALLS);

获取一个呼叫记录

你可以实例化2种类型的呼叫记录: PhoneCallLog对象,它仅可以有一个参与者,以及ConferencePhoneCallLog对象,它有2个或多个参与者.这2个对象可以使你获取或改变呼叫记录信息,例如参与者或呼叫日期.

>调用 PhoneLogs.callAt(int index, long folderID).

PhoneCallLog phoneLog = (PhoneCallLog)_logs.callAt(0);

获取一个电话参与者

PhoneCallLogID类根据电话号码标志电话里的参与者.

>调用 PhoneCallLog.getParticipant(int)或 ConferencePhoneCallLog.getParticipantAt().

PhoneCallLogID participant = phoneCallLog.getParticipant();

PhoneCallLogID participant = ConferencePhoneCallLog.getParticipant();

获取电话号码类型

PhoneCallLogID类为日志标志了电话的类型.例如,记录在地址本里的Home(家庭),Mobile(移动),Work(工作)或Fax(传真).

>调用PhoneCallLogID.getType().

String phoneType = PhoneCallLogID.getType();

创建一个呼叫记录或会议电话记录

注: PhoneCallLogID构造函数删除了电话号码里的短横以及其他非数字的字符

创建一个PhoneCallLog或ConferencePhoneCallLog对象的实例

为电话的构造函数提供日期,持续时间,参与者,以及留言参数

Date date = new Date("1000"); // date of call

int duration = 60; // duration of call

PhoneCallLogID caller1 = new PhoneCallLogID("555-1234"); // first participant

PhoneCallLogID caller2 = new PhoneCallLogID("555-1235"); // second participant

String notes = "New call."; // notes

ConferencePhoneCallLog conferenceCall =

new ConferencePhoneCallLog(date, duration, PhoneLogs.FOLDER_NORMAL_CALLS,

caller1, caller2, notes);

将电话加入到电话日志的下一个可用的索引上

>调用PhoneLogs.addCall(CallLog call).

_logs.addCall(conferenceCall);

用新呼叫记录代替给定索引的呼叫记录

>调用 PhoneLogs.swapCall(CallLog call,int index,long folderID).

_logs.swapCall(conferenceCall, 0, FOLDER_NORMAL_CALLS);

注: swapCall()方法删除给定索引的呼叫记录..

删除一个呼叫记录

>调用 PhoneLogs.deleteCall().

_logs.deleteCall(0);

代码实例

下面的代码实例计算某个给定的参与者拨打电话的时间.

例: PhoneLogsDemo.java

/**

* PhoneLogsDemo.java

package com.rim.samples.docs.phonelogs;

import net.rim.blackberry.api.phone.phonelogs.*;

import java.lang.*;

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

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

public class PhoneLogsDemo extends Application {

private PhoneLogs _logs;

private int _timeSpokenTo;

static public void main(String[] args) {

PhoneLogsDemo app = new PhoneLogsDemo();

app.enterEventDispatcher();

}

private PhoneLogsDemo() {

_logs = PhoneLogs.getInstance();

PhoneLogsDemo phoneLogsDemo = new PhoneLogsDemo();

PhoneCallLogID participant = new PhoneCallLogID("5551234");

_timeSpokenTo = phoneLogsDemo.findTimeSpokenTo(participant,

PhoneLogs.FOLDER_NORMAL_CALLS);

}

// Returns the number of seconds spent on the phone with a participant.

public int findTimeSpokenTo(PhoneCallLogID participant,

long folder) {

int numberOfCalls = this._logs.numberOfCalls(folder);

int timeSpokenTo = 0;

PhoneCallLog phoneCallLog;

ConferencePhoneCallLog conferencePhoneCallLog;

for (int i = 0; i < numberOfCalls; i++) {

Object o = _logs.callAt(i, folder);

if (o instanceof PhoneCallLog) {

phoneCallLog = (PhoneCallLog)_logs.callAt(i, folder);

if ( phoneCallLog.getParticipant() == participant)

timeSpokenTo += phoneCallLog.getDuration();

}

else {

conferencePhoneCallLog = (ConferencePhoneCallLog)_logs.callAt(i, folder);

int participants = conferencePhoneCallLog.numberOfParticipants();

for (int j = 0; j < participants; j++)

if (conferencePhoneCallLog.getParticipantAt(j) == participant) {

timeSpokenTo += conferencePhoneCallLog.getDuration();

j = participants;

}

return timeSpokenTo;

}

Last Updated:2007年1月31日

BlackBerry 应用程序开发者指南第二卷：高级–第5章 BlackBerry浏览器

Taigoo — Mon, 28 Apr 2008 04:28:57 +0000

第5章 BlackBerry浏览器

浏览器API

在浏览器显示Web内容

在一个浏览器域里显示Web内容

支持附加的MIME类型

注册一个HTTP过滤器

浏览器API

API名和包	描述
浏览器应用程序API(net.rim.blackberry.api.browser)	通过调用Blackberry浏览器,API允许应用程序显示web内容,包括支持的图片格式,HTML以及WML页面.也允许应用程序提供HTTP请求的一个Referrer,HTTP头,以及提交的内容.为获得更多信息,参看51页的”在浏览器显示Web内容”.
浏览器域API (net.rim.blackberry.api.browser.field)	此API允许一个应用程序获取web内容在一个浏览器域里的显示,此域包含在应用程序UI里.也允许应用程序配置浏览器域的表现形式,例如去除滚动条,或者指定仅显示屏幕一部分的浏览器域.
浏览器页面API(net.rim.blackberry.api.browser.plugin)	此API允许应用程序支持附加的MIME类型.当BlackBerry启动时,注册一个提交提供者,所有后发的浏览器对话将支持附加的MIME类型.为获取更多信息,参看66页的”支持附加的MIME类型”.
HTTP过滤器API (net.rim.device.api.io.http)	API允许应用程序向浏览器注册一个或多个URL的提供者.为获取更多信息,参看71页的”注册一个HTTP过滤器”.

在浏览器里显示Web内容

为了在浏览器里显示web内容,使用浏览器应用程序API(net.rim.blackberry.api.browser).

获取一个浏览器对话(Session)

为了获取一个缺省的BrowserSession对象,调用静态方法Browser.getDefaultSession().本对象允许你访问正在BlackBerry设备上运行的浏览器.

为了新增一个约会,调用EventList.importEvent().
注:获取缺省的对话会覆写任何BlackBerry设备上已经打开的对话.

为获取一个不同的对话,调用getSession().此方法根据它的唯一ID(UID)获取一个浏览器配置服务记录.为获得更多信息,参见113页的”服务定制API”.

请求一个Web页面

为请求一个Web页面,调用BrowserSession.displayPage()方法.下面的实例使用了仅接受一个URL的displayPage()方法.为指定一个referrer,HTTP头,以及提交的数据,使用接受这些附加信息的方法.

代码实例

下面来自Restaurants.java实例的引用创建了一个菜单,此菜单会在浏览器中显示一个Web页面.

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);

}

};

在浏览器域显示Web内容

为了在应用程序UI里包含一个浏览器域,使用浏览器域API (net.rim.device.api.browser.field).浏览器呈现(rendering)库为域处理web内容的描绘,然后返回一个BrowserField-在此域URL内容得到描绘-到你的应用程序显示.
注:用来打开一个浏览器域的浏览器对话独立于BlackBerry设备上缺省的浏览器对话. 任何打开的浏览器对话则不受影响.

RenderingApplication接口定义了一个描绘对话所需要的回调功能来帮助处理URL资源, RenderingApplication接口的实现在一个浏览器域里显示web内容.

为呈现创建一个独立的线程

当应用程序获取和显示浏览器域时,为阻止应用程序挂起,在一个独立线程上完成这些操作.

class CreationThread extends Thread {

BrowserFieldHandlerApplication _callBackApplication;

BasicRenderingApplication _renderingApplication;

public CreationThread(BrowserFieldHandlerApplication callBackApplication) {

_callBackApplication = callBackApplication;

}

public void run() {

_renderingApplication = new BasicRenderingApplication(_callBackApplication);

BrowserField field = _renderingApplication.getBrowserField("www.blackberry.com");

_callBackApplication.displayBrowserField(field);

}

设置呈现选项

覆写getRenderingOptions().如果你没有覆写此方法, 将使用缺省的呈现选项.为获得更多信息,参看API参考的RenderingOptions.

处理事件

eventOccurred()的实现处理事件,例如一个URL请求.

public Object eventOccurred(Event event) {

int eventId = event.getUID();

switch (eventId) {

case Event.EVENT_URL_REQUESTED : {

UrlRequestedEvent e = (UrlRequestedEvent) event;

// This is a regular request.

String absoluteUrl = e.getURL();

HttpConnection conn = null;

OutputStream out = null;

try {

conn = (HttpConnection) Connector.open(absoluteUrl);

FormData postData = e.getPostData();

if (postData == null) {

conn.setRequestMethod(HttpConnection.GET);

}

else {

conn.setRequestMethod(HttpConnection.POST);

byte[] postBytes = postData.getBytes();

conn.setRequestProperty(HttpProtocolConstants.HEADER_CONTENT_LENGTH,

String.valueOf(postBytes.length));

if (conn.getRequestProperty(

HttpProtocolConstants.HEADER_CONTENT_TYPE) == null) {

conn.setRequestProperty(

HttpProtocolConstants.HEADER_CONTENT_TYPE,

postData.getContentType());

}

out = conn.openOutputStream();

out.write(postBytes);

}

HttpHeaders requestHeaders = e.getHeaders();

if (requestHeaders != null) {

/* From http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15.1.3

* Clients SHOULD NOT include a Referer header field in a

* (non-secure) HTTP request if the referring page was

* transferred with a secure protocol.*/

String referer =

requestHeaders.getPropertyValue("referer");

boolean sendReferrer = true;

if (referer != null && referer.startsWith("https:") &&

!absoluteUrl.startsWith("https:")) {

sendReferrer = false;

}

int size = requestHeaders.size();

for (int i = 0; i < size; i++) {

String header = requestHeaders.getPropertyKey(i);

// Remove refer header if needed.

if ( !sendReferrer && header.equals("referer")) {

requestHeaders.removeProperty(i);

continue;

}

conn.setRequestProperty( header,

requestHeaders.getPropertyValue( i ) );

}

catch (IOException e1) {

}

finally {

if (out != null) {

try {

out.close();

}

catch (IOException e2) {

}

BrowserField browserField = getBrowserField(conn, e);

_callbackApplication.displayBrowserField(browserField);

break;

}

case Event.EVENT_BROWSER_FIELD_CHANGED : {

// Browser field title might have changed. Update title.

break;

}

case Event.EVENT_REDIRECT : {

RedirectEvent e = (RedirectEvent) event;

switch (e.getType()) {

case RedirectEvent.TYPE_SINGLE_FRAME_REDIRECT :

// Show redirect message.

Application.getApplication().invokeAndWait(new Runnable() {

public void run() {

Status.show("");

}

});

break;

case RedirectEvent.TYPE_JAVASCRIPT :

case RedirectEvent.TYPE_META :

case RedirectEvent.TYPE_300_REDIRECT :

}

String absoluteUrl = e.getLocation();

HttpConnection conn = null;

try {

conn = (HttpConnection) Connector.open(absoluteUrl);

}

catch (IOException e1) {

}

BrowserField browserField = getBrowserField(conn,

e.getOriginalEvent());

_callbackApplication.displayBrowserField(browserField);

break;

}

case Event.EVENT_CLOSE :

// Close the appication.

break;

case Event.EVENT_SET_HEADER :// no cache support

case Event.EVENT_SET_HTTP_COOKIE : // no cookie support

case Event.EVENT_HISTORY : // no history support

case Event.EVENT_LOADING_IMAGES :// no progress bar is supported

case Event.EVENT_EXECUTING_SCRIPT : // no progress bar is supported

case Event.EVENT_FULL_WINDOW : // no full window support

case Event.EVENT_STOP : // no stop loading support

default :

}

return null;

}

为呈现获取浏览器内容

getBrowserField()的实现为呈现获取浏览器内容. getBrowserField()方法调用RenderingSession.getBrowserField()获取一个浏览器域.应用程序不能直接实例化BrowserField

public BrowserField getBrowserField (String absoluteUrl) {

HttpConnection conn = null;

try {

conn = (HttpConnection) Connector.open(absoluteUrl);

// Set transcode to true.

conn.setRequestProperty( "x-rim-transcode-content", "*/*" );

}

catch (IOException e1) {

}

return getBrowserField(conn, null);

}

private BrowserField getBrowserField(HttpConnection conn, Event e) {

BrowserField field = null;

try {

field = _renderingSession.getBrowserField(conn, this, e);

}

catch (RenderingException re) {

return null;

}

// Add to the event queue a thread that invokes finishLoading().

Application.getApplication().invokeLater(new RenderingThread(field));

return field;

}

描绘浏览器域

调用BrowserField.finishLoading().在下面的代码实例中, BrowserField.getBrowserField()将一个新的描绘线程加载到应用程序事件队列里来运行finishLoading().
注:HTML文件显示一个空白域,直到你调用BrowserField.finishLoading().在调用此方法前WML文件和图像可能加载 .在一个独立线程上运行finishLoading(),这样UI不会锁住.

class RenderingThread implements Runnable {

BrowserField _browserField;

RenderingThread(BrowserField field) {

_browserField = field;

}

public void run() {

try {

_browserField.finishLoading();

}

catch (RenderingException e) {

// Handle exception.

}

显示浏览器域

displayBrowserField()的实现删除屏幕内容,然后增加浏览器域到屏幕.

public void displayBrowserField(BrowserField browserField) {

synchronized (Application.getEventLock()) {

_vfm.deleteAll();

_vfm.add(browserField);

}

代码实例

下面的实例包含了3个文件: BasicRenderingApplication.java, BrowserFieldHandlerApplication.java, 以及 BrowserFieldSampleApp.java.

例:浏览器域实例

/**

* BasicRenderingApplication.java

package com.rim.samples.docs.browser;

import java.io.IOException;

import java.io.OutputStream;

import javax.microedition.io.Connector;

import javax.microedition.io.HttpConnection;

import net.rim.device.api.browser.field.*;

import net.rim.device.api.io.http.HttpHeaders;

import net.rim.device.api.io.http.HttpProtocolConstants;

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

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

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

import com.rim.samples.docs.browser.BrowserFieldHandlerApplication.*;

final public class BasicRenderingApplication implements RenderingApplication

{

RenderingSession _renderingSession;

BrowserFieldHandlerApplication _callbackApplication;

public BasicRenderingApplication(BrowserFieldHandlerApplication callBackApplication) {

_renderingSession = RenderingSession.getNewInstance();

_callbackApplication = callBackApplication;

}

/**

* * Simple method to get a browser field by specifying the URL.

* * This call blocks until the browser field is returned by RenderingSession.getBrowserField().

* * The browser field can continue to be rendered after the field is returned.

* *

* * @param absoluteUrl - absolute url of the page to render

* * @return rendered browser field

* */

public BrowserContent getBrowserField (String absoluteUrl) {

HttpConnection conn = null;

try {

conn = (HttpConnection) Connector.open(absoluteUrl);

// Set transcode to true.

conn.setRequestProperty( "x-rim-transcode-content", "*/*" );

}

catch (IOException e1) {

}

return getBrowserField(conn, null);

}

private BrowserContent getBrowserField(HttpConnection conn, Event e) {

BrowserContent field = null;

try {

field = _renderingSession.getBrowserContent(conn, this, e);

}

catch (RenderingException re) {

return null;

}

Application.getApplication().invokeLater(new RenderingThread(field));

return field;

}

/**

* * Invoked when an event occurs.

* */

public Object eventOccurred(Event event) {

int eventId = event.getUID();

switch (eventId) {

case Event.EVENT_URL_REQUESTED : {

UrlRequestedEvent e = (UrlRequestedEvent) event;

// this is a regular request

String absoluteUrl = e.getURL();

HttpConnection conn = null;

OutputStream out = null;

try {

conn = (HttpConnection) Connector.open(absoluteUrl);

byte[] postData = e.getPostData();

if (postData == null) {

conn.setRequestMethod(HttpConnection.GET);

}

else {

conn.setRequestMethod(HttpConnection.POST);

conn.setRequestProperty( HttpProtocolConstants.HEADER_CONTENT_LENGTH,

String.valueOf(postData.length));

out = conn.openOutputStream();

out.write(postData);

}

HttpHeaders requestHeaders = e.getHeaders();

if (requestHeaders != null) {

/* From http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15.1.3

* …

* Clients SHOULD NOT include a Referer header field in a

* (non-secure) HTTP request if the referring page was

* transferred with a secure protocol.

* */

String referer = requestHeaders.getPropertyValue("referer");

boolean sendReferrer = true;

if (referer != null && referer.startsWith("https:") &&

!absoluteUrl.startsWith("https:")) {

sendReferrer = false;

}

int size = requestHeaders.size();

for (int i = 0; i < size; i++) {

String header = requestHeaders.getPropertyKey(i);

// Remove refer header if needed.

if ( !sendReferrer && header.equals("referrer")) {

requestHeaders.removeProperty(i);

continue;

}

conn.setRequestProperty( header,

requestHeaders.getPropertyValue( i ) );

}

catch (IOException e1) {

}

finally {

if (out != null) {

try {

out.close();

}

catch (IOException e2) {

}

BrowserContent browserField = getBrowserField(conn, e);

_callbackApplication.displayBrowserField(browserField);

break;

}

case Event.EVENT_BROWSER_CONTENT_CHANGED : {

// Browser field title might have changed. Update title.

break;

}

case Event.EVENT_REDIRECT : {

RedirectEvent e = (RedirectEvent) event;

switch (e.getType()) {

// Show redirect message.

Application.getApplication().invokeAndWait(new Runnable() {

public void run() {

Status.show("");

}

});

break;

case RedirectEvent.TYPE_JAVASCRIPT :

case RedirectEvent.TYPE_META :

case RedirectEvent.TYPE_300_REDIRECT :

}

String absoluteUrl = e.getLocation();

HttpConnection conn = null;

try {

conn = (HttpConnection) Connector.open(absoluteUrl);

}

catch (IOException e1) {

}

BrowserContent browserField = getBrowserField(conn, e.getOriginalEvent());

_callbackApplication.displayBrowserField(browserField);

break;

}

case Event.EVENT_CLOSE :

// Close the appication.

break;

case Event.EVENT_TICK_CONTENT_READ : // No progress bar is supported.

case Event.EVENT_SET_HEADER : // No cache support.

case Event.EVENT_SET_HTTP_COOKIE : // No cookie support.

case Event.EVENT_HISTORY : // No history support

case Event.EVENT_LOADING_IMAGES : // No progress bar is supported.

case Event.EVENT_EXECUTING_SCRIPT : // No progress bar is supported.

case Event.EVENT_FULL_WINDOW : // No full window support.

case Event.EVENT_STOP : // No stop loading support.

default :

}

return null;

}

/**

* * Retrieves the pixels of height available for provided browser content.

* * @param browserField Content for which to retrieve available pixels of height.

* * @return Height available.

* */

public int getAvailableHeight(BrowserContent browserField) {

// Field has full screen.

return Graphics.getScreenHeight();

}

/**

* * Retrieves the pixels of width available for provided browser content.

* */

public int getAvailableWidth(BrowserContent browserField) {

// Field has full screen.

return Graphics.getScreenWidth();

}

/**

* * Retrieves the history position for provided browser content.

* */

public int getHistoryPosition(BrowserContent browserField) {

// No history support.

return 0;

}

/**

* * Retrieves cookies associated with a provided URL.

* */

public String getHTTPCookie(String url) {

// No cookie support.

return null;

}

/**

* * Retrieves the specified resource.

public HttpConnection getResource( RequestedResource resource, BrowserContent referrer)

{

if (resource == null) {

return null;

}

// Check if this is cache-only request.

if (resource.isCacheOnly()) {

// No cache support.

return null;

}

String url = resource.getUrl();

if (url == null) {

return null;

}

// If referrer is null, return the connection.

if (referrer == null) {

HttpConnection conn;

try {

return (HttpConnection) Connector.open(resource.getUrl());

}

catch (IOException e) {

return null;

}

else {

// If referrer is provided, set up the connection on a

// separate thread.

Application.getApplication().invokeLater(

new RetrieveThread(resource, referrer));

}

return null;

}

/**

* * Invokes the provided runnable object.

* */

public void invokeRunnable(Runnable runnable) {

(new Thread(runnable)).run();

}

class RenderingThread implements Runnable {

BrowserContent _browserField;

RenderingThread(BrowserContent field) {

_browserField = field;

}

public void run() {

try {

_browserField.finishLoading();

}

catch (RenderingException e) {

}

class RetrieveThread implements Runnable {

BrowserContent _browserField;

RequestedResource _resource;

RetrieveThread(RequestedResource resource, BrowserContent referrer) {

_browserField = referrer;

_resource = resource;

}

public void run() {

HttpConnection conn;

try {

conn = (HttpConnection) Connector.open(_resource.getUrl());

}

catch (IOException e) {

return;

}

_resource.setHttpConnection(conn);

_browserField.resourceReady(_resource);

}

/**

* BasicRenderingApplication.java

package com.rim.samples.docs.browser;

import java.io.IOException;

import java.io.OutputStream;

import javax.microedition.io.Connector;

import javax.microedition.io.HttpConnection;

import net.rim.device.api.browser.field.*;

import net.rim.device.api.io.http.HttpHeaders;

import net.rim.device.api.io.http.HttpProtocolConstants;

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

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

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

import com.rim.samples.docs.browser.BrowserFieldHandlerApplication.*;

final public class BasicRenderingApplication implements RenderingApplication {

RenderingSession _renderingSession;

BrowserFieldHandlerApplication _callbackApplication;

public BasicRenderingApplication(BrowserFieldHandlerApplication callBackApplication) {

_renderingSession = RenderingSession.getNewInstance();

_callbackApplication = callBackApplication;

}

/**

* * Simple method to get a browser field by specifying the URL.

* * This call blocks until the browser field is returned by RenderingSession.getBrowserField().

* * The browser field can continue to be rendered after the field is returned.

* *

* * @param absoluteUrl - absolute url of the page to render

* * @return rendered browser field

* */

public BrowserContent getBrowserField (String absoluteUrl) {

HttpConnection conn = null;

try {

conn = (HttpConnection) Connector.open(absoluteUrl);

// Set transcode to true.

conn.setRequestProperty("x-rim-transcode-content", "*/*" );

}

catch (IOException e1) {

}

return getBrowserField(conn, null);

}

private BrowserContent getBrowserField(HttpConnection conn, Event e) {

BrowserContent field = null;

try {

field = _renderingSession.getBrowserContent(conn, this, e);

}

catch (RenderingException re) {

return null;

}

Application.getApplication().invokeLater(new RenderingThread(field));

return field;

}

/**

* * Invoked when an event occurs.

* */

public Object eventOccurred(Event event) {

int eventId = event.getUID();

switch (eventId) {

case Event.EVENT_URL_REQUESTED : {

UrlRequestedEvent e = (UrlRequestedEvent) event;

// this is a regular request

String absoluteUrl = e.getURL();

HttpConnection conn = null;

OutputStream out = null;

try {

conn = (HttpConnection) Connector.open(absoluteUrl);

byte[] postData = e.getPostData();

if (postData == null) {

conn.setRequestMethod(HttpConnection.GET);

}

else {

conn.setRequestMethod(HttpConnection.POST);

conn.setRequestProperty( HttpProtocolConstants.HEADER_CONTENT_LENGTH,

String.valueOf(postData.length));

out = conn.openOutputStream();

out.write(postData);

}

HttpHeaders requestHeaders = e.getHeaders();

if (requestHeaders != null) {

/* From http://www.w3.org/Protocols/rfc2616/rfc2616-sec15.html#sec15.1.3

* …

* Clients SHOULD NOT include a Referer header field in a

* (non-secure) HTTP request if the referring page was

* transferred with a secure protocol.*/

String referer = requestHeaders.getPropertyValue("referer");

boolean sendReferrer = true;

if (referer != null && referer.startsWith("https:")

&& !absoluteUrl.startsWith("https:")) {

sendReferrer = false;

}

int size = requestHeaders.size();

for (int i = 0; i < size; i++) {

String header = requestHeaders.getPropertyKey(i);

// Remove refer header if needed.

if ( !sendReferrer && header.equals("referrer")) {

requestHeaders.removeProperty(i);

continue;

}

conn.setRequestProperty( header, requestHeaders.getPropertyValue( i ) );

}

catch (IOException e1) {

}

finally {

if (out != null) {

try {

out.close();

}

catch (IOException e2) {

}

BrowserContent browserField = getBrowserField(conn, e);

_callbackApplication.displayBrowserField(browserField);

break;

}

case Event.EVENT_BROWSER_CONTENT_CHANGED : {

// Browser field title might have changed. Update title.

break;

}

case Event.EVENT_REDIRECT : {

RedirectEvent e = (RedirectEvent) event;

switch (e.getType()) {

case RedirectEvent.TYPE_SINGLE_FRAME_REDIRECT :

// Show redirect message.

Application.getApplication().invokeAndWait(new Runnable() {

public void run() {

Status.show("");

}

});

break;

case RedirectEvent.TYPE_JAVASCRIPT :

case RedirectEvent.TYPE_META :

case RedirectEvent.TYPE_300_REDIRECT :

}

String absoluteUrl = e.getLocation();

HttpConnection conn = null;

try {

conn = (HttpConnection) Connector.open(absoluteUrl);

}

catch (IOException e1) {

}

BrowserContent browserField = getBrowserField(conn, e.getOriginalEvent());

_callbackApplication.displayBrowserField(browserField);

break;

}

case Event.EVENT_CLOSE :

// Close the appication.

break;

case Event.EVENT_TICK_CONTENT_READ : // No progress bar is supported.

case Event.EVENT_SET_HEADER : // No cache support.

case Event.EVENT_SET_HTTP_COOKIE : // No cookie support.

case Event.EVENT_HISTORY : // No history support.

case Event.EVENT_LOADING_IMAGES : // No progress bar is supported.

case Event.EVENT_EXECUTING_SCRIPT : // No progress bar is supported

case Event.EVENT_FULL_WINDOW : // No full window support

case Event.EVENT_STOP : // No stop loading support.

default :

}

return null;

}

/**

* * Retrieves the pixels of height available for provided browser content.

* * @param browserField Content for which to retrieve available pixels of height.

* * @return Height available.

* */

public int getAvailableHeight(BrowserContent browserField) {

// Field has full screen.

return Graphics.getScreenHeight();

}

/**

* * Retrieves the pixels of width available for provided browser content.

* */

public int getAvailableWidth(BrowserContent browserField) {

// Field has full screen.

return Graphics.getScreenWidth();

}

/**

* * Retrieves the history position for provided browser content.

* */

public int getHistoryPosition(BrowserContent browserField) {

// No history support.

return 0;

}

/**

* * Retrieves cookies associated with a provided URL.

* */

public String getHTTPCookie(String url) {

// No cookie support.

return null;

}

/**

* * Retrieves the specified resource.

* */

public HttpConnection getResource( RequestedResource resource, BrowserContent referrer)

{

if (resource == null) {

return null;

}

// Check if this is cache-only request.

if (resource.isCacheOnly()) {

// No cache support.

return null;

}

String url = resource.getUrl();

if (url == null) {

return null;

}

// If referrer is null, return the connection.

if (referrer == null) {

HttpConnection conn;

try {

return (HttpConnection) Connector.open(resource.getUrl());

}

catch (IOException e) {

return null;

}

else {

// If referrer is provided, set up the connection on a

// separate thread.

Application.getApplication().invokeLater(

new RetrieveThread(resource, referrer));

}

return null;

}

/**

* * Invokes the provided runnable object.

* */

public void invokeRunnable(Runnable runnable) {

(new Thread(runnable)).run();

}

class RenderingThread implements Runnable {

BrowserContent _browserField;

RenderingThread(BrowserContent field) {

_browserField = field;

}

public void run() {

try {

browserField.finishLoading();

}

catch (RenderingException e) {

}

class RetrieveThread implements Runnable {

BrowserContent _browserField;

RequestedResource _resource;

RetrieveThread(RequestedResource resource, BrowserContent referrer) {

_browserField = referrer;

_resource = resource;

}

public void run() {

HttpConnection conn;

try {

conn = (HttpConnection) Connector.open(_resource.getUrl());

}

catch (IOException e) {

return;

}

_resource.setHttpConnection(conn);

_browserField.resourceReady(_resource);

}

支持附加MIME类型

浏览器页面API在net.rim.device.api.browser.plugin包中,它允许第三方应用程序向描绘库将它们自己注册为BlackBerry浏览器不支持的MIME类型的描绘提供者.
注: 如果你试着注册一个BlackBerry浏览器已经支持的MIME类型，BrowserFieldProviderRegistry.register()方法会抛出一个异常.为得到支持的MIME类型列表,调用RenderingSession.getSupportedMimeType().

注册一个MIME类型的呈现提供者

为支持附加的MIME类型,需要扩展BrowserContentProvider抽象类.为了指定显示特性,例如没有滚动条显示或全屏显示,需要实现BrowserPageContext接口.

呈现的类库调用BrowserContentProvider.getAccept()和BrowserContentProvider.getSupportedMimeTypes()标志提供者呈现的MIME类型.

列出接受的MIME类型

getAccept()和getSupportedMimeTypes()的实现列出了提供者接受的MIME类型,它们给定了一组呈现的选项. getAccept()方法考虑到已经设置的呈现选项.这个例子假设没有设置呈现选项.为得到更多信息.参看API参考的RenderingOptions

public String[] getAccept(RenderingOptions context) {

// Return subset of getSupportedMimeTypes() if accept depends on rendering

// options. For example, HTML can be turned off in the rendering options.

// This would cause HTMLConverter to remove HTML MIME types.

return ACCEPT;

}

public String[] getSupportedMimeTypes() {

return ACCEPT;

}

指定显示特征

BrowserPageContext接口的实现指定了显示的特征.如果没有实现此接口,将使用缺省的值.

在本例中,所有属性都是整型.一个带有Boolean,String,和Object属性的应用程序将实现对应的方法.

public boolean getPropertyWithBooleanValue(int id, boolean defaultValue) {

// TODO Implement.

return false;

}

public int getPropertyWithIntValue(int id, int defaultValue) {

if (id == BrowserPageContext.DISPLAY_STYLE) {

// Turn off the scroll bar.

return BrowserPageContext.STYLE_NO_VERTICAL_SCROLLBAR;

}

return 0;

}

public Object getPropertyWithObjectValue(int id, Object defaultValue) {

// TODO Implement.

return null;

}

public String getPropertyWithStringValue(int id, String defaultValue) {

// TODO Implement.

return null;

}

获取一个域呈现内容

实现getBrowserContent(BrowserContentProviderContext)方法.

public BrowserContent getBrowserContent( BrowserContentProviderContext context)

throws RenderingException {

if (context == null) {

throw new RenderingException("No Context is passed into Provider");

}

BrowserContentBaseImpl browserContentBaseImpl = new

BrowserContentBaseImpl(context.getHttpConnection().getURL(), null,

context.getRenderingApplication(),

context.getRenderingSession().getRenderingOptions(), context.getFlags());

VerticalFieldManager vfm = new VerticalFieldManager(Manager.VERTICAL_SCROLL);

vfm.add(new LabelField("Mime type: ") );

vfm.add(new LabelField(ACCEPT[0]));

vfm.add(new SeparatorField());

vfm.add(new LabelField("Content of the resource file: \n"));

vfm.add(new SeparatorField());

try {

HttpConnection conn = context.getHttpConnection();

InputStream in = conn.openInputStream();

byte[] data = IOUtilities.streamToBytes(in);

vfm.add(new LabelField(new String(data)));

}

catch (IOException e) {

// TODO Implement.

e.printStackTrace();

}

browserContentBaseImpl.setContent(vfm);

browserContentBaseImpl.setTitle(ACCEPT[0]);

// Set browser page context, this will tell the browser how to display this

// field.

browserContentBaseImpl.setBrowserPageContext(this);

return browserContentBaseImpl;

}

在BlackBerry启动时注册

创建一个类库工程,将它的属性设置为启动时自动运行.在libMain()里,调用BrowserFieldProviderRegistry.getInstance()方法,然后再调用invoke register().

public static void libMain( String[] args ) {

BrowserContentProviderRegistry converterRegistry =

BrowserContentProviderRegistry.getInstance();

if (converterRegistry != null) {

converterRegistry.register(new BrowserPlugin());

}

代码实例

下面的例子包含2个文件, LoaderApp.java和BrowserPlugin.java.当BlackBerry设备启动时LoaderApp.java增加一个新支持的MIME类型. BrowserPlugin.java包含了一个扩展了BrowserContentProvider的类.

例: BrowserPlugin.java和LoaderApp.java

/**

* LoaderApp.java

package com.rim.samples.docs.browser;

import net.rim.device.api.browser.plugin.BrowserContentProviderRegistry;

final class LoaderApp {

public static void libMain( String[] args ) {

BrowserContentProviderRegistry converterRegistry =

BrowserContentProviderRegistry.getInstance();

if (converterRegistry != null) {

converterRegistry.register(new BrowserPlugin());

}

/**

* BrowserPlugin.java

package com.rim.samples.docs.browser;

import java.io.IOException;

import java.io.InputStream;

import javax.microedition.io.HttpConnection;

import net.rim.device.api.browser.field.*;

import net.rim.device.api.browser.plugin.*;

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

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

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

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

/**

* Create a file with xxtest extension and associate that type with

* application/x-vnd.rim.xxxtest mime type on any server.

public final class BrowserPlugin extends BrowserContentProvider

implements BrowserPageContext {

private static final String[] ACCEPT = {"application/x-vnd.rim.xxxtest"};

/**

* Retrieves list of mime types this provider can accept given a set of rendering options.

* * @param context Rendering options in place this provider should consider.

* * @return Array of mime types this provider will accept, given the provided rendering

* options.

**/

public String[] getAccept(RenderingOptions context) {

// Return subset of getSupportedMimeTypes() if accept depends in rendering options.

// For example HTML can be disabled in the rendering options, and HTMLConverter would remove

// html MIME types.

return ACCEPT;

}

/**

* Retrieves a browser content capable of rendering the mime content this provider

* can handle.

* @param context Provider context object provided by rendering session.

* @return Browser content to render specialized content.

public BrowserContent getBrowserContent( BrowserContentProviderContext context)

throws RenderingException {

if (context == null) {

throw new RenderingException("No Context is passed into Provider");

}

BrowserContentBaseImpl browserContentBaseImpl =

new BrowserContentBaseImpl(context.getHttpConnection().getURL(),

null, context.getRenderingApplication(),

context.getRenderingSession().getRenderingOptions(),

context.getFlags());

VerticalFieldManager vfm = new VerticalFieldManager(Manager.VERTICAL_SCROLL);

vfm.add(new LabelField("Mime type: ") );

vfm.add(new LabelField(ACCEPT[0]));

vfm.add(new SeparatorField());

vfm.add(new LabelField("Content of the resource file: \n"));

vfm.add(new SeparatorField());

try {

HttpConnection conn = context.getHttpConnection();

InputStream in = conn.openInputStream();

int numBytes = in.available();

byte[] data = new byte[numBytes];

in.read(data, 0, numBytes);

vfm.add(new LabelField(new String(data)));

}

catch (IOException e) {

e.printStackTrace();

}

browserContentBaseImpl.setContent(vfm);

browserContentBaseImpl.setTitle(ACCEPT[0]);

// Set browser page context. This tells the browser how to display this field.

browserContentBaseImpl.setBrowserPageContext(this);

return browserContentBaseImpl;

}

/**

* * Retrieves all the mime content types supported by this provider.

* * @return Mime types this converter supports.

* */

public String[] getSupportedMimeTypes() {

return ACCEPT;

}

/**

* * Retrieves value of specified property as a boolean value.

* * @param id ID of property to query.

* * @param defaultValue Expected default value of property.

* * @return Current value of property.

* */

public boolean getPropertyWithBooleanValue(int id, boolean defaultValue) {

return false;

}

/**

* Retrieves value of specified property as an int.

* @param id ID of property to query.

* @param defaultValue Expected default value of property.

* @return Current value of property.

public int getPropertyWithIntValue(int id, int defaultValue) {

if (id == BrowserPageContext.DISPLAY_STYLE) {

// Disable the scroll bar.

return BrowserPageContext.STYLE_NO_VERTICAL_SCROLLBAR;

}

return 0;

}

/**

* Retrieves value of specified property as an object.

* @param id ID of property to query.

* @param defaultValue Expected default value of property.

* @return Current value of property.

public Object getPropertyWithObjectValue(int id, Object defaultValue) {

return null;

}

/* Retrieves value of specified property as a String value.

* @param id - ID of property to query.

* @param defaultValue - Expected default value of property.

* @return Current value of property.

public String getPropertyWithStringValue(int id, String defaultValue) {

return null;

}

注册一个HTTP过滤器

HTTP过滤器API(net.rim.device.api.io.http)允许应用程序向浏览器注册一个指定URL的提供者.当用户数输入指定的URL时,连接栈(connection stack)会重新路由到指定的应用程序.
注: 当应用程序第一次访问HTTP 过滤器API时,检查一个 NoClassDefFoundError.如果系统管理员通过应用程序控制限制访问HTTP过滤器API,将抛出此错误. 为获得更多信息,参看BlackBerry应用程序开发者指南 第2卷:高级第1卷:基础.

注册一个HTTP 过滤器

调用HttpFilterRegistry.registerFilter().提供拦截的URL以及定义拦截行为的应用程序包名作为参数.

HttpFilterRegistry.registerFilter("content.blackberry.com",

"com.rim.samples.device.httpfilterdemo.precanned");

启动时完成注册

创建一个类库工程,然后将它的属性设置为启动时自动运行.调用libMain()里的registerFilter().

代码实例

下面的实例包含2个文件: PackageManager.java,它在启动时注册过滤器,以及Protocol.java,它定义过滤器的行为.

例: HTTP 过滤器实例

/**

* PackageManager.java

package com.rim.samples.docs.httpfilterdemo;

import net.rim.device.api.io.http.HttpFilterRegistry;

/**

* This class runs on startup of the device and registers the necessary http filters.

final class PackageManager

{

public static void libMain(String[] args) {

HttpFilterRegistry.registerFilter("www.blackberry.com",

"com.rim.samples.docs.httpfilterdemo.filter");

}

/**

* Protocol.java

package com.rim.samples.docs.httpfilterdemo.filter;

import net.rim.device.api.io.FilterBaseInterface;

import java.io.*;

import javax.microedition.io.*;

/**

* This class implements a simple pass through mechanism that writes out the http response headers to System.out.

public final class Protocol implements FilterBaseInterface, HttpConnection {

private HttpConnection _subConnection;

/**

* Defined by FilterBaseInterface.

* This method opens a filtered Http Connection.

public Connection openFilter( String name, int mode, boolean timeouts )

throws IOException {

_subConnection = (HttpConnection)Connector.open("http:" + name +

";usefilter=false", mode, timeouts);

if (_subConnection != null) {

return this;

}

// Filed to open the sub connection; so let us fail too.

return null;

}

// Return a string representation of the URL for this connection.

public String getURL() {

return _subConnection.getURL();

}

// Returns the protocol name of the URL of this HttpConnection. e.g., http or https.

public String getProtocol() {

return _subConnection.getProtocol();

}

// Returns the host information of the URL of this HttpConnection.

//e.g. host name or IPv4 address.

public String getHost() {

return _subConnection.getHost();

}

// Returns the file portion of the URL of this HttpConnection.

public String getFile() {

return _subConnection.getFile();

}

/**

* Returns the ref portion of the URL of this HttpConnection.

* RFC2396 specifies the optional fragment identifier as the the text after the crosshatch (#)

* character in the URL. This information may be used by the user agent as additional

* reference information after the resource is successfully retrieved. The format and

* interpretation of the fragment identifier is dependent on the media type[RFC2046] of

* the retrieved information.

public String getRef() {

return _subConnection.getRef();

}

// Returns the network port number of the URL for this HttpConnection.

public int getPort() {

return _subConnection.getPort();

}

// Returns the query portion of the URL of this HttpConnection.

// RFC2396 defines the query component as the text after the first

// question-mark (?) character in the URL.

public String getQuery() {

return _subConnection.getQuery();

}

// Get the current request method. e.g. HEAD, GET, POST The default value is GET.

public String getRequestMethod() {

return _subConnection.getRequestMethod();

}

// Set the method for the URL request, one of: GET, POST, HEAD,

//subject to protocol restrictions. The default method is GET.

public void setRequestMethod(String method) throws IOException {

_subConnection.setRequestMethod(method);

}

// Returns the value of the named general request property for this connection.

public String getRequestProperty(String key) {

return _subConnection.getRequestProperty(key);

}

// Sets the general request property. If a property with the key already exists, overwrite its value with the new value.

// Note: HTTP requires all request properties which can legally have multiple instances with the

// same key to use a comma-separated list syntax which enables multiple properties to be appended into a single property.

public void setRequestProperty(String key, String value) throws IOException {

System.out.println("Request property : " + key + ", " + value );

_subConnection.setRequestProperty(key, value);

}

// Returns the HTTP response status code.

public int getResponseCode() throws IOException {

return _subConnection.getResponseCode();

}

// Gets the HTTP response message, if any, returned along with

//the response code from a server.

public String getResponseMessage() throws IOException {

return _subConnection.getResponseMessage();

}

// Returns the value of the expires header field.

public long getExpiration() throws IOException {

return _subConnection.getExpiration();

}

// Returns the value of the date header field.

public long getDate() throws IOException {

return _subConnection.getDate();

}

// Returns the value of the last-modified header field.

//The result is the number of milliseconds since January 1, 1970 GMT.

public long getLastModified() throws IOException {

return _subConnection.getLastModified();

}

// Returns the value of the named header field.

public String getHeaderField(String name) throws IOException

{

String value = _subConnection.getHeaderField(name);

System.out.println("Response property : " + name + ", " + value );

return value;

}

// Returns the value of the named field parsed as a number.

public int getHeaderFieldInt(String name, int def)

throws IOException {

return _subConnection.getHeaderFieldInt(name, def);

}

// Returns the value of the named field parsed as date. The result is the

// number of milliseconds since January 1, 1970 GMT represented by the named field.

public long getHeaderFieldDate(String name, long def) throws IOException {

return _subConnection.getHeaderFieldDate(name, def);

}

// Gets a header field value by index.

public String getHeaderField(int n) throws IOException {

return _subConnection.getHeaderField(n);

}

// Gets a header field key by index.

public String getHeaderFieldKey(int n) throws IOException {

return _subConnection.getHeaderFieldKey(n);

}

// Returns the type of content that the resource connected to is providing.

public String getType() {

return _subConnection.getType();

}

// Returns a string describing the encoding of the content

//which the resource connected to is providing.

public String getEncoding() {

return _subConnection.getEncoding();

}

// Returns the length of the content which is being provided.

public long getLength() {

return _subConnection.getLength();

}

// Opens and returns an input stream for a connection.

public InputStream openInputStream() throws IOException {

return _subConnection.openInputStream();

}

// Opens and returns a data input stream for a connection.

public DataInputStream openDataInputStream() throws IOException {

return _subConnection.openDataInputStream();

}

// Opens and returns an output stream for a connection.

public OutputStream openOutputStream() throws IOException {

return _subConnection.openOutputStream();

}

// Opens and returns a data output stream for a connection.

public DataOutputStream openDataOutputStream() throws IOException {

return _subConnection.openDataOutputStream();

}

// Closes the connection.

public void close() throws IOException {

_subConnection.close();

}

Last Updated:2007年1月30日

专注于blackberry » doc

好消息，Blackberry开发文档基础篇发布。

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 应用程序开发者指南 第二卷：高级–第6章 访问电话应用程序

第6章 访问电话应用程序

电话API

将DTMF音调增加到发送队列中

BlackBerry 应用程序开发者指南 第二卷：高级–第5章 BlackBerry浏览器

第5章 BlackBerry浏览器

在浏览器里显示Web内容

请求一个Web页面

在浏览器域显示Web内容

支持附加MIME类型

注册一个MIME类型的呈现提供者

注册一个HTTP过滤器

注册一个HTTP 过滤器

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应用程序通信

BlackBerry 应用程序开发者指南第二卷：高级–第6章访问电话应用程序

第6章访问电话应用程序

BlackBerry 应用程序开发者指南第二卷：高级–第5章 BlackBerry浏览器