View Javadoc

1   /**********************************************
2    * Copyright (C) 2010 Lukas Laag
3    * This file is part of lib-gwt-svg.
4    * 
5    * libgwtsvg is free software: you can redistribute it and/or modify
6    * it under the terms of the GNU Lesser General Public License as published by
7    * the Free Software Foundation, either version 3 of the License, or
8    * (at your option) any later version.
9    * 
10   * libgwtsvg is distributed in the hope that it will be useful,
11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13   * GNU Lesser General Public License for more details.
14   * 
15   * You should have received a copy of the GNU Lesser General Public License
16   * along with libgwtsvg.  If not, see http://www.gnu.org/licenses/
17   **********************************************/
18  package org.vectomatic.dom.svg.utils;
19  
20  /**
21   * Interface to define an API to load XML resources asynchronously.
22   * <p>If you want to develop a GWT application which runs as a
23   * regular web application, you do not need this level of
24   * abstraction and can use the {@link HttpRequestXmlLoader} class
25   * directly with no specific configuration.</p>
26   * <p>If you want to develop a GWT application which can be run
27   * either as a regular web application or as a plasmoid / opera control,
28   * you will create instances of this type by calling:
29   * <pre>AsyncXmlLoader loader = GWT.create(AsyncXmlLoader.class)</pre>
30   * then use the proper GWT configuration to control which implementation
31   * gets instantiated.
32   * </p>
33   * <p>For regular web application, use {@link HttpRequestXmlLoader}:</p>
34   * <pre>
35   * &lt;replace-with class="org.vectomatic.dom.svg.utils.HttpRequestXmlLoader"&gt;
36   *  &lt;when-type-is class="org.vectomatic.dom.svg.utils.AsyncXmlLoader" /&gt;
37   * &lt;/replace-with&gt;
38   * </pre>
39   * <p>For plasmoids / opera controls, use {@link IFrameXmlLoader}:</p>
40   * <pre>
41   * &lt;replace-with class="org.vectomatic.dom.svg.utils.IFrameXmlLoader"&gt;
42   *  &lt;when-type-is class="org.vectomatic.dom.svg.utils.AsyncXmlLoader" /&gt;
43   * &lt;/replace-with&gt;
44   * </pre>
45   * <p>For instance, if you want to load an SVG image located
46   * in the <b>public</b> directory of your GWT
47   * application, you should make the following call:</p>
48   * <pre>
49   * AsyncXmlLoader loader = ...;
50   * String resourceName = "foo.svg";
51   * loader.loadResource(GWT.getModuleBaseURL() + "/" + resourceName, new AsyncXmlLoaderCallback() {
52   *	public void onSuccess(String resourceName, Element root) {
53   *	 RootPanel.get().add(new SVGImage(OMNode.&lt;OMSVGSVGElement&gt;convert(root)));
54   *	}
55   *	public void onError(String resourceName, Throwable error) {
56   *	 GWT.log("Cannot load " + resourceName, error);
57   *	}
58   * });
59   * </pre>
60   */
61  public interface AsyncXmlLoader {
62  	/**
63  	 * Initiates a request to load an XML resource
64  	 * @param resourceUrl
65  	 * The resource to load
66  	 * @param callback
67  	 * A callback invoked to process the resource once it is loaded
68  	 */
69  	public void loadResource(String resourceUrl, AsyncXmlLoaderCallback callback);
70  }