|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectnet.rim.device.api.invocation.ListenerInvocationProperties
public class ListenerInvocationProperties
Defines listener invocation properties.
This class is used by a client application to specify how its listener should be called. This class serves as extra parameter
in various addXXXListener() methods.
| Field Summary | ||
|---|---|---|
static int |
INVOCATION_IN_CLIENT_APPLICATION
Constant to indicate that listener should be executed in client application. |
|
static int |
INVOCATION_IN_CLIENT_PROCESS
Constant to indicate that listener should be executed in the client process. |
|
static int |
INVOCATION_IN_PROXY_PROCESS
Constant to indicate that listener should be executed in proxy application. |
|
| Constructor Summary | ||
|---|---|---|
ListenerInvocationProperties()
Creates default properties. |
||
ListenerInvocationProperties(int type)
Creates listener invocation properties based on the invocation type |
||
ListenerInvocationProperties(Application app)
Creates listener invocation properties based on given application. |
||
ListenerInvocationProperties(ApplicationDescriptor descr)
Creates listener invocation properties based on the type and application descriptor. |
||
| Method Summary | ||
|---|---|---|
Application |
getApplication()
|
|
ApplicationDescriptor |
getApplicationDescriptor()
Returns client application descriptor |
|
int |
getType()
Returns invocation type |
|
void |
setApplication(Application app)
|
|
void |
setApplicationDescriptor(ApplicationDescriptor descr)
Sets client application descriptor |
|
void |
setType(int type)
Sets invocation type |
|
| Methods inherited from class java.lang.Object |
|---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
|---|
public static final int INVOCATION_IN_CLIENT_PROCESS
The client application will have to be running in the background to get notified. When the client application exists its listener is automatically unregistered.
Note that when CLIENT_PROCESS type notification is used then the system keeps a weak reference to the given listener object. This means that the client application must store hard reference to the listener to prevent it being garbage collected. Here is sample code how to keep a hard reference from the application:
public class MyApplication extends Application {
private MyListener myListener; // hard reference
public void installListener() {
this.myListener = new MyListener();
API.addListener( this.myListener );
}
}
class MyListener implements Listener {
}
public static final int INVOCATION_IN_CLIENT_APPLICATION
If the client application is not running then it will be started automatically. The listener will remain registered until the application calls unregister or device reboots.
When client application notification is used then the given listener must not store reference to the Application where it
was created. It means that application and listener logic can not be implemented in the same class. This is required to let
the client application exit and clean up process resources. Listener code can access its application by calling the
Application.getApplication() method.
Note that because listener remains registered even after the client application exits, it becomes relatively easy to register the same listener multiple times. To avoid duplicate registrations the listener should implement equals() method and compare the class name. Here is a sample code:
public class MyApplication extends Application {
public void installListener() {
MyListener myListener = new MyListener();
API.addListener( myListener );
enterEventDispatcher();
}
public void beep() {
}
}
class MyListener implements Listener {
public void onEvent() {
MyApplication app = (MyApplication) Application.getApplication(); // access to current application
app.invokeLater( new Runnable() {
public void run() {
beep();
}
} );
}
public boolean equals( Object ob ) {
return ob instanceof MyListener;
}
}
public static final int INVOCATION_IN_PROXY_PROCESS
The proxy application is always running and allocates threads dynamically, so the client application doesn't have to be started each time a listener is called. The listener will remain registered until the application calls unregister.
Similarly to ListenerInvocationProperties.INVOCATION_IN_CLIENT_APPLICATION type, the listener must not store reference to its application. The
listener should also implement equals() method to prevent duplicate registration.
Because the listener is executed in a system process, it means that Application.getApplication() call would not
return client application. Additionally, the client application may not be running at the the time the listener is
executed. This invocation type should be used to perform some basic logic in the listener callback and optionally start the
main client application for user interaction. To start client application call to
ApplicationManager.runApplication(ApplicationDescriptor). Here is a code sample:
public class MyApplication extends UiApplication {
static final long MY_APP_DESCRIPTOR = 0x57114469668376edL; // MY_APP_DESCRIPTOR hash but it MUST be unique for each application
static final long MY_APP_MESSAGE_QUEUE = 0xe2e29c962e9c4214L; // MY_APP_MESSAGE_QUEUE hash but it MUST be unique for each application
public MyApplication() {
// check if the application has been started at least once
RuntimeStore runtimeStore = RuntimeStore.getRuntimeStore();
if( runtimeStore.get( MY_APP_DESCRIPTOR ) == null ) {
// the application started the very first time - store application descriptor in memory
runtimeStore.put( MY_APP_DESCRIPTOR, ApplicationDescriptor.currentApplicationDescriptor() );
// allocate message queue between application and the listener
runtimeStore.put( MY_APP_MESSAGE_QUEUE, new Vector() );
}
installListener();
startProcessingMessages();
enterEventDispatcher();
}
public void installListener() {
MyListener myListener = new MyListener();
API.addListener( myListener );
}
public void startProcessingMessages() {
new Thread( new Runnable() {
public void run() {
RuntimeStore runtimeStore = RuntimeStore.getRuntimeStore();
Vector messageQueue = (Vector) runtimeStore.get( MyApplication.MY_APP_MESSAGE_QUEUE );
while( true ) {
String email = null;
synchronized( messageQueue ) {
if( messageQueue.isEmpty() ) {
messageQueue.wait();
} else {
email = (String) messageQueue.elementAt( 0 );
messageQueue.removeElementAt( 0 );
}
}
if( email != null ) {
Dialog.inform( "Found email '" + email + "'" );
}
}
}
} ).start();
}
}
class MyListener implements Listener {
public void onEvent( String email ) {
RuntimeStore runtimeStore = RuntimeStore.getRuntimeStore();
if( email.endsWith( "@acme.com" ) ) {
// found email, start my application to notify user
ApplicationDescriptor myDescr = (ApplicationDescriptor) runtimeStore.get( MyApplication.MY_APP_DESCRIPTOR );
if( myDescr != null ) {
int processID = ApplicationManager.getApplicationManager().runApplication( myDescr );
if( processID > 0 ) {
Vector messageQueue = (Vector) runtimeStore.get( MyApplication.MY_APP_MESSAGE_QUEUE );
synchronized( messageQueue ) {
messageQueue.addElement( email );
messageQueue.notifyAll();
}
}
}
}
}
public boolean equals( Object ob ) {
return ob instanceof MyListener;
}
}
| Constructor Detail |
|---|
public ListenerInvocationProperties()
By default ListenerInvocationProperties.INVOCATION_IN_CLIENT_PROCESS type of invocation is used.
public ListenerInvocationProperties(ApplicationDescriptor descr)
ListenerInvocationProperties.INVOCATION_IN_CLIENT_APPLICATION meaning that the listener execution would happen in the
client application and if it is not running then it will be started automatically using the given descriptor.
descr - descriptor that defines how to start client applicationpublic ListenerInvocationProperties(Application app)
ListenerInvocationProperties.INVOCATION_IN_CLIENT_PROCESS meaning that the listener execution would happen in the client application process
until it runs.
app - application process where the listener will be calledpublic ListenerInvocationProperties(int type)
type - one of ListenerInvocationProperties.INVOCATION_IN_CLIENT_PROCESS, ListenerInvocationProperties.INVOCATION_IN_PROXY_PROCESS,
ListenerInvocationProperties.INVOCATION_IN_CLIENT_APPLICATION| Method Detail |
|---|
public int getType()
public void setType(int type)
type - new typepublic ApplicationDescriptor getApplicationDescriptor()
public void setApplicationDescriptor(ApplicationDescriptor descr)
public Application getApplication()
public void setApplication(Application app)
app - application where the listener will be executed
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal