net.rim.device.api.content
Class DefaultContentHandlerRegistry

java.lang.Object
  net.rim.device.api.content.DefaultContentHandlerRegistry

public class DefaultContentHandlerRegistry
extends Object

Sets and retrieves default content handlers that have been registered.

This registry permits two main functions:

1. Set and get the default handler: setDefaultContentHandler() and getDefaultContentHandler().
2. Set and get the application descriptor for a content handler: setApplicationDescriptor() and setApplicationDescriptor(). This is useful for specifying the icon that is associated with the content handler. Additionally, the application descriptor can contain localized names of the content handler application.

Note for Applications

Users are affected when you change the default content handlers. Applications should consider prompting the user to configure or accept the defaults being set. Consider prompting the user when:

• replacing an existing default content handler
• setting more than one default
• setting the default of a commonly used type such as JPEG or HTML

The bottom line is to keep the user in mind when setting default content handlers.

See Also:

ContentHandler

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

Method Summary
	void	clearAllDefaults() Clears all of the default content handlers that were set.
	ApplicationDescriptor	getApplicationDescriptor(String contentHandlerId) Returns the application descriptor for the content handler.
	ContentHandler	getDefaultContentHandler(Invocation invocation) Returns the default handler for the given invocation.
	static DefaultContentHandlerRegistry	getDefaultContentHandlerRegistry(Registry registry) Returns an instance for the given registry.
	void	setApplicationDescriptor(ApplicationDescriptor appDescriptor, String contentHandlerId) Sets the application descriptor for the given content handler.
	void	setDefaultContentHandler(String[] types, String[] suffixes, String[] actions, String contentHandlerId) Sets the default content handler for the given types, suffixes, and actions.

Methods inherited from class java.lang.Object

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

Method Detail

getDefaultContentHandlerRegistry

public static DefaultContentHandlerRegistry getDefaultContentHandlerRegistry(Registry registry)

Returns an instance for the given registry. The given registry will be used to perform Registry operations so any security restrictions will be based on the given registry.

Parameters:

registry - The registry. Must not be null.

Returns:

An instance for the given registry.

Throws:

NullPointerException - if registry is null.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

getDefaultContentHandler

public ContentHandler getDefaultContentHandler(Invocation invocation)
                                        throws IOException,
                                               SecurityException

Returns the default handler for the given invocation. The returned handler will be one of the handlers from using Registry.findHandler.

Parameters:

invocation - The ID, type, action, and URL that are needed to identify one or more content handlers; must not be null.

Returns:

The default content handler for the invocation; returns null if there is no default.

Throws:

IllegalArgumentException - if ID, type, action, and URL are all null

IOException - if the content is accessed via the URL and the URL is invalid

SecurityException - if access to the content is not permitted

NullPointerException - if the invocation is null

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

setDefaultContentHandler

public void setDefaultContentHandler(String[] types,
                                     String[] suffixes,
                                     String[] actions,
                                     String contentHandlerId)

Sets the default content handler for the given types, suffixes, and actions.

Parameters:

types - An array of content types; if null it is treated the same as an empty array.

suffixes - An array of suffixes to register; if null it is treated the same as an empty array.

actions - An array of actions to register; if null it is treated the same as an empty array.

contentHandlerId - The content handler ID; if null, any default handler associated with the types, suffixes, and actions is cleared.

Throws:

NullPointerException - if any array element of types, suffixes, actions is null

SecurityException - if registration is not permitted

IllegalArgumentException - if the content handler is not registered for the given types, suffixes or actions

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

setApplicationDescriptor

public void setApplicationDescriptor(ApplicationDescriptor appDescriptor,
                                     String contentHandlerId)

Sets the application descriptor for the given content handler. This is meant to be called only from Registry.

Parameters:

appDescriptor - The application descriptor for the content handler.

contentHandlerId - The ID for the content handler.

Throws:

NullPointerException - if appDescriptor or contentHandlerId is null

IllegalArgumentException - if contentHandlerId is not a registered ID

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

getApplicationDescriptor

public ApplicationDescriptor getApplicationDescriptor(String contentHandlerId)

Returns the application descriptor for the content handler.

Parameters:

contentHandlerId - A registered content handler ID.

Returns:

The application descriptor for the content handler; returns null if one does not exist or if contentHandlerId is null.

Throws:

NullPointerException - if contentHandlerId is null.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

clearAllDefaults

public void clearAllDefaults()

Clears all of the default content handlers that were set.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0