/*

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:

*

*/

package javax.microedition.m2g;

import java.io.IOException;

/**

 * This class models images in vector format, such as the Scalable Vector

 * Graphics (SVG) image format.  Therefore, it is required that all classes

 * representing "scalable" images extend this class.

 * @see      javax.microedition.m2g.SVGImage

 */

public abstract class ScalableImage

{

    /**

     * Constructor

     */

    protected ScalableImage()

    {

    }

    /**

     * This method creates and loads a ScalableImage (e.g. SVG) from the specified stream.

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

     * <ul>

     * <li>the SVG document does not conform to the XML 1.0 specification</li>

     * <li>an element has an attribute or property value which is not permissible according to the SVG specification </li>

     * <li>the required or mandatory attributes according to the SVG specification are missing</li>

     * <li>the document contains circular references on the &lt;use&gt; element</li>

     * <li>the document contains &lt;image&gt; element(s) with local references </li>

     * <li>the document contains elements with duplicate Id's</li>

     * <li>the document contains animation(s) in error</li>

     * </ul>

     *

     * <p>If an <code>handler</code> 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 <code>handler</code> 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 <code>null</code> for resourceData. </p>

     *

     * <p>Note that the <code>handler</code> 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:

     * <ul>

     * <li>When changing the xlink:href attribute of an existing &lt;image&gt; element that is already hooked or part of the tree.</li>

     * <li>When creating a new &lt;image&gt;, setting its xlink:href and hooking it to the document tree.</li>

     * </ul>

     * </p>

     *

     * @param stream The stream from which the SVG content should be read.

     * @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 content.

     * @throws NullPointerException if <code>stream</code> 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:

     * <ul>

     * <li>the SVG document does not conform to the XML 1.0 specification</li>

     * <li>an element has an attribute or property value which is not permissible according to the SVG specification </li>

     * <li>the required or mandatory attributes according to the SVG specification are missing</li>

     * <li>the document contains circular references on the &lt;use&gt; element</li>

     * <li>the document contains &lt;image&gt; element(s) with local references </li>

     * <li>the document contains elements with duplicate Id's</li>

     * <li>the document contains animation(s) in error</li>

     * </ul>

     *

     *

     * <p>If an <code>handler</code> 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 <code>handler</code> 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 <code>null</code> for resourceData. </p>

     *

     * <p>Note that the <code>handler</code> 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:

     * <ul>

     * <li>When changing the xlink:href attribute of an existing &lt;image&gt; element that is already hooked or part of the tree.</li>

     * <li>When creating a new &lt;image&gt;, setting its xlink:href and hooking it to the document tree.</li>

     * </ul>

     * </p>

     *

     * <p>

     * 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 <code>URL</code> 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 <code>SVGImage</code>, the engine will replace the current resource data with the new

    * one. <b>Note:</b> Setting <code>null</code> for resourceData indicates that the requested resource

    * could not be fetched by the <code>ResourceHandler</code> 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);

}