net.rim.blackberry.api.sendmenu.SendCommand
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
public abstract class SendCommand
Stores all of the information needed to send data from the BlackBerry device
at a later time, when the user selects a corresponding SendCommandMenuItem
in a SendCommandMenu or a SendCommandScreen.
The SendCommand class is similar to the
Runnable interface in that it defines a generic "command"
that can be executed by calling the SendCommand.run() method at a later time.
Instances of SendCommand are bound to a specific context.
For example, to send file A and file B requires distinct instances of
SendCommand because the files’ paths are stored in the context
objects. A SendCommand object also provides the ability to
store meta-information about the command, including the menu item label (see
SendCommand.getDisplayName()) and the maximum length of values in the context
object (see SendCommand.getMaxContextStringLength(String key)).
The attributes of a SendCommand are specified in the
constructor and are immutable thereafter. So, a SendCommand
object is a "read-only" object.
There are two constants in this class that define the known types of
SendCommand objects: SendCommand.TYPE_PATH and SendCommand.TYPE_TEXT.
SendCommand of the TYPE_PATH type is
designed for sending files from the local file system. SendCommand of the TYPE_TEXT type is
designed for sending text strings, such as in an email or BlackBerry
Messenger (BBM) message. An application can create its own custom SendCommand and
SendCommandMenuItem objects and include the created items in the
application's SendCommandMenu. The SendCommand
objects that an application creates cannot be stored in the
SendCommandRepository.
| Field Summary | ||
|---|---|---|
|
static int |
TYPE_PATH
Type of content to be sent: a file on the device's file system specified by a path. |
|
static int |
TYPE_TEXT
Type of content to be sent: a text string. |
| Constructor Summary | ||
|---|---|---|
|
SendCommand(String id,
int type,
JSONObject context,
StringProvider displayName)
Constructs a new SendCommand instance with the specified
values. |
|
| Method Summary | ||
|---|---|---|
|
JSONObject |
getContext()
Returns the content context object of this command. |
|
StringProvider |
getDisplayName()
Returns the display name of this command to be displayed in the Send menu for the corresponding menu item. |
|
String |
getId()
Returns this command's ID, which is the globally-unique identifier of this SendCommand. |
|
int |
getMaxContextStringLength(String key)
Returns the maximum length of the string value of the specified key among key/value pairs in the JSONObject context object for this
SendCommand. |
|
SendCommandContextFilter |
getSendCommandContextFilter()
Returns the filter for this command's context that is used by the SendCommand.run() method. |
|
int |
getType()
Returns the type of this SendCommand. |
|
boolean |
isAllowed()
Indicates whether the action that is associated with this SendCommand is allowed by the system in the specific
circumstances. |
|
boolean |
isSupported()
Indicates whether an application targeted by this SendCommand can be opened. |
|
abstract void |
run()
Executes this SendCommand with the context that is returned
from SendCommand.getContext(). |
|
void |
setSendCommandContextFilter(SendCommandContextFilter filter)
Sets the filter for the command's context to be used by the SendCommand.run() method. |
| Methods inherited from class java.lang.Object |
|---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
|---|
public static final int TYPE_TEXT
public static final int TYPE_PATH
| Constructor Detail |
|---|
public SendCommand(String id,
int type,
JSONObject context,
StringProvider displayName)
SendCommand instance with the specified
values.
The values are returned by the corresponding get methods
in this class. Refer to those methods’ specifications below for the
semantics of the values.
id - The command ID, which is the globally-unique identifier of this
SendCommand. This value is used to identify the action that
is to be executed by the SendCommand.type - The command type. It may be assigned the value of
SendCommand.TYPE_PATH or SendCommand.TYPE_TEXT, or any other arbitrary value.
This parameter is not checked for validity. In particular, checks for
equality to the TYPE_ constants that are defined in this class are
not performed.context - The content context data of the
SendCommand. This data is used when the corresponding menu
item is selected by the user and the SendCommand is executed
by the system. This parameter may contain information such as the path
of the file to send or the subject and body of the message to create.
A copy of the specified JSONObject context data parameter is
stored internally for use. The names of keys in key/value pairs in the
specified JSONObject context data parameter can be one of
SendCommandContextKeys.PATH, SendCommandContextKeys.SUBJECT,
or SendCommandContextKeys.TEXT.displayName - The display name of the SendCommand.
NullPointerException - if either id or
context is null.
IllegalArgumentException - if context.toString() is
null, context failed to create a copy of itself,
or the length of id is 0 (that is, if
id.length() == 0 is true).| Method Detail |
|---|
public boolean isAllowed()
SendCommand is allowed by the system in the specific
circumstances.
If the SendCommand is of TYPE_TEXT, then
this method checks to ensure that the current process is allowed to send
text to the target application. If the SendCommand is of
TYPE_PATH, then this method checks to ensure that the target
application is allowed to access the file that is specified by the path.
true if the action is allowed, false
otherwise.public StringProvider getDisplayName()
The method returns a StringProvider instead of a
String so that this string may be localized into the current
locale that is used by the application.
public String getId()
SendCommand.
This ID is used to identify the action that is to be executed by this
command. Its value has no semantics but may be used by applications to
"filter out" specific SendCommand objects that are not
desired. For example, if an application wanted to exclude
BlackBerry Messenger from the Send menu, the application could filter out
commands with the "bbm" ID. The actual string values are not documented
anywhere but must be discovered by experimentation.
null.public JSONObject getContext()
The returned object is a copy of the internally-stored
content context object, in form of a JSONObject instance,
that is used when the corresponding SendCommandMenuItem is
selected by the user and this SendCommand is executed (its
SendCommand.run() method is invoked by the system).
null if the
context object has an incorrect structure.public int getMaxContextStringLength(String key)
JSONObject context object for this
SendCommand.
For example, this method can be used by the target application to
specify that the body of a text message may not exceed a specific number
of characters. The predefined keys are defined in the
SendCommandContextKeys class, but any string value may be
specified.
If the JSONObject context data for this
SendCommand has a string value with a length that exceeds
the length returned by this method, and the SendCommand.run() method is
invoked, then the behaviour of run() is undefined;
in all likelihood, the value is to be truncated by run(). An
application can register a listener by using the
SendCommand.setSendCommandContextFilter(SendCommandContextFilter filter)
method of this class. By using this method, the application can provide a
more intelligently shortened string for those string values that exceed
the maximum allowed length.
key - The context key whose maximum string length to return. This
value is one of the keys in key/value pairs of the
JSONObject context object of this SendCommand.
It can be one of the predefined keys in the
SendCommandContextKeys class, or any string value defined as
a key instead. It may be null.
SendCommand. If the specified
key is not recognized, the specified key is null, or the
specified key has no known maximum length, then this method returns a
negative value.public int getType()
SendCommand.
The type that is returned by this method is the value that was
provided to the constructor. It may be SendCommand.TYPE_PATH or
SendCommand.TYPE_TEXT, or any other arbitrary value assigned.
public SendCommandContextFilter getSendCommandContextFilter()
SendCommand.run() method.
null if no filter has been set previously or if the
previously set filter has been removed by invoking
setSendCommandContextFilter( null ).SendCommand.setSendCommandContextFilter(SendCommandContextFilter filter)public void setSendCommandContextFilter(SendCommandContextFilter filter)
SendCommand.run() method.
By setting a filter, an application can adjust or modify the
command's content context, which is stored in the form of a
JSONObject instance, prior to it actually being used in the
run() method. The primary use case for a filter is to provide
a more intelligently shortened string for those string values in the
context object that exceed the maximum allowed length.
filter - The filter to set. If this parameter is null,
then the previously set filter is removed, if any filter was set.
Otherwise, the previously set filter is replaced with the specified
filter.SendCommand.getSendCommandContextFilter(),
SendCommand.run()public boolean isSupported()
SendCommand can be opened.
This method returns a boolean value indicating whether invoking the
SendCommand.run() method with the context that was provided to the
constructor is supported. If this method returns false, then
it is guaranteed that run() will throw a
SendCommandException.
Applications may choose to omit unsupported commands from the Send
menu. A SendCommand may be unsupported for many reasons,
including path-type commands attempting to send file that do not exist or
are forward-locked.
true if the SendCommand can open the
application, false otherwise.
public abstract void run()
throws SendCommandException
SendCommand with the context that is returned
from SendCommand.getContext().
Before actually using the context object, the listener that is
registered with #setSendCommandContextFilter() is notified to
potentially modify the context object, especially if the application
should provide shorter strings for those string values that exceed the
maximum allowed length.
The real work of this method runs in the target application’s process space and not the process space of the calling application. This method returns immediately and does not wait for the target application to complete the request.
SendCommandException - if an error occurs while executing this
SendCommand.SendCommand.setSendCommandContextFilter(SendCommandContextFilter filter)
|
|||||||||
| 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