net.rim.blackberry.api.messagelist
Class ApplicationMessageFolderRegistry

java.lang.Object
  extended by net.rim.blackberry.api.messagelist.ApplicationMessageFolderRegistry

public class ApplicationMessageFolderRegistry
extends Object

Registry for application folders. Provides operations to register new application folders, assign icons and menu items for specific message type and statuses.

An application can register multiple folders similar to email such as Inbox, Sent, Deleted, etc. A folder stores application messages in the chronological order. Most graphical message list representations show folder items in the same order from most recent to the oldest. An application message can be added only to one folder, however, it may have various statuses and types. Application folders can not be nested and are represented as a simple collection.

An application folder is uniquely identified by folder ID for a given application. Additionally, folder has name attribute that will be displayed on Folder List screens. If application registers more than one folder then these folders will be grouped with a root element. Application may specify folder root element name.

Messages added to an application folder will be displayed in the global message list. Message element on GUI comprises of icon, date and time, contact and subject attributes. Some message screens may optionally display body attribute, for example, it will be shown on message preview screen. Message icons must be associated with message status and types in order to display icon in the message list. Icon registration is performed for particular message type, for example, application can register one icon for incoming messages and another icon for outgoing messages. Similarly, icon can be associated with message status, e.g. specific icon for new messages and another for opened. An application may use 0 value for both message type and status if it has only one kind of messages. If a new icon is registered for the same message type and status then no updates are triggered for visible messages. However, the new icon will be used in further paint procedures.

Application message can be assigned a number of context menu items. Similar to icon registration, menu items are associated with specific message type and status. For example, incoming message type can have View and Reply actions while outgoing message can have View action only. Menu items are associated with current or provided application descriptor which means that they will be executed in the given application context. If an application is not running at the moment a menu item is selected by user then it will be started automatically. The first registered menu item for a message type will be marked as Default item and it should have a label such as 'Open in XXXApplication'. This menu item is executed when user clicks on a message in the message list. Also the default menu item action is executed from the message preview screen to open the message in the application.

Note that application cannot register context menu items for bulk operations. If user selects multiple messages in the list then the context menu will include the generic operations only, such as Delete, Mark Opened and Mark UnOpened. While the Delete action will be always present in the menu, the Mark XXX operations can be configured through ApplicationMessageFolderRegistry.setBulkMarkOperationsSupport(int, int, boolean, boolean) method call. If user selects a number of messages of different types and chooses one of the Mark XXX operation then affected messages will be only those that support the operation. If none of the selected messages support the Mark XXX action then the corresponding menu item is hidden. These bulk actions do not affect which context menu items are displayed when an individual message is selected. An application cannot set additional application specific context menu items for bulk operations. By default no Mark XXX bulk operations are allowed on application messages.

Application can specify whether folder messages should be merged with the global message list. If folder messages are not merged then they will not be visible in the global message list, however, messages will be searcheable and accessible through the [View Folder] screen. This can be used for Deleted or Junk Messages type folders. The following standard RIM folders are not merged: Phone Calls, Browser Messages, Junk and Deleted email messages. By default folder messages are merged and visible in the global message list.

Neither folders nor their messages are persisted automatically. So, folder registration and populating with messages must be performed each time the phone starts. This also applies to icon and menu items registration.

Collection of messages is always kept in memory even if its application is not running. Hence, its elements should be small java objects to leave memory for other applications. The message collection should be treated as a singleton object. When application is uninstalled then all its folders and message collections are cleaned up.

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

Method Summary
Category: Signed  ApplicationMessageFolder getApplicationFolder(long folderId)
          Retrieves application folder previously registered by folder ID for application specified by given descriptor.
Category: Signed static ApplicationMessageFolderRegistry getInstance()
          Retrieves registry instance.
Category: Signed  String getRootFolderName()
          Returns root folder name used for grouping application folders.
Category: Signed  ApplicationMessageFolder registerFolder(long folderId, String folderName, ReadableList collection)
          Registers an application message folder with folder ID and name.
Category: Signed  ApplicationMessageFolder registerFolder(long folderId, String folderName, ReadableList collection, boolean mergeMessages)
          Registers an application message folder with folder ID and name.
Category: Signed  ApplicationMessageFolder registerFolder(long folderId, String folderName, ReadableList collection, ApplicationFolderIntegrationConfig integrationConfig)
          Registers an application message folder with folder ID and name.
Category: Signed  void registerMessageIcon(int type, int status, ApplicationIcon icon)
          Registers an icon for given message type and status
Category: Signed  void registerMessageMenuItems(int type, int status, ApplicationMenuItem[] menuItems)
          Registers menu items for given message type and status.
Category: Signed  void registerMessageMenuItems(int type, int status, ApplicationMenuItem[] menuItems, ApplicationDescriptor appDescriptor)
          Registers menu items for given message type and status.
Category: Signed  void setBulkMarkOperationsSupport(int type, int status, boolean supportsBulkMarkOpen, boolean supportsBulkMarkUnopened)
          Specifies whether Mark Opened and Mark UnOpened bulk operations are supported for given message type and status.
Category: Signed  void setRootFolderName(String rootName)
          Sets a new root folder name.
Category: Signed  boolean unregisterFolder(long folderId)
          Unregister application folder by its ID.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Method Detail

registerMessageMenuItems

public void registerMessageMenuItems(int type,
                                     int status,
                                     ApplicationMenuItem[] menuItems)
                              throws IllegalArgumentException
Registers menu items for given message type and status. Menu items are associated with the current application, so they will be executed in the current application context. This is a shortcut method to the ApplicationMessageFolderRegistry.registerMessageMenuItems(int, int, ApplicationMenuItem[], ApplicationDescriptor) with ApplicationDescriptor.currentApplicationDescriptor() parameter value.

Parameters:
type - An application-specific message type.
status - An application-specific message status. The lowest 16 bits are reserved for internal use. Refer to ApplicationMessage.Status for the reserved statuses list.
menuItems - The optional menu items that will be available in message context menu. The menu method run(Object) will receive an ApplicationMessage instance.
Throws:
IllegalArgumentException - if menuItems has a length of 0.
NullPointerException - if menuItems is null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

registerMessageIcon

public void registerMessageIcon(int type,
                                int status,
                                ApplicationIcon icon)
Registers an icon for given message type and status

Parameters:
type - An application-specific message type.
status - An application-specific message status. The lowest 16 bits are reserved for internal use. Refer to ApplicationMessage.Status for the reserved statuses list.
icon - A message icon displayed in the global message list.
Throws:
NullPointerException - if icon is null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

registerMessageMenuItems

public void registerMessageMenuItems(int type,
                                     int status,
                                     ApplicationMenuItem[] menuItems,
                                     ApplicationDescriptor appDescriptor)
                              throws IllegalArgumentException
Registers menu items for given message type and status. Application may call this method multiple times for the same message type and menu items will be accumulated. Multiple calls may be required if different application descriptors are responsible for menu item execution.

The first menu item registered will be considered as default one and should be used for opening the message in the application.

Parameters:
type - An application-specific message type.
status - An application-specific message status. The lowest 16 bits are reserved for internal use. Refer to ApplicationMessage.Status for the reserved statuses list.
menuItems - The optional menu items that will be available in message context menu. The menu method run(Object) will receive an ApplicationMessage instance.
appDescriptor - The application descriptor to associate the type with. Menu items will be executed in the given application context.
Throws:
IllegalArgumentException - if the application descriptor specifies a module that is not the current module or menuItems has a length of 0.
NullPointerException - if menuItems is null or appDescriptor is null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

setBulkMarkOperationsSupport

public void setBulkMarkOperationsSupport(int type,
                                         int status,
                                         boolean supportsBulkMarkOpen,
                                         boolean supportsBulkMarkUnopened)
                                  throws IllegalArgumentException
Specifies whether Mark Opened and Mark UnOpened bulk operations are supported for given message type and status. If applicaton supports these actions then user will have the corresponding context menu item for selected messages. If bulk operation is not supported for messages then context menu will not include the Mark action. Note that this affects only bulk operations while application can define any application specific operations on an individual message.

Parameters:
type - An application-specific message type.
status - An application-specific message status.
supportsBulkMarkOpen - Specifies if bulk Mark Open operation is supported for this type of message.
supportsBulkMarkUnopened - Specifies if bulk Mark UnOpen operation is supported for this type of message.
Throws:
IllegalArgumentException - if the application message type and status were not registered previously.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

getInstance

public static ApplicationMessageFolderRegistry getInstance()
Retrieves registry instance.

Returns:
The registry instance.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

registerFolder

public ApplicationMessageFolder registerFolder(long folderId,
                                               String folderName,
                                               ReadableList collection)
                                        throws IllegalArgumentException,
                                               NullPointerException
Registers an application message folder with folder ID and name. Messages added to this folder will be displayed in the global message list. Messages may be cleared up automatically when LowMemory event occurs. Folder name will be displayed in [View Folder] list which allows filtering by folder. This is a shortcut to the register folder method with defaults.

Parameters:
folderId - A unique application folder ID, must be not equal to 0.
folderName - The name of the folder.
collection - A collection of ApplicationMessage elements.
Returns:
The registered application folder.
Throws:
IllegalArgumentException - if one of the following conditions is true:
  • folderId is equal to 0
  • a folder with the same name or ID is already registered
  • folderName has a length of 0
NullPointerException - if folderName is null or collection is null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

registerFolder

public ApplicationMessageFolder registerFolder(long folderId,
                                               String folderName,
                                               ReadableList collection,
                                               boolean mergeMessages)
                                        throws IllegalArgumentException,
                                               NullPointerException
Registers an application message folder with folder ID and name. Messages added to this folder will be displayed in the global message list. Messages may be cleared up automatically when LowMemory event occurs. Folder name will be displayed in [View Folder] list which allows filtering by folder.

Parameters:
folderId - A unique application folder ID, must be not equal to 0.
folderName - The name of the folder.
collection - A collection of ApplicationMessage elements.
mergeMessages - Defines if folder messages should be merged with the global message list. The false value is used for DeletedMessages-type folders so that its messages will not be visible but accessible through other means.
Returns:
The registered application folder.
Throws:
IllegalArgumentException - if one of the following conditions is true:
  • folderId is equal to 0
  • a folder with the same name or ID is already registered
  • folderName has a length of 0
NullPointerException - if folderName is null or collection is null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

registerFolder

public ApplicationMessageFolder registerFolder(long folderId,
                                               String folderName,
                                               ReadableList collection,
                                               ApplicationFolderIntegrationConfig integrationConfig)
                                        throws IllegalArgumentException,
                                               NullPointerException
Registers an application message folder with folder ID and name. Messages added to this folder will be displayed in the global message list. Messages may be cleared up automatically when LowMemory event occurs. Folder name will be displayed in [View Folder] list which allows filtering by folder.

Parameters:
folderId - A unique application folder ID, must be not equal to 0.
folderName - The name of the folder.
collection - A collection of ApplicationMessage elements.
integrationConfig - Defines how folder messages should be integrated.
Returns:
The registered application folder.
Throws:
IllegalArgumentException - if one of the following conditions is true:
  • folderId is equal to 0
  • a folder with the same name or ID is already registered
  • folderName has a length of 0
  • in integrationConfig, Home screen integration is enabled and a UI application is not specified
  • in integrationConfig, the application descriptor that is specified is not for the current application
NullPointerException - if folderName is null or collection is null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 6.0.0

setRootFolderName

public void setRootFolderName(String rootName)
                       throws NullPointerException,
                              IllegalArgumentException
Sets a new root folder name.

The root folder name will be displayed on the [View Folder] dialog if and only if application registered more than one application message folders. Also, if there is an existing folder with the same name as the one you specified, the application name will be placed in parenthesis and appended to your specified folder name. For example, if your specified folder name is Inbox and the application name is ExampleApp, but a folder named Inbox already exists, then your folder name will be set to Inbox (ExampleApp).

Parameters:
rootName - The new name to assign.
Throws:
NullPointerException - if rootName is null.
IllegalArgumentException - if rootName has a length of 0.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

getRootFolderName

public String getRootFolderName()
Returns root folder name used for grouping application folders.

Returns:
The root folder name if the application provided one, null otherwise.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

unregisterFolder

public boolean unregisterFolder(long folderId)
                         throws IllegalArgumentException
Unregister application folder by its ID.

If you had set a root folder name and you unregistered the last folder for your application using this method, the root folder name will be lost. You can reassign the root folder name using the setRootFolderName method.

Parameters:
folderId - The folder ID provided during folder registration.
Returns:
true if the folder was successfully unregistered, false otherwise.
Throws:
IllegalArgumentException - if folderId is equal to 0.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

getApplicationFolder

public ApplicationMessageFolder getApplicationFolder(long folderId)
Retrieves application folder previously registered by folder ID for application specified by given descriptor.

Parameters:
folderId - The folder ID provided during folder registration.
Returns:
The application folder if previously registered, null otherwise.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.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