javax.microedition.content
Interface ContentHandler

All Known Subinterfaces:

ContentHandlerServer

public interface ContentHandler

A ContentHandler provides the details of a content handler registration. Each ContentHandler contains the ID, content types, suffixes, actions, and action names. It provides the ID, authority, and application name and version of the content handler. The values are set when the content handler is registered. ContentHandler instances are immutable and thread safe. Content handlers can only be changed by re-registering which returns a new ContentHandler instance. The registered content handlers can be queried using the query methods of Registry.

Content Types

For the purposes of this API, content types are simple opaque strings that are NOT case-sensitive. All comparisons are performed using case-insensitive string comparisons. By convention, the UNIVERSAL_TYPE is used to indicate any type. A content handler that can support any type of content should include it as one of types when it is registered. Any application can get the list of universal handlers with a query for the UNIVERSAL_TYPE. Handlers with this type are only returned by Registry.findHandler or Registry.forType if the type requested is equal to UNIVERSAL_TYPE.

The most common content types are MIME types. RFC-2046 defines the Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. It defines the general structure of the MIME media typing system and defines an initial set of media types. RFC-2048 describes the specific IANA registration procedures for MIME-related facilities. Other strings may be used as content types, but only if the type system semantics are well defined. An example of where the type system semantics are well defined is in the XML messaging schema.

Suffixes

A content handler can declare a set of suffixes that identify content it can handle based on the syntax of a URL. The suffix is a case-insensitive string that includes punctuation, for example ".png". For some URLs and content storage mechanisms, such as file systems, the content type is not readily available. To accommodate this, a mapping can be used to associate URL suffixes with content handlers. The common practice in file systems is to map filename extensions to content types. For example, a file ending in .png can be identified as content type image/png. This mapping is used if the content access mechanism does not support content typing or if the content type is not available from the content. For the http protocol, that supports a mechanism to identify the content type, the suffix matching MUST be used to identify content handlers if the type is not defined for a particular URL. RFC 2396 - Uniform Resource Identifiers (URI): Generic Syntax describes the syntax of URI's and the path component. Suffix matching consists of comparing each of the registered suffixes with the last n characters of the path component of the URL, where n is the length of the suffix. The comparison is case-insensitive and is done using the equivalent of java.lang.String.regionMatches. If multiple suffixes would match, the longest suffix that matches is used.

Actions

Each content handler registers a set of actions it supports. Actions are Java strings representing semantic functions the content handler can perform on every content type and suffix registered. Actions are case-sensitive strings. The set of actions is extensible but applications should choose from the following actions when appropriate: open, edit, new, send, save, execute, select, delete, remove, install, install_only, print, and stop.

The content handler application should provide localized action names for each action. The action names are used by applications that need to present the possible actions to users in locale appropriate terminology. A mapping for each action to action name should be created for each locale using the ActionNameMap.ActionNameMap method. The action name maps for all the locales supported by the content handler MUST be included when the content handler is registered. The attribute Microedition-Handler-<n>-<locale> is used to declare action names in the application packaging.

Locale Strings

A locale string MUST include a language code, and may include a country code and a variant. The values are separated by a delimiter defined by the Java runtime environment. For MIDP, locale strings follow the definition of the system property microedition.locale and the delimiter MUST be a hyphen ("-" = U+002D). The values for the language, country code and variant are not validated.

Application developers should refer to ISO-639-1 for language codes and to ISO-3166-1 for country codes.

RIM Implementation Notes

IDs for RIM-registered content handlers can be found in the BlackBerryContentHandler class.

Since:

BlackBerry API 4.3.0

Field Summary
static String	ACTION_DELETE Action to delete the content and release resources it may have been consuming if appropriate.
static String	ACTION_EDIT Action to edit the content.
static String	ACTION_EXECUTE Action to execute the content.
static String	ACTION_INSTALL Action to install the content on the device.
static String	ACTION_INSTALL_ONLY Action to only install the content on the device with user interaction limited to the minimum.
static String	ACTION_NEW Action to create new content.
static String	ACTION_OPEN Action to open content.
static String	ACTION_PRINT Action to print the content.
static String	ACTION_REMOVE Action to remove the content from any list or directory maintained by the content handler.
static String	ACTION_SAVE Action to save the content.
static String	ACTION_SELECT Action to select a value from the content, usually with user input, and return its value.
static String	ACTION_SEND Action to send the content via email or messaging.
static String	ACTION_STOP Action to request a content handler to stop processing the content identified by the URL, ID, and arguments.
static String	UNIVERSAL_TYPE The universal type; a handler supporting this type can handle any type of content.

Method Summary
String	getAction(int index) Gets the action supported by the content handler at the specified index.
int	getActionCount() Gets the number of actions supported by the content handler.
ActionNameMap	getActionNameMap() Gets the mapping of actions to action names for the current locale supported by this content handler.
ActionNameMap	getActionNameMap(int index) Gets the ActionNameMap supported by the content handler at the specified index.
ActionNameMap	getActionNameMap(String locale) Gets the mapping of actions to action names for the requested locale supported by this content handler.
int	getActionNameMapCount() Gets the number of action name maps supported by the content handler.
String	getAppName() Gets the user-friendly application name of this content handler.
String	getAuthority() Gets the authority that authenticated this application.
String	getID() Gets the content handler application ID.
String	getSuffix(int index) Gets the suffix supported by the content handler at the specified index.
int	getSuffixCount() Gets the number of suffixes supported by the content handler.
String	getType(int index) Gets the type supported by the content handler at the specified index.
int	getTypeCount() Gets the number of types supported by the content handler.
String	getVersion() Gets the version of this content handler.
boolean	hasAction(String action) Determines if an action is supported by the content handler.
boolean	hasSuffix(String suffix) Determines if a suffix is supported by the content handler.
boolean	hasType(String type) Determines if a type is supported by the content handler.

Field Detail

ACTION_EDIT

static final String ACTION_EDIT

Action to edit the content.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

ACTION_EXECUTE

static final String ACTION_EXECUTE

Action to execute the content.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

ACTION_INSTALL

static final String ACTION_INSTALL

Action to install the content on the device.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

ACTION_NEW

static final String ACTION_NEW

Action to create new content.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

ACTION_OPEN

static final String ACTION_OPEN

Action to open content.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

ACTION_PRINT

static final String ACTION_PRINT

Action to print the content.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

ACTION_SAVE

static final String ACTION_SAVE

Action to save the content.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

ACTION_SELECT

static final String ACTION_SELECT

Action to select a value from the content, usually with user input, and return its value. For example, if the content were a URL of an address book, then the user would be asked to choose an entry or entries to return. The format of the return value depends on the content handler and the content, but if appropriate it should take the form of a URL.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

ACTION_SEND

static final String ACTION_SEND

Action to send the content via email or messaging. Note: Handlers registered with this action, an ActionNameMap and with image or video mime types will have dialog buttons and/or menu items added when viewing files of the specified type(s) in the camera application, video recorder screen or file explorer application. These action items will invoke the registered handler which can then handle the content in an appropriate manner.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

ACTION_STOP

static final String ACTION_STOP

Action to request a content handler to stop processing the content identified by the URL, ID, and arguments. If stopping a previous request, these values should match the corresponding values in that request.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

ACTION_DELETE

static final String ACTION_DELETE

Action to delete the content and release resources it may have been consuming if appropriate. The content handler should be careful not to delete content that is indispensable to the user without confirmation.

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

ACTION_INSTALL_ONLY

static final String ACTION_INSTALL_ONLY

Action to only install the content on the device with user interaction limited to the minimum.

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

ACTION_REMOVE

static final String ACTION_REMOVE

Action to remove the content from any list or directory maintained by the content handler. The content may be deleted depending on the nature of the content handler and the content. Compare with ContentHandler.ACTION_DELETE.

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

UNIVERSAL_TYPE

static final String UNIVERSAL_TYPE

The universal type; a handler supporting this type can handle any type of content.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

Method Detail

getID

String getID()

Gets the content handler application ID. The ID uniquely identifies the content handler with the value provided to the register method, if one was supplied, otherwise a unique ID. This information has been authenticated only if getAuthority is non-null.

Returns:

the ID; MUST NOT be null

Since:

BlackBerry API 4.3.0

getType

String getType(int index)

Gets the type supported by the content handler at the specified index. The type returned for each index must be the equal to the type at the same index in the types array passed to Registry.register.

Parameters:

index - the index of the type

Returns:

the type at the specified index

Throws:

IndexOutOfBoundsException - if index is less than zero or greater than or equal to the value of the getTypeCount method.

Since:

BlackBerry API 4.3.0

getTypeCount

int getTypeCount()

Gets the number of types supported by the content handler. The number of types must be equal to the length of the array of types passed to Registry.register.

Returns:

the number of types

Since:

BlackBerry API 4.3.0

hasType

boolean hasType(String type)

Determines if a type is supported by the content handler.

Parameters:

type - the type to check for

Returns:

true if the type is supported; false otherwise

Throws:

NullPointerException - if type is null

Since:

BlackBerry API 4.3.0

getSuffix

String getSuffix(int index)

Gets the suffix supported by the content handler at the specified index. The suffix returned for each index must be the equal to the suffix at the same index in the suffixes array passed to Registry.register.

Parameters:

index - the index of the suffix

Returns:

the suffix at the specified index

Throws:

IndexOutOfBoundsException - if index is less than zero or greater than or equal to the value of the ContentHandler.getSuffixCount() method.

Since:

BlackBerry API 4.3.0

getSuffixCount

int getSuffixCount()

Gets the number of suffixes supported by the content handler. The number of suffixes must be equal to the length of the array of suffixes passed to Registry.register.

Returns:

the number of suffixes

Since:

BlackBerry API 4.3.0

hasSuffix

boolean hasSuffix(String suffix)

Determines if a suffix is supported by the content handler.

Parameters:

suffix - the suffix to check for

Returns:

true if the suffix is supported; false otherwise

Throws:

NullPointerException - if suffix is null

Since:

BlackBerry API 4.3.0

getAction

String getAction(int index)

Gets the action supported by the content handler at the specified index. The action returned for each index must be the equal to the action at the same index in the actions array passed to Registry.register.

Parameters:

index - the index of the action

Returns:

the action at the specified index

Throws:

IndexOutOfBoundsException - if index is less than zero or greater than or equal to the value of the getActionCount method.

Since:

BlackBerry API 4.3.0

getActionCount

int getActionCount()

Gets the number of actions supported by the content handler. The number of actions must be equal to the length of the array of actions passed to Registry.register.

Returns:

the number of actions

Since:

BlackBerry API 4.3.0

hasAction

boolean hasAction(String action)

Determines if an action is supported by the content handler.

Parameters:

action - the action to check for

Returns:

true if the action is supported; false otherwise

Throws:

NullPointerException - if action is null

Since:

BlackBerry API 4.3.0

getActionNameMap

ActionNameMap getActionNameMap()

Gets the mapping of actions to action names for the current locale supported by this content handler. The behavior is the same as invoking getActionNameMap(String) with the current locale.

Returns:

an ActionNameMap; if there is no map available for the current locale or if the locale is null or empty, then it MUST be null

Since:

BlackBerry API 4.3.0

getActionNameMap

ActionNameMap getActionNameMap(String locale)

Gets the mapping of actions to action names for the requested locale supported by this content handler. The locale is matched against the available ActionNameMaps. If a match is found it is used. If an exact match is not found, then the locale string is shortened and retried if a delimiter is present. For MIDP, the delimiter is ("-" = U+002D). The locale is shortened by retaining only the characters up to but not including the last occurrence of the delimiter. The shortening and matching is repeated as long as the string contains a delimiter. Effectively, this will try the full locale and then try without the variant and then without the country code, if present.

Parameters:

locale - for which to find an ActionNameMap; MUST NOT be null

Returns:

an ActionNameMap; if there is no map available for the locale, then it MUST be null

Throws:

NullPointerException - if the locale is null

Since:

BlackBerry API 4.3.0

getActionNameMapCount

int getActionNameMapCount()

Gets the number of action name maps supported by the content handler. The number of action name maps must be equal to the length of the array of action name maps passed to Registry.register.

Returns:

the number of action name maps

Since:

BlackBerry API 4.3.0

getActionNameMap

ActionNameMap getActionNameMap(int index)

Gets the ActionNameMap supported by the content handler at the specified index. The ActionNameMap returned for each index must be the equal to the ActionNameMap at the same index in the actionnames array passed to Registry.register.

Parameters:

index - the index of the locale

Returns:

the ActionNameMap at the specified index

Throws:

IndexOutOfBoundsException - if index is less than zero or greater than or equal to the value of the getActionNameMapCount method.

Since:

BlackBerry API 4.3.0

getAppName

String getAppName()

Gets the user-friendly application name of this content handler. The value is extracted from the normal installation information about the content handler application.

Returns:

the user-friendly name of the application; it MUST NOT be null

Since:

BlackBerry API 4.3.0

getVersion

String getVersion()

Gets the version of this content handler. The value is extracted from the normal installation information about the content handler application.

Returns:

the version of the application; MAY be null

Since:

BlackBerry API 4.3.0

getAuthority

String getAuthority()

Gets the authority that authenticated this application. This value MUST be null unless the device has been able to authenticate this application. If non-null, it is the string identifying the authority. The authority is determined by the security mechanisms and policy of the Java runtime environment. For signed MIDP applications, it is the subject of the signing certificate.

Returns:

the authority; may be null

Since:

BlackBerry API 4.3.0