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

public static final String ACTION_EDIT
Action to edit the content.
Since:
JDE 4.3.0

ACTION_EXECUTE

public static final String ACTION_EXECUTE
Action to execute the content.
Since:
JDE 4.3.0

ACTION_INSTALL

public static final String ACTION_INSTALL
Action to install the content on the device.
Since:
JDE 4.3.0

ACTION_NEW

public static final String ACTION_NEW
Action to create new content.
Since:
JDE 4.3.0

ACTION_OPEN

public static final String ACTION_OPEN
Action to open content.
Since:
JDE 4.3.0

ACTION_PRINT

public static final String ACTION_PRINT
Action to print the content.
Since:
JDE 4.3.0

ACTION_SAVE

public static final String ACTION_SAVE
Action to save the content.
Since:
JDE 4.3.0

ACTION_SELECT

public 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.
Since:
JDE 4.3.0

ACTION_SEND

public static final String ACTION_SEND
Action to send the content via email or messaging. Handlers registered with this action as well as an ActionNameMap and a supported mime type will have dialog buttons and/or menu items added when viewing images of the specified type in the camera application or file explorer application.
Since:
JDE 4.3.0

ACTION_STOP

public 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.
Since:
JDE 4.3.0

UNIVERSAL_TYPE

public static final String UNIVERSAL_TYPE
The universal type; a handler supporting this type can handle any type of content.
Since:
JDE 4.3.0
Method Detail

getAction

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

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
Since:
JDE 4.3.0

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
Since:
JDE 4.3.0

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:
IndexOutOfBoundsException - if index is less than zero or greater than or equal to the value of the getActionNameMapCount method.
Since:
JDE 4.3.0

getActionNameMap

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

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
Since:
JDE 4.3.0

getAppName

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

getAuthority

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

getID

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

getSuffix

public 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 getSuffixCount() method.
Since:
JDE 4.3.0

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
Since:
JDE 4.3.0

getType

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

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
Since:
JDE 4.3.0

getVersion

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

hasAction

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

hasSuffix

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

hasType

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



Copyright 1999-2009 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.