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, install, 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_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_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_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
           
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
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

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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.