1 /*******************************************************************************
\r
2 * Copyright (c) 2007, 2010 Association for Decentralized Information Management
\r
3 * in Industry THTH ry.
\r
4 * All rights reserved. This program and the accompanying materials
\r
5 * are made available under the terms of the Eclipse Public License v1.0
\r
6 * which accompanies this distribution, and is available at
\r
7 * http://www.eclipse.org/legal/epl-v10.html
\r
10 * VTT Technical Research Centre of Finland - initial API and implementation
\r
11 *******************************************************************************/
\r
12 package org.simantics.g2d.image;
\r
14 import java.net.URL;
\r
16 import org.simantics.g2d.image.impl.CacheProvider;
\r
17 import org.simantics.g2d.image.impl.ImageBundleFactory;
\r
18 import org.simantics.g2d.image.impl.ImageProxy;
\r
19 import org.simantics.g2d.image.impl.ImageURLFactory;
\r
20 import org.simantics.g2d.image.impl.ProviderAsyncronizer;
\r
21 import org.simantics.g2d.image.impl.ProviderProxier;
\r
22 import org.simantics.g2d.image.impl.RasterizingProvider;
\r
23 import org.simantics.utils.datastructures.cache.IFactory;
\r
24 import org.simantics.utils.datastructures.cache.IProvider;
\r
25 import org.simantics.utils.datastructures.cache.WeakCachedProvider;
\r
28 * Image Provider Utilities offers methods for constructing chains of
\r
29 * provider {@link Image} providers.
\r
31 * The nature of IProvider<Image> is at the same time
\r
32 * (a) description of the source of an image
\r
33 * e.g. at("https://www.simantics.org/simantics/simantics/logo.jpg")
\r
35 * (b) method of acquiring the image from its source
\r
36 * e.g. Image i = provider.get();
\r
38 * IProviders are equals-comparable and can be used as keys in a map.
\r
41 * map.put( at("https://www.simantics.org/simantics/simantics/logo.jpg"), obj1 );
\r
43 * Object obj2 = map.get( at("https://www.simantics.org/simantics/simantics/logo.jpg") );
\r
46 * The difference between IProvider<Image> and IFactory<Image> is Factory
\r
47 * always constructs a new instance and provider may either instantiate new instance
\r
48 * or return cached result.
\r
50 * In typical scenario the result of IFactory<Image> is cached using cacheResult().
\r
51 * The cached result is stored weakly and therefore strong references are required.
\r
52 * proxy() adds strong reference ({@link ImageProxy}) factory.
\r
56 * IFactory<Image> prov = reference(weakCache(rasterize(asynchronize(at("https://www.simantics.org/simantics/simantics/logo.jpg")))));
\r
58 * Image handle = prov.get();
\r
59 * handle.addImageListener();
\r
64 * handle instance would be a composition of the following instances:
\r
69 * java.awt.image.BufferedImage
\r
72 * @See {@link ImageUtils}
\r
73 * @author Toni Kalajainen <toni.kalajainen@vtt.fi>
\r
75 public class ProviderUtils {
\r
78 * Create provider that retrieves symbol from URL.
\r
79 * Bitmap and SVG symbols are supported. The format of the image is determined
\r
80 * by the suffix of the url.
\r
85 public static IFactory<Image> at(URL url)
\r
87 return new ImageURLFactory(url);
\r
91 * Create image from bundle address. The bundle address is in format:
\r
92 * "<bundleId/location/file.ext>"
\r
93 * Image type is determined from the suffix (.svg .png .jpg etc supported).
\r
95 * @param filename bundle address
\r
96 * @return bundle image constructor
\r
98 public static IFactory<Image> bundle(String filename)
\r
100 return new ImageBundleFactory(filename);
\r
104 * Caches the result of the provided image with a weak reference.
\r
105 * The cached result will be garbage collected with out strong reference
\r
106 * (See reference() ).
\r
110 public static IProvider<Image> cache(IProvider<Image> provider)
\r
112 return WeakCachedProvider.cache(provider);
\r
116 * Creates a memory buffer backed raster of provided vector based image.
\r
117 * For non-vector images this provider changes nothing.
\r
119 * @param prov image provider
\r
120 * @return provider that rasterizes the image
\r
122 public static IFactory<Image> rasterize(IProvider<Image> prov) {
\r
123 return new RasterizingProvider(prov);
\r
127 * Converts provider into asynchronized provider. It returns non-blocking result
\r
128 * while at the same time acquires the actual image of the source provider
\r
129 * in a thread. Once the image is complete the content of the result will be changed.
\r
130 * Due to this model, the result is Volatile.
\r
132 * @param prov original provider
\r
133 * @return asynchronous provider (constructs new image every time)
\r
135 public static IFactory<Image> asynchronize(IProvider<Image> prov) {
\r
136 return new ProviderAsyncronizer(prov);
\r
140 * Adds a strong reference (proxy instance) to the provider chain.
\r
141 * Proxy handles are used with cache to ensure strong references to the
\r
142 * weakly cached result.
\r
144 * @param prov original provider (cache provider)
\r
145 * @return asynchronous provider (constructs new image every time)
\r
147 public static IFactory<Image> reference(IProvider<Image> prov) {
\r
148 return new ProviderProxier(prov);
\r
152 * Caches the constructed image weakly. Use proxy provider to create
\r
153 * strong references to the cached image.
\r
156 * @return caching provider
\r
158 public static IProvider<Image> cache(IFactory<Image> prov) {
\r
159 return new CacheProvider(prov);
\r
163 * Convenience method that
\r
164 * 1. acquires image asynchronously in a thread
\r
165 * 2. rasterizes the image to memory buffer, if necessary (it is vector format)
\r
166 * 3. caches the resulted image
\r
167 * 4. creates a strong reference for the cached image
\r
169 * The result of the factory instantiates proxy handles.
\r
170 * Proxy handle returns constructed or cached image.
\r
171 * The underlying image will be remain in memory until all handles are
\r
172 * released (nulled).
\r
175 * IFactory<Image> i = convenience( at("https://www.simantics.org/simantics/simantics/logo.jpg") );
\r
179 * @param originalFactory
\r
180 * @return factory that instantiates disposable (nullable) handles
\r
182 public static IFactory<Image> convenience(IFactory<Image> originalFactory) {
\r
183 return reference(cache(rasterize(asynchronize(originalFactory))));
\r
185 public static IFactory<Image> convenience(URL url) {
\r
186 return reference(cache(rasterize(asynchronize(at(url)))));
\r
188 public static IFactory<Image> convenience(String bundleAddress) {
\r
189 return reference(cache(rasterize(asynchronize(bundle(bundleAddress)))));
\r