-/*******************************************************************************\r
- * Copyright (c) 2007, 2010 Association for Decentralized Information Management\r
- * in Industry THTH ry.\r
- * All rights reserved. This program and the accompanying materials\r
- * are made available under the terms of the Eclipse Public License v1.0\r
- * which accompanies this distribution, and is available at\r
- * http://www.eclipse.org/legal/epl-v10.html\r
- *\r
- * Contributors:\r
- * VTT Technical Research Centre of Finland - initial API and implementation\r
- *******************************************************************************/\r
-package org.simantics.g2d.image;\r
-\r
-import java.net.URL;\r
-\r
-import org.simantics.g2d.image.impl.CacheProvider;\r
-import org.simantics.g2d.image.impl.ImageBundleFactory;\r
-import org.simantics.g2d.image.impl.ImageProxy;\r
-import org.simantics.g2d.image.impl.ImageURLFactory;\r
-import org.simantics.g2d.image.impl.ProviderAsyncronizer;\r
-import org.simantics.g2d.image.impl.ProviderProxier;\r
-import org.simantics.g2d.image.impl.RasterizingProvider;\r
-import org.simantics.utils.datastructures.cache.IFactory;\r
-import org.simantics.utils.datastructures.cache.IProvider;\r
-import org.simantics.utils.datastructures.cache.WeakCachedProvider;\r
-\r
-/**\r
- * Image Provider Utilities offers methods for constructing chains of \r
- * provider {@link Image} providers. \r
- * <p>\r
- * The nature of IProvider<Image> is at the same time \r
- * (a) description of the source of an image\r
- * e.g. at("https://www.simantics.org/simantics/simantics/logo.jpg") \r
- * \r
- * (b) method of acquiring the image from its source\r
- * e.g. Image i = provider.get();\r
- * <p>\r
- * IProviders are equals-comparable and can be used as keys in a map.\r
- * eg.\r
- * <pre>\r
- * map.put( at("https://www.simantics.org/simantics/simantics/logo.jpg"), obj1 );\r
- * ...\r
- * Object obj2 = map.get( at("https://www.simantics.org/simantics/simantics/logo.jpg") );\r
- * </pre>\r
- * <p>\r
- * The difference between IProvider<Image> and IFactory<Image> is Factory\r
- * always constructs a new instance and provider may either instantiate new instance\r
- * or return cached result. \r
- * \r
- * In typical scenario the result of IFactory<Image> is cached using cacheResult().\r
- * The cached result is stored weakly and therefore strong references are required.\r
- * proxy() adds strong reference ({@link ImageProxy}) factory. \r
- * <p>\r
- * Example:\r
- * <pre>\r
- * IFactory<Image> prov = reference(weakCache(rasterize(asynchronize(at("https://www.simantics.org/simantics/simantics/logo.jpg")))));\r
- * \r
- * Image handle = prov.get();\r
- * handle.addImageListener();\r
- * handle.paint();\r
- * handle = null;\r
- * </pre>\r
- * \r
- * handle instance would be a composition of the following instances:\r
- * <pre>\r
- * ImageProxy\r
- * AsyncImage\r
- * AWTImage\r
- * java.awt.image.BufferedImage\r
- * </pre>\r
- *\r
- * @See {@link ImageUtils}\r
- * @author Toni Kalajainen <toni.kalajainen@vtt.fi>\r
- */\r
-public class ProviderUtils {\r
-\r
- /**\r
- * Create provider that retrieves symbol from URL. \r
- * Bitmap and SVG symbols are supported. The format of the image is determined\r
- * by the suffix of the url. \r
- * \r
- * @param url\r
- * @return\r
- */\r
- public static IFactory<Image> at(URL url)\r
- {\r
- return new ImageURLFactory(url);\r
- }\r
- \r
- /**\r
- * Create image from bundle address. The bundle address is in format: \r
- * "<bundleId/location/file.ext>" \r
- * Image type is determined from the suffix (.svg .png .jpg etc supported).\r
- * \r
- * @param filename bundle address\r
- * @return bundle image constructor\r
- */\r
- public static IFactory<Image> bundle(String filename)\r
- {\r
- return new ImageBundleFactory(filename);\r
- } \r
- \r
- /**\r
- * Caches the result of the provided image with a weak reference.\r
- * The cached result will be garbage collected with out strong reference\r
- * (See reference() ).\r
- * \r
- * @return cache\r
- */\r
- public static IProvider<Image> cache(IProvider<Image> provider)\r
- {\r
- return WeakCachedProvider.cache(provider);\r
- }\r
-\r
- /**\r
- * Creates a memory buffer backed raster of provided vector based image. \r
- * For non-vector images this provider changes nothing.\r
- * \r
- * @param prov image provider\r
- * @return provider that rasterizes the image\r
- */\r
- public static IFactory<Image> rasterize(IProvider<Image> prov) {\r
- return new RasterizingProvider(prov); \r
- }\r
- \r
- /**\r
- * Converts provider into asynchronized provider. It returns non-blocking result\r
- * while at the same time acquires the actual image of the source provider \r
- * in a thread. Once the image is complete the content of the result will be changed.\r
- * Due to this model, the result is Volatile. \r
- * \r
- * @param prov original provider\r
- * @return asynchronous provider (constructs new image every time)\r
- */\r
- public static IFactory<Image> asynchronize(IProvider<Image> prov) {\r
- return new ProviderAsyncronizer(prov); \r
- }\r
-\r
- /**\r
- * Adds a strong reference (proxy instance) to the provider chain. \r
- * Proxy handles are used with cache to ensure strong references to the\r
- * weakly cached result. \r
- * \r
- * @param prov original provider (cache provider)\r
- * @return asynchronous provider (constructs new image every time)\r
- */\r
- public static IFactory<Image> reference(IProvider<Image> prov) {\r
- return new ProviderProxier(prov); \r
- }\r
- \r
- /**\r
- * Caches the constructed image weakly. Use proxy provider to create\r
- * strong references to the cached image.\r
- * \r
- * @param prov \r
- * @return caching provider\r
- */\r
- public static IProvider<Image> cache(IFactory<Image> prov) {\r
- return new CacheProvider(prov);\r
- }\r
-\r
- /**\r
- * Convenience method that \r
- * 1. acquires image asynchronously in a thread\r
- * 2. rasterizes the image to memory buffer, if necessary (it is vector format)\r
- * 3. caches the resulted image\r
- * 4. creates a strong reference for the cached image\r
- * \r
- * The result of the factory instantiates proxy handles.\r
- * Proxy handle returns constructed or cached image. \r
- * The underlying image will be remain in memory until all handles are \r
- * released (nulled). \r
- * \r
- * Usage example:\r
- * IFactory<Image> i = convenience( at("https://www.simantics.org/simantics/simantics/logo.jpg") ); \r
- * i.paint();\r
- * i = null;\r
- * \r
- * @param originalFactory\r
- * @return factory that instantiates disposable (nullable) handles \r
- */\r
- public static IFactory<Image> convenience(IFactory<Image> originalFactory) {\r
- return reference(cache(rasterize(asynchronize(originalFactory))));\r
- }\r
- public static IFactory<Image> convenience(URL url) {\r
- return reference(cache(rasterize(asynchronize(at(url)))));\r
- }\r
- public static IFactory<Image> convenience(String bundleAddress) {\r
- return reference(cache(rasterize(asynchronize(bundle(bundleAddress)))));\r
- }\r
- \r
-}\r
-\r
+/*******************************************************************************
+ * Copyright (c) 2007, 2010 Association for Decentralized Information Management
+ * in Industry THTH ry.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ * VTT Technical Research Centre of Finland - initial API and implementation
+ *******************************************************************************/
+package org.simantics.g2d.image;
+
+import java.net.URL;
+
+import org.simantics.g2d.image.impl.CacheProvider;
+import org.simantics.g2d.image.impl.ImageBundleFactory;
+import org.simantics.g2d.image.impl.ImageProxy;
+import org.simantics.g2d.image.impl.ImageURLFactory;
+import org.simantics.g2d.image.impl.ProviderAsyncronizer;
+import org.simantics.g2d.image.impl.ProviderProxier;
+import org.simantics.g2d.image.impl.RasterizingProvider;
+import org.simantics.utils.datastructures.cache.IFactory;
+import org.simantics.utils.datastructures.cache.IProvider;
+import org.simantics.utils.datastructures.cache.WeakCachedProvider;
+
+/**
+ * Image Provider Utilities offers methods for constructing chains of
+ * provider {@link Image} providers.
+ * <p>
+ * The nature of IProvider<Image> is at the same time
+ * (a) description of the source of an image
+ * e.g. at("https://www.simantics.org/simantics/simantics/logo.jpg")
+ *
+ * (b) method of acquiring the image from its source
+ * e.g. Image i = provider.get();
+ * <p>
+ * IProviders are equals-comparable and can be used as keys in a map.
+ * eg.
+ * <pre>
+ * map.put( at("https://www.simantics.org/simantics/simantics/logo.jpg"), obj1 );
+ * ...
+ * Object obj2 = map.get( at("https://www.simantics.org/simantics/simantics/logo.jpg") );
+ * </pre>
+ * <p>
+ * The difference between IProvider<Image> and IFactory<Image> is Factory
+ * always constructs a new instance and provider may either instantiate new instance
+ * or return cached result.
+ *
+ * In typical scenario the result of IFactory<Image> is cached using cacheResult().
+ * The cached result is stored weakly and therefore strong references are required.
+ * proxy() adds strong reference ({@link ImageProxy}) factory.
+ * <p>
+ * Example:
+ * <pre>
+ * IFactory<Image> prov = reference(weakCache(rasterize(asynchronize(at("https://www.simantics.org/simantics/simantics/logo.jpg")))));
+ *
+ * Image handle = prov.get();
+ * handle.addImageListener();
+ * handle.paint();
+ * handle = null;
+ * </pre>
+ *
+ * handle instance would be a composition of the following instances:
+ * <pre>
+ * ImageProxy
+ * AsyncImage
+ * AWTImage
+ * java.awt.image.BufferedImage
+ * </pre>
+ *
+ * @See {@link ImageUtils}
+ * @author Toni Kalajainen <toni.kalajainen@vtt.fi>
+ */
+public class ProviderUtils {
+
+ /**
+ * Create provider that retrieves symbol from URL.
+ * Bitmap and SVG symbols are supported. The format of the image is determined
+ * by the suffix of the url.
+ *
+ * @param url
+ * @return
+ */
+ public static IFactory<Image> at(URL url)
+ {
+ return new ImageURLFactory(url);
+ }
+
+ /**
+ * Create image from bundle address. The bundle address is in format:
+ * "<bundleId/location/file.ext>"
+ * Image type is determined from the suffix (.svg .png .jpg etc supported).
+ *
+ * @param filename bundle address
+ * @return bundle image constructor
+ */
+ public static IFactory<Image> bundle(String filename)
+ {
+ return new ImageBundleFactory(filename);
+ }
+
+ /**
+ * Caches the result of the provided image with a weak reference.
+ * The cached result will be garbage collected with out strong reference
+ * (See reference() ).
+ *
+ * @return cache
+ */
+ public static IProvider<Image> cache(IProvider<Image> provider)
+ {
+ return WeakCachedProvider.cache(provider);
+ }
+
+ /**
+ * Creates a memory buffer backed raster of provided vector based image.
+ * For non-vector images this provider changes nothing.
+ *
+ * @param prov image provider
+ * @return provider that rasterizes the image
+ */
+ public static IFactory<Image> rasterize(IProvider<Image> prov) {
+ return new RasterizingProvider(prov);
+ }
+
+ /**
+ * Converts provider into asynchronized provider. It returns non-blocking result
+ * while at the same time acquires the actual image of the source provider
+ * in a thread. Once the image is complete the content of the result will be changed.
+ * Due to this model, the result is Volatile.
+ *
+ * @param prov original provider
+ * @return asynchronous provider (constructs new image every time)
+ */
+ public static IFactory<Image> asynchronize(IProvider<Image> prov) {
+ return new ProviderAsyncronizer(prov);
+ }
+
+ /**
+ * Adds a strong reference (proxy instance) to the provider chain.
+ * Proxy handles are used with cache to ensure strong references to the
+ * weakly cached result.
+ *
+ * @param prov original provider (cache provider)
+ * @return asynchronous provider (constructs new image every time)
+ */
+ public static IFactory<Image> reference(IProvider<Image> prov) {
+ return new ProviderProxier(prov);
+ }
+
+ /**
+ * Caches the constructed image weakly. Use proxy provider to create
+ * strong references to the cached image.
+ *
+ * @param prov
+ * @return caching provider
+ */
+ public static IProvider<Image> cache(IFactory<Image> prov) {
+ return new CacheProvider(prov);
+ }
+
+ /**
+ * Convenience method that
+ * 1. acquires image asynchronously in a thread
+ * 2. rasterizes the image to memory buffer, if necessary (it is vector format)
+ * 3. caches the resulted image
+ * 4. creates a strong reference for the cached image
+ *
+ * The result of the factory instantiates proxy handles.
+ * Proxy handle returns constructed or cached image.
+ * The underlying image will be remain in memory until all handles are
+ * released (nulled).
+ *
+ * Usage example:
+ * IFactory<Image> i = convenience( at("https://www.simantics.org/simantics/simantics/logo.jpg") );
+ * i.paint();
+ * i = null;
+ *
+ * @param originalFactory
+ * @return factory that instantiates disposable (nullable) handles
+ */
+ public static IFactory<Image> convenience(IFactory<Image> originalFactory) {
+ return reference(cache(rasterize(asynchronize(originalFactory))));
+ }
+ public static IFactory<Image> convenience(URL url) {
+ return reference(cache(rasterize(asynchronize(at(url)))));
+ }
+ public static IFactory<Image> convenience(String bundleAddress) {
+ return reference(cache(rasterize(asynchronize(bundle(bundleAddress)))));
+ }
+
+}
+
Code Review / simantics / platform.git / blobdiff