1 /*

     2 * Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 

    18 

    19 package javax.microedition.m2g;

    20 

    21 import java.io.IOException;

    22 

    23 /**

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

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

    26  * representing "scalable" images extend this class.

    27  * @see      javax.microedition.m2g.SVGImage

    28  */

    29 public abstract class ScalableImage

    30 {

    31     /**

    32      * Constructor

    33      */

    34     protected ScalableImage()

    35     {

    36     }

    37 

    38     /**

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

    40      * A ScalableImage can only be rendered using the render() method in the ScalableGraphics

    41      * context.The image size is determined by the content specification

    42      * (eg: width/height attributes on root SVG element). The default viewport size

    43      * of 100-by-100 pixels is used when the size is unspecified. This method will throw an exception

    44      * when the image is in error. For SVG document, the document is in error when:

    45      * <ul>

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

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

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

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

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

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

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

    53      * </ul>

    54      *

    55      * <p>If an <code>handler</code> is specified, the engine will invoke it for any

    56      * external resource referenced in the document. However, please note that data URIs

    57      * (for ex: base64 encoded images like <image xlink:href="data:image/png;base64,/9j/4AAQ..."/>)

    58      * are required to be decoded by the engine, and therefore the handler will not be invoked

    59      * in such cases. All these requests must occur before createImage returns, and the

    60      * engine must only make one call if there exist multiple resources

    61      * with the same URI. If the <code>handler</code> is set to null, the ScalableImage

    62      * will try to load images automatically using the engine's default implementation,

    63      * but might not be able to load all of them. For example, if the ScalableImage

    64      * is loaded from a file in a Jar file, the implementation will not be able

    65      * to load images that have relative URIs (ex; <image xlink:href="myImage.png" />).

    66      * If the handler is not able to locate a requested resource, it informs the SVG engine

    67      * by calling the requestCompleted method with <code>null</code> for resourceData. </p>

    68      *

    69      * <p>Note that the <code>handler</code> is also called when the xlink:href attribute on

    70      * <image> is set or changed by the application, but the call is made only when the

    71      * element is hooked into the document tree i.e. when the ancestors go all the way up to

    72      * the root <svg> element. There are two cases:

    73      * <ul>

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

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

    76      * </ul>

    77      * </p>

    78      *

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

    80      * @param handler implementation of the ExternalResourceHandler interface

    81      * @see      javax.microedition.m2g.ExternalResourceHandler

    82      *

    83      * @return the loaded ScalableImage.

    84      * @throws IOException if an error occurs while loading the content.

    85      * @throws NullPointerException if <code>stream</code> is null.

    86      */

    87     public static ScalableImage createImage(java.io.InputStream stream,

    88                                             ExternalResourceHandler handler) throws IOException

    89     {

    90         return SVGImage.createImage(stream, handler);

    91     }

    92 

    93 

    94     /**

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

    96      * URI. A ScalableImage can only be rendered using the render() method in the ScalableGraphics

    97      * context.The image size is determined by the content specification

    98      * (eg: width/height attributes on root SVG element). The default viewport size

    99      * of 100-by-100 pixels is used when the size is unspecified. This method will throw an

   100      * exception when the image is in error. For SVG document, the document is in error when:

   101      * <ul>

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

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

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

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

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

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

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

   109      * </ul>

   110      *

   111      *

   112      * <p>If an <code>handler</code> is specified, the engine will invoke it for any

   113      * external resource referenced in the document. However, please note that data URIs

   114      * (for ex: base64 encoded images like <image xlink:href="data:image/png;base64,/9j/4AAQ..."/>)

   115      * are required to be decoded by the engine, and therefore the handler will not be invoked

   116      * in such cases. All these requests must occur before createImage returns, and the

   117      * engine must only make one call if there exist multiple resources

   118      * with the same URI. If the <code>handler</code> is set to null, the ScalableImage

   119      * will try to load images automatically using the engine's default implementation,

   120      * but might not be able to load all of them. For example, if the ScalableImage

   121      * is loaded from a file in a Jar file, the implementation will not be able

   122      * to load images that have relative URIs (ex: <image xlink:href="myImage.png" />).

   123      * If the handler is not able to locate a requested resource, it informs the SVG engine

   124      * by calling the requestCompleted method with <code>null</code> for resourceData. </p>

   125      *

   126      * <p>Note that the <code>handler</code> is also called when the xlink:href attribute on

   127      * <image> is set or changed by the application, but the call is made only when the

   128      * element is hooked into the document tree i.e. when the ancestors go all the way up to

   129      * the root <svg> element. There are two cases:

   130      * <ul>

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

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

   133      * </ul>

   134      * </p>

   135      *

   136      * <p>

   137      * If the platform implementation supports the JSR-75 FileConnection, then the file: URLs

   138      * as used by JSR-75 shall be supported and the images are loaded from files identified

   139      * by this locator. This can be used to load possible DRM protected image files from the

   140      * file system.

   141      *

   142      * @param url A string in URL syntax that identifies the image source.

   143      * @param handler implementation of the ExternalResourceHandler interface

   144      * @see      javax.microedition.m2g.ExternalResourceHandler

   145      *

   146      * @return the loaded ScalableImage

   147      * @throws IOException if an error occurs while loading the SVG content.

   148      * @throws NullPointerException if <code>URL</code> is null.

   149      * @throws java.lang.IllegalArgumentException if the specified locator is of unsupported type.

   150      * @throws SecurityException if the application does not have the privilege rights to access

   151      * the contents of this resource.

   152      *

   153      */

   154     public static ScalableImage createImage(String url,

   155                                             ExternalResourceHandler handler) throws IOException

   156     {

   157         return SVGImage.createImage(url, handler);

   158     }

   159 

   160     /**

   161      * This method returns the ScalableImage's viewport height. The initial

   162      * viewport height is taken from the "height" value specified in the Scalable Image. The value

   163      * returned is always in pixels. If the specified height is defined in percentages, the

   164      * values are mapped to the default view port size of 100x100. If the viewport height

   165      * is explicitly changed by the application, then the percentages are ignored and the content

   166      * is made to fit to this new viewport height.

   167      *

   168      * @return the current height of this ScalableImage.

   169      * @see #setViewportHeight

   170      */

   171     public abstract int getViewportHeight();

   172 

   173     /**

   174      * This method returns the ScalableImage's viewport width. The initial

   175      * viewport width is taken from the "width" value specified in the Scalable Image. The value

   176      * returned is always in pixels. If the specified width is defined in percentages, the

   177      * values are mapped to the default view port size of 100x100. If the viewport width

   178      * is explicitly changed by the application, then the percentages are ignored and the content

   179      * is made to fit to this new viewport width.

   180      *

   181      * @return the current width of this ScalableImage.

   182      * @see #setViewportWidth

   183      */

   184     public abstract int getViewportWidth();

   185 

   186     /**

   187     * Once the requested external resource is available, the application forwards this information

   188     * (resourceData) to the SVG engine. If this method is called a second time for a same URL of a

   189     * same <code>SVGImage</code>, the engine will replace the current resource data with the new

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

   191     * could not be fetched by the <code>ResourceHandler</code> or application, and in this

   192     * event the SVG engine will not make further attempts to load this resource.

   193     *

   194     * @param URI URI that was requested through requestExternalResource

   195     * @param resourceData inputstream containing the external resource

   196     *

   197     * @see      javax.microedition.m2g.ExternalResourceHandler

   198     *

   199     * @throws IOException if an error occurs while loading the resource.

   200     * @throws NullPointerException if URL is null.

   201     */

   202     public abstract void requestCompleted(String URI, java.io.InputStream resourceData) throws IOException;

   203 

   204     /**

   205      * This method sets the new (viewport) height of this ScalableImage.

   206      *

   207      * @param height the new height to be set.

   208      * @see #getViewportHeight

   209      * @throws IllegalArgumentException if height is negative.

   210      */

   211     public abstract void setViewportHeight(int height);

   212 

   213     /**

   214      * This method sets the new (viewport) width of this ScalableImage.

   215      * The viewport is the area where the ScalableImage is rendered. Any parts

   216      * of the viewport that lie outside the boundaries of the target clipping

   217      * rectangle are clipped. The viewport upper left corner (x, y) is given

   218      * relative to the upper left corner of the target rendering surface.

   219      *

   220      * @param width the new width to be set.

   221      * @see #getViewportWidth

   222      * @throws IllegalArgumentException if width is negative.

   223      */

   224     public abstract void setViewportWidth(int width);

   225 }