net.rim.device.api.command
Class CommandMetadata

java.lang.Object
  net.rim.device.api.command.CommandMetadata

public class CommandMetadata
extends Object

Encapsulates metadata associated with a CommandHandler.

The only required piece of metadata for a command is the command's identifier, which is set when the CommandMetadata object is constructed and is stored in the CommandMetadata.COMMAND_ID field.

For more information about using this class, see the package overview.

Since:

BlackBerry API 6.0.0

Field Summary
static String	ALIGNMENT The alignment used by the command.
static String	BITMAP_ICON The bitmap icon of the command.
static String	CLASSNAME The command's class name.
static String	COMMAND_ID The identifier of the command.
static String	LABEL The label of the command.
static String	LABEL_ORIENTATION The orientation of the command's label.
static String	LABEL_RESOURCE_ID The identifier of the command's label.
static String	PREDEFINED_ICON The predefined icon of the command.
static String	RESOURCE_BUNDLE_NAME The name of the resource bundle used by the command.
static String	THEMED_ICON The themed icon of the command.

Constructor Summary

CommandMetadata(String commandId)
Constructs a new CommandMetadata instance.

CommandMetadata(CommandMetadata metadata)
Constructs a new CommandMetadata instance based on an existing CommandMetadata instance.

Method Summary
void	addCommandCategory(String commandCategory) Adds a command category to the command categories for the associated command.
void	addContextCategory(String contextCategory) Adds a context category to the context categories for the associated command.
boolean	getBoolean(String name) Retrieves the value associated with the specified attribute name as a boolean value.
String	getClassname() Retrieves the command's class name.
CategoryCollection	getCommandCategories() Retrieves the command categories for the associated command.
String	getCommandId() Retrieves the command's identifier (the value stored in CommandMetadata.COMMAND_ID).
CategoryCollection	getContextCategories() Retrieves the context categories for the associated command.
ExecutionContextEnum	getExecutionContext() Retrieves the execution context of the associated command.
int	getInt(String name) Retrieves the value associated with the specified attribute name as an int value.
long	getLong(String name) Retrieves the value associated with the specified attribute name as a long value.
String	getResourceBundleName() Retrieves the name of the command's resource bundle (the value stored in CommandMetadata.RESOURCE_BUNDLE_NAME).
String	getString(String name) Retrieves the value associated with the specified attribute name as a string.
boolean	has(String name) Determines if this metadata instance contains a specified attribute name.
boolean	optBoolean(String name) Retrieves the value associated with the specified attribute name as a boolean value.
boolean	optBoolean(String name, boolean defaultValue) Retrieves the value associated with the specified attribute name as a boolean value.
int	optInt(String name) Retrieves the value associated with the specified attribute name as an int value.
int	optInt(String name, int defaultValue) Retrieves the value associated with the specified attribute name as an int value.
long	optLong(String name) Retrieves the value associated with the specified attribute name as a long value.
long	optLong(String name, long defaultValue) Retrieves the value associated with the specified attribute name as a long value.
String	optString(String name) Retrieves the value associated with the specified attribute name as a string.
String	optString(String name, String defaultValue) Retrieves the value associated with the specified attribute name as a string.
void	set(String name, boolean value) Stores an attribute name and boolean value in this metadata instance.
void	set(String name, int value) Stores an attribute name and int value in this metadata instance.
void	set(String name, String value) Stores an attribute name and string value in this metadata instance.
void	set(String name, long value) Stores an attribute name and long value in this metadata instance.
void	setClassname(String classname) Sets the class name of the command.
void	setCommandCategories(CategoryCollection commandCategories) Sets the command categories for the associated command.
void	setContextCategories(CategoryCollection contextCategories) Sets the context categories for the associated command.
void	setExecutionContext(ExecutionContextEnum executionContext) Sets the execution context of the associated command.
void	setResourceBundleName(String resourceBundleName) Sets the name of the command's resource bundle (the value stored in CommandMetadata.RESOURCE_BUNDLE_NAME).
String	toString() Retrieves a string representation of this metadata instance.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

COMMAND_ID

public static final String COMMAND_ID

The identifier of the command.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

CLASSNAME

public static final String CLASSNAME

The command's class name.

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

RESOURCE_BUNDLE_NAME

public static final String RESOURCE_BUNDLE_NAME

The name of the resource bundle used by the command.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

LABEL_RESOURCE_ID

public static final String LABEL_RESOURCE_ID

The identifier of the command's label.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

LABEL

public static final String LABEL

The label of the command.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

LABEL_ORIENTATION

public static final String LABEL_ORIENTATION

The orientation of the command's label.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

THEMED_ICON

public static final String THEMED_ICON

The themed icon of the command.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

PREDEFINED_ICON

public static final String PREDEFINED_ICON

The predefined icon of the command.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

ALIGNMENT

public static final String ALIGNMENT

The alignment used by the command.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

BITMAP_ICON

public static final String BITMAP_ICON

The bitmap icon of the command.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

Constructor Detail

CommandMetadata

public CommandMetadata(String commandId)

Constructs a new CommandMetadata instance.

Parameters:

commandId - The identifier of the command that this CommandMetadata instance is associated with.

Since:

BlackBerry API 6.0.0

CommandMetadata

public CommandMetadata(CommandMetadata metadata)

Constructs a new CommandMetadata instance based on an existing CommandMetadata instance.

This constructor performs a shallow copy of the metadata of the specified CommandMetadata, except for the command categories and context categories, each of which are deep copied.

Parameters:

metadata - The CommandMetadata instance to clone.

Since:

BlackBerry API 6.0.0

Method Detail

getCommandId

public String getCommandId()

Retrieves the command's identifier (the value stored in CommandMetadata.COMMAND_ID).

Returns:

The command's identifier.

Since:

BlackBerry API 6.0.0

getClassname

public String getClassname()

Retrieves the command's class name.

Returns:

The command's class name.

Since:

BlackBerry API 6.0.0

setClassname

public void setClassname(String classname)

Sets the class name of the command.

Parameters:

classname - The command's class name.

Since:

BlackBerry API 6.0.0

getResourceBundleName

public String getResourceBundleName()

Retrieves the name of the command's resource bundle (the value stored in CommandMetadata.RESOURCE_BUNDLE_NAME).

Returns:

The name of the resource bundle.

Since:

BlackBerry API 6.0.0

setResourceBundleName

public void setResourceBundleName(String resourceBundleName)

Sets the name of the command's resource bundle (the value stored in CommandMetadata.RESOURCE_BUNDLE_NAME).

Parameters:

resourceBundleName - The name of the resource bundle.

Since:

BlackBerry API 6.0.0

getExecutionContext

public ExecutionContextEnum getExecutionContext()

Retrieves the execution context of the associated command.

Returns:

The execution context.

See Also:

CommandMetadata.setExecutionContext(net.rim.device.api.command.ExecutionContextEnum)

Since:

BlackBerry API 6.0.0

setExecutionContext

public void setExecutionContext(ExecutionContextEnum executionContext)

Sets the execution context of the associated command.

The value of the execution context instructs the command registrar to execute the command in an execution context other than the current thread (for example, in the process that registered the command).

Parameters:

executionContext - The execution context.

Since:

BlackBerry API 6.0.0

getCommandCategories

public CategoryCollection getCommandCategories()

Retrieves the command categories for the associated command.

Returns:

The command categories. This method never returns null. If no command categories have been set for the associated command, this method returns a NullCategoryCollection singleton instance.

Since:

BlackBerry API 6.0.0

setCommandCategories

public void setCommandCategories(CategoryCollection commandCategories)

Sets the command categories for the associated command.

Parameters:

commandCategories - The command categories. If null, this method sets the command categories to a NullCategoryCollection singleton instance.

Since:

BlackBerry API 6.0.0

addCommandCategory

public void addCommandCategory(String commandCategory)

Adds a command category to the command categories for the associated command.

Parameters:

commandCategory - The command category to add.

Since:

BlackBerry API 6.0.0

getContextCategories

public CategoryCollection getContextCategories()

Retrieves the context categories for the associated command.

Returns:

The context categories. This method never returns null. If no context categories have been set for the associated command, this method returns a NullCategoryCollection singleton instance.

Since:

BlackBerry API 6.0.0

setContextCategories

public void setContextCategories(CategoryCollection contextCategories)

Sets the context categories for the associated command.

Parameters:

contextCategories - The context categories. If null, this method sets the context categories to a NullCategoryCollection singleton instance.

Since:

BlackBerry API 6.0.0

addContextCategory

public void addContextCategory(String contextCategory)

Adds a context category to the context categories for the associated command.

Parameters:

contextCategory - The context category to add.

Since:

BlackBerry API 6.0.0

has

public boolean has(String name)

Determines if this metadata instance contains a specified attribute name.

Parameters:

name - The metadata attribute name to check.

Returns:

true if this metadata instance contains the specified name, false otherwise.

Since:

BlackBerry API 6.0.0

set

public void set(String name,
                String value)

Stores an attribute name and string value in this metadata instance.

Parameters:

name - The name of the attribute.

value - The value of the attribute.

Since:

BlackBerry API 6.0.0

getString

public String getString(String name)
                 throws CommandMetadataException

Retrieves the value associated with the specified attribute name as a string.

Parameters:

name - The name of the attribute.

Returns:

The value of the attribute.

Throws:

CommandMetadataException - if the value associated with name is not a string.

NonExistentAttributeException - if an attribute with the specified name does not exist in this metadata instance.

Since:

BlackBerry API 6.0.0

optString

public String optString(String name)

Retrieves the value associated with the specified attribute name as a string.

Parameters:

name - The name of the attribute.

Returns:

The value of the attribute, or null if an attribute with the specified name does not exist in this metadata instance.

Since:

BlackBerry API 6.0.0

optString

public String optString(String name,
                        String defaultValue)

Retrieves the value associated with the specified attribute name as a string.

Parameters:

name - The name of the attribute.

defaultValue - The default value of the attribute.

Returns:

The value of the attribute, or defaultValue if an attribute with the specified name does not exist in this metadata instance.

Since:

BlackBerry API 6.0.0

set

public void set(String name,
                long value)

Stores an attribute name and long value in this metadata instance.

Parameters:

name - The name of the attribute.

value - The value of the attribute.

Since:

BlackBerry API 6.0.0

getLong

public long getLong(String name)
             throws CommandMetadataException

Retrieves the value associated with the specified attribute name as a long value.

Parameters:

name - The name of the attribute.

Returns:

The value of the attribute.

Throws:

CommandMetadataException - if name is not a long value.

NonExistentAttributeException - if an attribute with the specified name does not exist in this metadata instance.

Since:

BlackBerry API 6.0.0

optLong

public long optLong(String name,
                    long defaultValue)

Retrieves the value associated with the specified attribute name as a long value.

Parameters:

name - The name of the attribute.

defaultValue - The default value of the attribute.

Returns:

The value of the attribute, or defaultValue if an attribute with the specified name does not exist in this metadata instance.

Since:

BlackBerry API 6.0.0

optLong

public long optLong(String name)

Retrieves the value associated with the specified attribute name as a long value.

Parameters:

name - The name of the attribute.

Returns:

The value of the attribute, or null if an attribute with the specified name does not exist in this metadata instance.

Since:

BlackBerry API 6.0.0

set

public void set(String name,
                int value)

Stores an attribute name and int value in this metadata instance.

Parameters:

name - The name of the attribute.

value - The value of the attribute.

Since:

BlackBerry API 6.0.0

getInt

public int getInt(String name)
           throws CommandMetadataException

Retrieves the value associated with the specified attribute name as an int value.

Parameters:

name - The name of the attribute.

Returns:

The value of the attribute.

Throws:

CommandMetadataException - if name is not an int value.

NonExistentAttributeException - if an attribute with the specified name does not exist in this metadata instance.

Since:

BlackBerry API 6.0.0

optInt

public int optInt(String name,
                  int defaultValue)

Retrieves the value associated with the specified attribute name as an int value.

Parameters:

name - The name of the attribute.

defaultValue - The default value of the attribute.

Returns:

The value of the attribute, or defaultValue if an attribute with the specified name does not exist in this metadata instance.

Since:

BlackBerry API 6.0.0

optInt

public int optInt(String name)

Retrieves the value associated with the specified attribute name as an int value.

Parameters:

name - The name of the attribute.

Returns:

The value of the attribute, or null if an attribute with the specified name does not exist in this metadata instance.

Since:

BlackBerry API 6.0.0

set

public void set(String name,
                boolean value)

Stores an attribute name and boolean value in this metadata instance.

Parameters:

name - The name of the attribute.

value - The value of the attribute.

Since:

BlackBerry API 6.0.0

getBoolean

public boolean getBoolean(String name)
                   throws CommandMetadataException

Retrieves the value associated with the specified attribute name as a boolean value.

Parameters:

name - The name of the attribute.

Returns:

The value of the attribute.

Throws:

CommandMetadataException - if name is not a boolean value.

NonExistentAttributeException - if an attribute with the specified name does not exist in this metadata instance.

Since:

BlackBerry API 6.0.0

optBoolean

public boolean optBoolean(String name,
                          boolean defaultValue)

Retrieves the value associated with the specified attribute name as a boolean value.

Parameters:

name - The name of the attribute.

defaultValue - The default value of the attribute.

Returns:

The value of the attribute, or defaultValue if an attribute with the specified name does not exist in this metadata instance.

Since:

BlackBerry API 6.0.0

optBoolean

public boolean optBoolean(String name)

Retrieves the value associated with the specified attribute name as a boolean value.

Parameters:

name - The name of the attribute.

Returns:

The value of the attribute, or false if an attribute with the specified name does not exist in this metadata instance.

Since:

BlackBerry API 6.0.0

toString

public String toString()

Retrieves a string representation of this metadata instance.

Overrides:

toString in class Object

Returns:

A string representation of this metadata instance.

Since:

BlackBerry API 6.0.0