If an handler is specified, the engine will invoke it for any
+ * external resource referenced in the document. However, please note that data URIs
+ * (for ex: base64 encoded images like <image xlink:href="data:image/png;base64,/9j/4AAQ..."/>)
+ * are required to be decoded by the engine, and therefore the handler will not be invoked
+ * in such cases. All these requests must occur before createImage returns, and the
+ * engine must only make one call if there exist multiple resources
+ * with the same URI. If the handler is set to null, the ScalableImage
+ * will try to load images automatically using the engine's default implementation,
+ * but might not be able to load all of them. For example, if the ScalableImage
+ * is loaded from a file in a Jar file, the implementation will not be able
+ * to load images that have relative URIs (ex; <image xlink:href="myImage.png" />).
+ * If the handler is not able to locate a requested resource, it informs the SVG engine
+ * by calling the requestCompleted method with null for resourceData.
Note that the handler is also called when the xlink:href attribute on
+ * <image> is set or changed by the application, but the call is made only when the
+ * element is hooked into the document tree i.e. when the ancestors go all the way up to
+ * the root <svg> element. There are two cases:
+ *
stream is null.
+ */
+ public static ScalableImage createImage(java.io.InputStream stream,
+ ExternalResourceHandler handler) throws IOException
+ {
+ return SVGImage.createImage(stream, handler);
+ }
+
+
+ /**
+ * This method creates and loads a ScalableImage (e.g. SVG) with the specified
+ * URI. A ScalableImage can only be rendered using the render() method in the ScalableGraphics
+ * context.The image size is determined by the content specification
+ * (eg: width/height attributes on root SVG element). The default viewport size
+ * of 100-by-100 pixels is used when the size is unspecified. This method will throw an
+ * exception when the image is in error. For SVG document, the document is in error when:
+ * If an handler is specified, the engine will invoke it for any
+ * external resource referenced in the document. However, please note that data URIs
+ * (for ex: base64 encoded images like <image xlink:href="data:image/png;base64,/9j/4AAQ..."/>)
+ * are required to be decoded by the engine, and therefore the handler will not be invoked
+ * in such cases. All these requests must occur before createImage returns, and the
+ * engine must only make one call if there exist multiple resources
+ * with the same URI. If the handler is set to null, the ScalableImage
+ * will try to load images automatically using the engine's default implementation,
+ * but might not be able to load all of them. For example, if the ScalableImage
+ * is loaded from a file in a Jar file, the implementation will not be able
+ * to load images that have relative URIs (ex: <image xlink:href="myImage.png" />).
+ * If the handler is not able to locate a requested resource, it informs the SVG engine
+ * by calling the requestCompleted method with null for resourceData.
Note that the handler is also called when the xlink:href attribute on
+ * <image> is set or changed by the application, but the call is made only when the
+ * element is hooked into the document tree i.e. when the ancestors go all the way up to
+ * the root <svg> element. There are two cases:
+ *
+ * If the platform implementation supports the JSR-75 FileConnection, then the file: URLs
+ * as used by JSR-75 shall be supported and the images are loaded from files identified
+ * by this locator. This can be used to load possible DRM protected image files from the
+ * file system.
+ *
+ * @param url A string in URL syntax that identifies the image source.
+ * @param handler implementation of the ExternalResourceHandler interface
+ * @see javax.microedition.m2g.ExternalResourceHandler
+ *
+ * @return the loaded ScalableImage
+ * @throws IOException if an error occurs while loading the SVG content.
+ * @throws NullPointerException if URL is null.
+ * @throws java.lang.IllegalArgumentException if the specified locator is of unsupported type.
+ * @throws SecurityException if the application does not have the privilege rights to access
+ * the contents of this resource.
+ *
+ */
+ public static ScalableImage createImage(String url,
+ ExternalResourceHandler handler) throws IOException
+ {
+ return SVGImage.createImage(url, handler);
+ }
+
+ /**
+ * This method returns the ScalableImage's viewport height. The initial
+ * viewport height is taken from the "height" value specified in the Scalable Image. The value
+ * returned is always in pixels. If the specified height is defined in percentages, the
+ * values are mapped to the default view port size of 100x100. If the viewport height
+ * is explicitly changed by the application, then the percentages are ignored and the content
+ * is made to fit to this new viewport height.
+ *
+ * @return the current height of this ScalableImage.
+ * @see #setViewportHeight
+ */
+ public abstract int getViewportHeight();
+
+ /**
+ * This method returns the ScalableImage's viewport width. The initial
+ * viewport width is taken from the "width" value specified in the Scalable Image. The value
+ * returned is always in pixels. If the specified width is defined in percentages, the
+ * values are mapped to the default view port size of 100x100. If the viewport width
+ * is explicitly changed by the application, then the percentages are ignored and the content
+ * is made to fit to this new viewport width.
+ *
+ * @return the current width of this ScalableImage.
+ * @see #setViewportWidth
+ */
+ public abstract int getViewportWidth();
+
+ /**
+ * Once the requested external resource is available, the application forwards this information
+ * (resourceData) to the SVG engine. If this method is called a second time for a same URL of a
+ * same SVGImage, the engine will replace the current resource data with the new
+ * one. Note: Setting null for resourceData indicates that the requested resource
+ * could not be fetched by the ResourceHandler or application, and in this
+ * event the SVG engine will not make further attempts to load this resource.
+ *
+ * @param URI URI that was requested through requestExternalResource
+ * @param resourceData inputstream containing the external resource
+ *
+ * @see javax.microedition.m2g.ExternalResourceHandler
+ *
+ * @throws IOException if an error occurs while loading the resource.
+ * @throws NullPointerException if URL is null.
+ */
+ public abstract void requestCompleted(String URI, java.io.InputStream resourceData) throws IOException;
+
+ /**
+ * This method sets the new (viewport) height of this ScalableImage.
+ *
+ * @param height the new height to be set.
+ * @see #getViewportHeight
+ * @throws IllegalArgumentException if height is negative.
+ */
+ public abstract void setViewportHeight(int height);
+
+ /**
+ * This method sets the new (viewport) width of this ScalableImage.
+ * The viewport is the area where the ScalableImage is rendered. Any parts
+ * of the viewport that lie outside the boundaries of the target clipping
+ * rectangle are clipped. The viewport upper left corner (x, y) is given
+ * relative to the upper left corner of the target rendering surface.
+ *
+ * @param width the new width to be set.
+ * @see #getViewportWidth
+ * @throws IllegalArgumentException if width is negative.
+ */
+ public abstract void setViewportWidth(int width);
+}