net.rim.device.api.invocation
Class ListenerInvocationProperties

java.lang.Object
  extended by net.rim.device.api.invocation.ListenerInvocationProperties

public class ListenerInvocationProperties
extends Object

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.

Since:
BlackBerry API 7.0.0

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

INVOCATION_IN_CLIENT_PROCESS

public static final int INVOCATION_IN_CLIENT_PROCESS
Constant to indicate that listener should be executed in the 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 {
 }
 

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

INVOCATION_IN_CLIENT_APPLICATION

public static final int INVOCATION_IN_CLIENT_APPLICATION
Constant to indicate that listener should be executed 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;
     }
 }
 

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

INVOCATION_IN_PROXY_PROCESS

public static final int INVOCATION_IN_PROXY_PROCESS
Constant to indicate that listener should be executed in proxy application.

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

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0


Constructor Detail

ListenerInvocationProperties

public ListenerInvocationProperties()
Creates default properties.

By default ListenerInvocationProperties.INVOCATION_IN_CLIENT_PROCESS type of invocation is used.

Since:
BlackBerry API 7.0.0

ListenerInvocationProperties

public ListenerInvocationProperties(ApplicationDescriptor descr)
Creates listener invocation properties based on the type and application descriptor. The invocation type will be automatically set to 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.

Parameters:
descr - descriptor that defines how to start client application
Since:
BlackBerry API 7.0.0

ListenerInvocationProperties

public ListenerInvocationProperties(Application app)
Creates listener invocation properties based on given application. The invocation type will be automatically set to ListenerInvocationProperties.INVOCATION_IN_CLIENT_PROCESS meaning that the listener execution would happen in the client application process until it runs.

Parameters:
app - application process where the listener will be called
Since:
BlackBerry API 7.0.0

ListenerInvocationProperties

public ListenerInvocationProperties(int type)
Creates listener invocation properties based on the invocation type

Parameters:
type - one of ListenerInvocationProperties.INVOCATION_IN_CLIENT_PROCESS, ListenerInvocationProperties.INVOCATION_IN_PROXY_PROCESS, ListenerInvocationProperties.INVOCATION_IN_CLIENT_APPLICATION
Since:
BlackBerry API 7.0.0


Method Detail

getType

public int getType()
Returns invocation type

Since:
BlackBerry API 7.0.0

setType

public void setType(int type)
Sets invocation type

Parameters:
type - new type
Since:
BlackBerry API 7.0.0

getApplicationDescriptor

public ApplicationDescriptor getApplicationDescriptor()
Returns client application descriptor

Since:
BlackBerry API 7.0.0

setApplicationDescriptor

public void setApplicationDescriptor(ApplicationDescriptor descr)
Sets client application descriptor

Since:
BlackBerry API 7.0.0

getApplication

public Application getApplication()
Returns:
application where the listener will be executed
Since:
BlackBerry API 7.0.0

setApplication

public void setApplication(Application app)
Parameters:
app - application where the listener will be executed
Since:
BlackBerry API 7.0.0





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