javax.microedition.m2g
Interface ExternalResourceHandler

public interface ExternalResourceHandler

This interface is used to load external resources that are referenced within a ScalableImage, namely within an SVG document in the case of SVG. In SVGT 1.1, these resources are not required for displaying the SVG document. If no ExternalResourceHandler is registered when creating the image, the engine will retrieve these resources using its own implementation of the requestResource method.

The default engine behaviour can be overwritten by passing to createImage an implementation of this interface as parameter when the default implementation is insufficient. For example, if the SVGImage is loaded from within a Jar file, the implementation will not be able to load images that have relative URIs (e.g., <image xlink:href="myImage.png" />). All the external resources are requested by the engine at the time of the createImage() call. Note that SVGT 1.1 does not contain external references to SVG files, therefore an external resource can not contain subsequent external resources.

The ScalableImage instances are primarily used to call the requestCompleted() method. Using it for anything else should be carefully considered because requestResource may be called before the SVGImage gets fully loaded (through createImage()), and any method invocation referencing such an SVGImage has an undefined behavior. For example, it is discouraged to create an animator or render the image during the requestResource() call, as their behavior is only defined on valid SVGImages (returned with no exception from either createImage() or createEmptyImage()).

See Also:

ScalableImage

Since:

BlackBerry API 4.6.0

Method Summary
void	requestResource(ScalableImage image, String URI) This method is invoked when an external resource is required by the underlying implementation.

Method Detail

requestResource

void requestResource(ScalableImage image,
                     String URI)

This method is invoked when an external resource is required by the underlying implementation. When the request is completed by the implementation of this handler, a notification must be sent to the SVG engine through the requestCompleted() method of ScalableImage. To get a synchronous behaviour, requestCompleted() can be called in the implementation of requestResource. If called later, rendering the document before completing all the requests will just display the currently available content. Once the request is completed, the image will have to be redrawn to reflect the newly available data. For more details on required resources, please refer to the externalResourcesRequired attribute description in the SVG specification.

Parameters:

image - image that originated the external data request

URI - the URI for the external resource. The URI must always be computed to its absolute form, to the extent possible. For ex: if the ScalableImage is loaded using an URL, then the computed absolute URI for the requested external resource must include this base URL. For more information please refer to http://www.w3.org/TR/xmlbase.

Since:

BlackBerry API 4.6.0