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, install_only, remove, delete, 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, the Locale strings follow the definition of the system property microedition.locale and the delimiter MUST be a hyphen ("-" = U+002D). For all other runtimes, the format follows the requirements of java.lang.Locale and the delimiter MUST be an underscore ("_" = U+005F). 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.

Field Summary

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

Method Summary

java.lang.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(java.lang.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.
java.lang.String	getAppName() Gets the user-friendly application name of this content handler.
java.lang.String	getAuthority() Gets the authority that authenticated this application.
java.lang.String	getID() Gets the content handler application ID.
java.lang.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.
java.lang.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.
java.lang.String	getVersion() Gets the version of this content handler.
boolean	hasAction(java.lang.String action) Determines if an action is supported by the content handler.
boolean	hasSuffix(java.lang.String suffix) Determines if a suffix is supported by the content handler.
boolean	hasType(java.lang.String type) Determines if a type is supported by the content handler.

Field Detail

ACTION_OPEN

public static final java.lang.String ACTION_OPEN

Action to open content.

See Also:

Constant Field Values

ACTION_EDIT

public static final java.lang.String ACTION_EDIT

Action to edit the content.

See Also:

Constant Field Values

ACTION_SEND

public static final java.lang.String ACTION_SEND

Action to send the content via email or messaging.

See Also:

Constant Field Values

ACTION_SAVE

public static final java.lang.String ACTION_SAVE

Action to save the content.

See Also:

Constant Field Values

ACTION_EXECUTE

public static final java.lang.String ACTION_EXECUTE

Action to execute the content.

See Also:

Constant Field Values

ACTION_SELECT

public static final java.lang.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

ACTION_INSTALL

public static final java.lang.String ACTION_INSTALL

Action to install the content on the device.

See Also:

Constant Field Values

ACTION_INSTALL_ONLY

public static final java.lang.String ACTION_INSTALL_ONLY

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

See Also:

Constant Field Values

ACTION_REMOVE

public static final java.lang.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 delete.

See Also:

Constant Field Values

ACTION_DELETE

public static final java.lang.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

ACTION_PRINT

public static final java.lang.String ACTION_PRINT

Action to print the content.

See Also:

Constant Field Values

ACTION_NEW

public static final java.lang.String ACTION_NEW

Action to create new content.

See Also:

Constant Field Values

ACTION_STOP

public static final java.lang.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

UNIVERSAL_TYPE

public static final java.lang.String UNIVERSAL_TYPE

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

See Also:

Constant Field Values

Method Detail

getID

public java.lang.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

getType

public java.lang.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:

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

getTypeCount

public 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

hasType

public boolean hasType(java.lang.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:

java.lang.NullPointerException - if type is null

getSuffix

public java.lang.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:

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

getSuffixCount

public 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

hasSuffix

public boolean hasSuffix(java.lang.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:

java.lang.NullPointerException - if suffix is null

getAction

public java.lang.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:

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

getActionCount

public 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

hasAction

public boolean hasAction(java.lang.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:

java.lang.NullPointerException - if action is null

getActionNameMap

public 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

getActionNameMap

public ActionNameMap getActionNameMap(java.lang.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 hyphen ("-" = U+002D). For all other runtimes, the delimiter is an underscore ("_" = U+005F). 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:

java.lang.NullPointerException - if the locale is null

getActionNameMapCount

public 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

getActionNameMap

public 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:

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

getAppName

public java.lang.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

getVersion

public java.lang.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

getAuthority

public java.lang.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. For signed applications, the authority is the Subject of the signing certificate of the class registered as the content handler.

Returns:

the authority; may be null