net.rim.blackberry.api.sendmenu
Class SendCommandRepository

java.lang.Object
  extended by net.rim.blackberry.api.sendmenu.SendCommandRepository

public class SendCommandRepository
extends Object

Used to retrieve an array of SendCommand objects that target the applications that are registered with the SendCommandRepository to appear in Send submenus.

The SendCommandRepository class is the entry point to the Send Menu API that is included in this package. Classes in this package, primarily SendCommandRepository, SendCommand, and SendCommandMenu, provide a mechanism for an application to incorporate the Send submenu into the application's menu. When a user selects one of the Send submenu items, the BlackBerry device will launch the target application (one of those registered on the device to appear in the Send menu) with fields prepopulated with the content to be sent, allowing the user to fill out the rest of the information and send the content to a recipient.

A Send submenu can be added to a Menu instance of an application by performing the following actions:

  1. Override the Screen.makeMenu(Menu menu, int instance) method of the application's screen class.
  2. Add a new instance of SendCommandMenu (made of an array of SendCommand instances that are retrieved from the SendCommandRepository class) to the Menu object that is referred as the parameter in the overridden makeMenu(Menu menu, int instance) method of the application's screen class.

For example:

 class MyScreen extends MainScreen 
 {
     protected void makeMenu(Menu menu, int instance) {
         super.makeMenu(menu, instance);
         JSONObject context = new JSONObject();
         try {
             context.put(SendCommandContextKeys.PATH, "/SDCard/BlackBerry/camera/photo.jpg");
         } catch (JSONException e) {
             System.out.println(e.toString());
         }
         SendCommand[] sendCommands = SendCommandRepository.getInstance().get(SendCommand.TYPE_PATH, context, false);
         if (sendCommands != null && sendCommands.length > 0)
             menu.add(new SendCommandMenu(sendCommands, 0, 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 7.0.0

Method Summary
Category: Signed  SendCommandMenu buildMenu(String data, int type, int ordinal, int priority)
          Creates a SendCommandMenu that excludes commands whose applications cannot be opened.
Category: Signed  SendCommandScreen buildScreen(String data, int type)
          Creates a SendCommandScreen that excludes commands whose applications cannot be opened.
Category: Signed  SendCommand[] get(int type, JSONObject commandContext)
          Retrieves an array of SendCommand objects based on the given type of the content and on the content that is specified in the given context, commandContext.
Category: Signed  SendCommand[] get(int type, JSONObject commandContext, boolean includeAll)
          Retrieves an array of SendCommand objects based on the given type of the content and on the content that is specified in the given context, commandContext.
Category: Signed static SendCommandRepository getInstance()
          Retrieves the singleton instance of SendCommandRepository that acts as a factory to provide arrays of SendCommand objects that target supported applications.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Method Detail

getInstance

public static SendCommandRepository getInstance()
Retrieves the singleton instance of SendCommandRepository that acts as a factory to provide arrays of SendCommand objects that target supported applications.

Returns:
The singleton instance SendCommandRepository. This method never returns 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 7.0.0

get

public SendCommand[] get(int type,
                         JSONObject commandContext,
                         boolean includeAll)
Retrieves an array of SendCommand objects based on the given type of the content and on the content that is specified in the given context, commandContext.

The retrieved SendCommand objects are to appear in a SendCommandMenu or in a SendCommandScreen.

The retrieved SendCommand objects target specific applications that support both the given type and the content that is specified in the given context, commandContext.

Parameters:
type - The type of the content. This parameter defines the resulting array of Send commands. The type is either SendCommand.TYPE_TEXT or SendCommand.TYPE_PATH. If SendCommand.TYPE_PATH is the type of the content, then checks are performed to ensure that the file represented by the given path as the content is allowed to be sent.
commandContext - The command's content context data that will be used when the run() method of the SendCommand is invoked. This parameter may contain information such as the path of the file to send or the subject and body of the message to create. The names of keys in key/value pairs in the specified JSONObject context data parameter may be one of SendCommandContextKeys.PATH, SendCommandContextKeys.SUBJECT, or SendCommandContextKeys.TEXT.
includeAll - If true this method returns all commands regardless if their associated applications can be opened, if false this method returns only commands whose associated applications can be opened.
Returns:
An array of SendCommand objects that target the applications that support the given type and the content that is specified in the given context, or null if there are no target applications that are supported by the content and its type.
Throws:
IllegalArgumentException - if one of the following occurs:
  1. The commandContext parameter is null.
  2. Both SendCommandContextKeys.PATH and SendCommandContextKeys.TEXT are specified as keys in the commandContext parameter.
  3. Neither SendCommandContextKeys.PATH or SendCommandContextKeys.TEXT are specified as keys in the commandContext parameter.
  4. A file URL specified in the commandContext parameter under the SendCommandContextKeys.PATH key is a directory (it ends with the slash character '/').
  5. No file-path root exists in the file system for the file-path that is stored as a file URL in the commandContext parameter under the SendCommandContextKeys.PATH key.
  6. The BlackBerry device failed to extract the MIME type from the file URL that is stored in the commandContext parameter under the SendCommandContextKeys.PATH key.
UnsupportedOperationException - if one of the following occurs:
  1. The MIME type extracted from the file URL that is stored in the commandContext parameter under the SendCommandContextKeys.PATH key is for a non-supported media type.
  2. A file specified by a file URL in the commandContext parameter under the SendCommandContextKeys.PATH key is not found in the file system.
  3. A file specified by a file URL in the commandContext parameter under the SendCommandContextKeys.PATH key is an empty file.
  4. A file specified by a file URL in the commandContext parameter under the SendCommandContextKeys.PATH key is a remote file. Sending remote files is not supported.
SendCommandException - if a file specified by a file URL in the commandContext parameter under the SendCommandContextKeys.PATH key represents content that is restricted from being sent from from the device.
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 7.0.0

get

public SendCommand[] get(int type,
                         JSONObject commandContext)
Retrieves an array of SendCommand objects based on the given type of the content and on the content that is specified in the given context, commandContext.

The retrieved SendCommand objects are to appear in a SendCommandMenu or in a SendCommandScreen.

The retrieved SendCommand objects target specific applications that support both the given type and the content that is specified in the given context, commandContext.

Parameters:
type - The type of the content. This parameter defines the resulting array of Send commands. The type is either SendCommand.TYPE_TEXT or SendCommand.TYPE_PATH. If SendCommand.TYPE_PATH is the type of the content, then checks are performed to ensure that the file represented by the given path as the content is allowed to be sent.
commandContext - The content context data that will be used when the corresponding menu item is selected by the user and the command is invoked by the BlackBerry device. This parameter may contain information such as the path of the file to send or the subject and body of the message to create. The names of keys in key/value pairs in the specified JSONObject context data parameter may be one of SendCommandContextKeys.PATH, SendCommandContextKeys.SUBJECT, or SendCommandContextKeys.TEXT.
Returns:
An array of SendCommand that target the applications that support the given type and the content that is specified in the given context, or null if there are no target applications that are supported by the content and its type.
Throws:
IllegalArgumentException - if one of the conditions that are listed for SendCommandRepository.get(int type, JSONObject commandContext, boolean includeAll) occurs.
UnsupportedOperationException - if one of the conditions that are listed for SendCommandRepository.get(int type, JSONObject commandContext, boolean includeAll) occurs.
SendCommandException - if one of the conditions that are listed for SendCommandRepository.get(int type, JSONObject commandContext, boolean includeAll) occurs.
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 7.0.0

buildMenu

public SendCommandMenu buildMenu(String data,
                                 int type,
                                 int ordinal,
                                 int priority)
Creates a SendCommandMenu that excludes commands whose applications cannot be opened.

For the text-type data, the subject will not be populated.

Parameters:
data - The data to use to create the SendCommandMenu, which can be text or a path to a file.
type - The type of the content. This parameter defines the resulting array of Send commands. The type is either SendCommand.TYPE_TEXT or SendCommand.TYPE_PATH.
ordinal - The ordinal of the menu.
priority - The priority of the menu.
Returns:
A SendCommandMenu object with the specified data, type, ordinal, and priority.
Throws:
IllegalArgumentException - if type is not SendCommand.TYPE_TEXT or SendCommand.TYPE_PATH.
NullPointerException - if data 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 7.0.0

buildScreen

public SendCommandScreen buildScreen(String data,
                                     int type)
Creates a SendCommandScreen that excludes commands whose applications cannot be opened.

For the text-type data, the subject will not be populated.

Parameters:
data - The data to use to create the SendCommandScreen, which can be text or a path to a file.
type - The type of the content. This parameter defines the resulting array of Send commands. The type is either SendCommand.TYPE_TEXT or SendCommand.TYPE_PATH.
Returns:
A SendCommandScreen object with the specified data and type.
Throws:
IllegalArgumentException - if type is not SendCommand.TYPE_TEXT or SendCommand.TYPE_PATH.
NullPointerException - if data 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 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