Commit: 69a5976b653746b019085207def7e4691aa9a717 - MikuMikuStudio (git)

Main repository of MikuMikuStudio

Commit MetaInfo

• Revision: 69a5976b653746b019085207def7e4691aa9a717 (tree)
• Time: 2013-07-07 03:56:44
• Author: kobayasi <kobayasi@pscn...>
• Commiter: kobayasi

Log Message

add asset cache

Change Summary

• modified: engine/src/core/com/jme3/asset/AssetKey.java
• add: engine/src/core/com/jme3/asset/AssetProcessor.java
• add: engine/src/core/com/jme3/asset/CloneableSmartAsset.java
• add: engine/src/core/com/jme3/asset/cache/AssetCache.java
• add: engine/src/core/com/jme3/asset/cache/SimpleAssetCache.java
• add: engine/src/core/com/jme3/asset/cache/WeakRefAssetCache.java
• add: engine/src/core/com/jme3/asset/cache/WeakRefCloneAssetCache.java

Incremental Difference

--- a/engine/src/core/com/jme3/asset/AssetKey.java
+++ b/engine/src/core/com/jme3/asset/AssetKey.java
@@ -61,7 +61,16 @@ public class AssetKey<T> implements Savable {
     public AssetKey(){
     }
 
-    protected static String getExtension(String name){
+    @Override
+    public AssetKey<T> clone() {
+        try {
+            return (AssetKey<T>) super.clone();
+        } catch (CloneNotSupportedException ex) {
+            throw new AssertionError();
+        }
+    }
+    
+    protected static String getExtension(String name) {
         int idx = name.lastIndexOf('.');
         //workaround for filenames ending with xml and another dot ending before that (my.mesh.xml)
         if (name.toLowerCase().endsWith(".xml")) {

--- /dev/null
+++ b/engine/src/core/com/jme3/asset/AssetProcessor.java
@@ -0,0 +1,71 @@
+/*
+ * Copyright (c) 2009-2012 jMonkeyEngine
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
+ *   may be used to endorse or promote products derived from this software
+ *   without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.jme3.asset;
+
+import com.jme3.material.Material;
+import com.jme3.shader.Shader;
+
+/**
+ * <code>AssetProcessor</code> is used to apply processing to assets
+ * after they have been loaded. They are assigned to a particular
+ * asset type (which is represented by a {@link Class} and any assets
+ * loaded that are of that class will be processed by the assigned
+ * processor.
+ * 
+ * @author Kirill Vainer
+ */
+public interface AssetProcessor {
+    /**
+     * Applies post processing to an asset.
+     * The method may return an object that is not the same
+     * instance as the parameter object, and it could be from a different class.
+     * 
+     * @param obj The asset that was loaded from an {@link AssetLoader}.
+     * @return Either the same object with processing applied, or an instance
+     * of a new object.
+     */
+    public Object postProcess(AssetKey key, Object obj);
+    
+    /**
+     * Creates a clone of the given asset.
+     * If no clone is desired, then the same instance can be returned,
+     * otherwise, a clone should be created.
+     * For example, a clone of a {@link Material} should have its own set
+     * of unique parameters that can be changed just for that instance,
+     * but it may share certain other data if it sees fit (like the {@link Shader}).
+     * 
+     * @param obj The asset to clone
+     * @return The cloned asset, or the same as the given argument if no
+     * clone is needed.
+     */
+    public Object createClone(Object obj);
+}

--- /dev/null
+++ b/engine/src/core/com/jme3/asset/CloneableSmartAsset.java
@@ -0,0 +1,86 @@
+/*
+ * Copyright (c) 2009-2012 jMonkeyEngine
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
+ *   may be used to endorse or promote products derived from this software
+ *   without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.jme3.asset;
+
+import com.jme3.asset.cache.WeakRefCloneAssetCache;
+
+/**
+ * Implementing the <code>CloneableSmartAsset</code> interface allows use 
+ * of cloneable smart asset management.
+ * <p>
+ * Smart asset management requires cooperation from the {@link AssetKey}. 
+ * In particular, the AssetKey should return {@link WeakRefCloneAssetCache} in its 
+ * {@link AssetKey#getCacheType()} method. Also smart assets MUST
+ * create a clone of the asset and cannot return the same reference,
+ * e.g. {@link AssetProcessor#createClone(java.lang.Object) createClone(someAsset)} <code>!= someAsset</code>.
+ * <p>
+ * If the {@link AssetManager#loadAsset(com.jme3.asset.AssetKey) } method
+ * is called twice with the same asset key (equals() wise, not necessarily reference wise)
+ * then both assets will have the same asset key set (reference wise) via
+ * {@link AssetKey#AssetKey() }, then this asset key
+ * is used to track all instances of that asset. Once all clones of the asset 
+ * are garbage collected, the shared asset key becomes unreachable and at that 
+ * point it is removed from the smart asset cache. 
+ */
+public interface CloneableSmartAsset extends Cloneable {
+    
+    /**
+     * Creates a clone of the asset. 
+     * 
+     * Please see {@link Object#clone() } for more info on how this method
+     * should be implemented. 
+     * 
+     * @return A clone of this asset. 
+     * The cloned asset cannot reference equal this asset.
+     */
+    public Object clone();
+    
+    /**
+     * Set by the {@link AssetManager} to track this asset. 
+     * 
+     * Only clones of the asset has this set, the original copy that
+     * was loaded has this key set to null so that only the clones are tracked
+     * for garbage collection. 
+     * 
+     * @param key The AssetKey to set
+     */
+    public void setKey(AssetKey key);
+    
+    /**
+     * Returns the asset key that is used to track this asset for garbage
+     * collection.
+     * 
+     * @return the asset key that is used to track this asset for garbage
+     * collection.
+     */
+    public AssetKey getKey();
+}

--- /dev/null
+++ b/engine/src/core/com/jme3/asset/cache/AssetCache.java
@@ -0,0 +1,121 @@
+/*
+ * Copyright (c) 2009-2012 jMonkeyEngine
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
+ *   may be used to endorse or promote products derived from this software
+ *   without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.jme3.asset.cache;
+
+import com.jme3.asset.AssetKey;
+
+/**
+ * <code>AssetCache</code> is an interface for asset caches. 
+ * Allowing storage of loaded resources in order to improve their access time 
+ * if they are requested again in a short period of time.
+ * Depending on the asset type and how it is used, a specialized 
+ * caching method can be selected that is most appropriate for that asset type.
+ * The asset cache must be thread safe.
+ * <p>
+ * Some caches are used to manage cloneable assets, which track reachability
+ * based on a shared key in all instances exposed in user code. 
+ * E.g. {@link WeakRefCloneAssetCache} uses this approach.
+ * For those particular caches, either {@link #registerAssetClone(com.jme3.asset.AssetKey, java.lang.Object) }
+ * or {@link #notifyNoAssetClone() } <b>MUST</b> be called to avoid memory 
+ * leaking following a successful {@link #addToCache(com.jme3.asset.AssetKey, java.lang.Object) }
+ * or {@link #getFromCache(com.jme3.asset.AssetKey) } call!
+ * 
+ * @author Kirill Vainer
+ */
+public interface AssetCache {
+    /**
+     * Adds an asset to the cache.
+     * Once added, it should be possible to retrieve the asset
+     * by using the {@link #getFromCache(com.jme3.asset.AssetKey) } method.
+     * However the caching criteria may at some point choose that the asset
+     * should be removed from the cache to save memory, in that case, 
+     * {@link #getFromCache(com.jme3.asset.AssetKey) } will return null.
+     * <p><font color="red">Thread-Safe</font>
+     * 
+     * @param <T> The type of the asset to cache.
+     * @param key The asset key that can be used to look up the asset.
+     * @param obj The asset data to cache.
+     */
+    public <T> void addToCache(AssetKey<T> key, T obj);
+    
+    /**
+     * This should be called by the asset manager when it has successfully
+     * acquired a cached asset (with {@link #getFromCache(com.jme3.asset.AssetKey) })
+     * and cloned it for use. 
+     * <p><font color="red">Thread-Safe</font>
+     * 
+     * @param <T> The type of the asset to register.
+     * @param key The asset key of the loaded asset (used to retrieve from cache)
+     * @param clone The <strong>clone</strong> of the asset retrieved from
+     * the cache.
+     */
+    public <T> void registerAssetClone(AssetKey<T> key, T clone);
+    
+    /**
+     * Notifies the cache that even though the methods {@link #addToCache(com.jme3.asset.AssetKey, java.lang.Object) }
+     * or {@link #getFromCache(com.jme3.asset.AssetKey) } were used, there won't
+     * be a call to {@link #registerAssetClone(com.jme3.asset.AssetKey, java.lang.Object) }
+     * for some reason. For example, if an error occurred during loading
+     * or if the addToCache/getFromCache were used from user code.
+     */
+    public void notifyNoAssetClone();
+    
+    /**
+     * Retrieves an asset from the cache.
+     * It is possible to add an asset to the cache using
+     * {@link #addToCache(com.jme3.asset.AssetKey, java.lang.Object) }. 
+     * The asset may be removed from the cache automatically even if
+     * it was added previously, in that case, this method will return null.
+     * <p><font color="red">Thread-Safe</font>
+     * 
+     * @param <T> The type of the asset to retrieve
+     * @param key The key used to lookup the asset.
+     * @return The asset that was previously cached, or null if not found.
+     */
+    public <T> T getFromCache(AssetKey<T> key);
+    
+    /**
+     * Deletes an asset from the cache.
+     * <p><font color="red">Thread-Safe</font>
+     * 
+     * @param key The asset key to find the asset to delete.
+     * @return True if the asset was successfully found in the cache
+     * and removed.
+     */
+    public boolean deleteFromCache(AssetKey key);
+    
+    /**
+     * Deletes all assets from the cache.
+     * <p><font color="red">Thread-Safe</font>
+     */
+    public void clearCache();
+}

--- /dev/null
+++ b/engine/src/core/com/jme3/asset/cache/SimpleAssetCache.java
@@ -0,0 +1,71 @@
+/*
+ * Copyright (c) 2009-2012 jMonkeyEngine
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
+ *   may be used to endorse or promote products derived from this software
+ *   without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.jme3.asset.cache;
+
+import com.jme3.asset.AssetKey;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * <code>SimpleAssetCache</code> is an asset cache
+ * that caches assets without any automatic removal policy. The user
+ * is expected to manually call {@link #deleteFromCache(com.jme3.asset.AssetKey) }
+ * to delete any assets.
+ * 
+ * @author Kirill Vainer
+ */
+public class SimpleAssetCache implements AssetCache {
+
+    private final ConcurrentHashMap<AssetKey, Object> keyToAssetMap = new ConcurrentHashMap<AssetKey, Object>();
+    
+    public <T> void addToCache(AssetKey<T> key, T obj) {
+        keyToAssetMap.put(key, obj);
+    }
+
+    public <T> void registerAssetClone(AssetKey<T> key, T clone) {
+    }
+
+    public <T> T getFromCache(AssetKey<T> key) {
+        return (T) keyToAssetMap.get(key);
+    }
+
+    public boolean deleteFromCache(AssetKey key) {
+        return keyToAssetMap.remove(key) != null;
+    }
+
+    public void clearCache() {
+        keyToAssetMap.clear();
+    }
+
+    public void notifyNoAssetClone() {
+    }
+    
+}

--- /dev/null
+++ b/engine/src/core/com/jme3/asset/cache/WeakRefAssetCache.java
@@ -0,0 +1,123 @@
+/*
+ * Copyright (c) 2009-2012 jMonkeyEngine
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
+ *   may be used to endorse or promote products derived from this software
+ *   without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.jme3.asset.cache;
+
+import com.jme3.asset.AssetKey;
+import com.jme3.asset.AssetProcessor;
+import java.lang.ref.ReferenceQueue;
+import java.lang.ref.WeakReference;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+/**
+ * A garbage collector bound asset cache that handles non-clonable objects.
+ * This cache assumes that the asset given to the user is the same asset
+ * that has been stored in the cache, in other words, 
+ * {@link AssetProcessor#createClone(java.lang.Object) } for that asset
+ * returns the same object as the argument.
+ * This implementation will remove the asset from the cache 
+ * once the asset is no longer referenced in user code and memory is low,
+ * e.g. the VM feels like purging the weak references for that asset.
+ * 
+ * @author Kirill Vainer
+ */
+public class WeakRefAssetCache implements AssetCache {
+
+    private static final Logger logger = Logger.getLogger(WeakRefAssetCache.class.getName());
+    
+    private final ReferenceQueue<Object> refQueue = new ReferenceQueue<Object>();
+    
+    private final ConcurrentHashMap<AssetKey, AssetRef> assetCache 
+            = new ConcurrentHashMap<AssetKey, AssetRef>();
+
+    private static class AssetRef extends WeakReference<Object> {
+        
+        private final AssetKey assetKey;
+        
+        public AssetRef(AssetKey assetKey, Object originalAsset, ReferenceQueue<Object> refQueue){
+            super(originalAsset, refQueue);
+            this.assetKey = assetKey;
+        }
+    }
+    
+    private void removeCollectedAssets(){
+        int removedAssets = 0;
+        for (AssetRef ref; (ref = (AssetRef)refQueue.poll()) != null;){
+            // Asset was collected, note that at this point the asset cache 
+            // might not even have this asset anymore, it is OK.
+            if (assetCache.remove(ref.assetKey) != null){
+                removedAssets ++;
+                //System.out.println("WeakRefAssetCache: The asset " + ref.assetKey + " was purged from the cache");
+            }
+        }
+        if (removedAssets >= 1) {
+            logger.log(Level.FINE, "WeakRefAssetCache: {0} assets were purged from the cache.", removedAssets);
+        }
+    }
+    
+    public <T> void addToCache(AssetKey<T> key, T obj) {
+        removeCollectedAssets();
+        
+        // NOTE: Some thread issues can hapen if another
+        // thread is loading an asset with the same key ..
+        AssetRef ref = new AssetRef(key, obj, refQueue);
+        assetCache.put(key, ref);
+        
+//        Texture t = (Texture) obj;
+//        Image i = t.getImage();
+//        System.out.println("add to cache "  + System.identityHashCode(i));
+    }
+
+    public <T> T getFromCache(AssetKey<T> key) {
+        AssetRef ref = assetCache.get(key);
+        if (ref != null){
+            return (T) ref.get();
+        }else{
+            return null;
+        }
+    }
+
+    public boolean deleteFromCache(AssetKey key) {
+        return assetCache.remove(key) != null;
+    }
+
+    public void clearCache() {
+        assetCache.clear();
+    }
+    
+    public <T> void registerAssetClone(AssetKey<T> key, T clone) {
+    }
+    
+    public void notifyNoAssetClone() {
+    }
+}

--- /dev/null
+++ b/engine/src/core/com/jme3/asset/cache/WeakRefCloneAssetCache.java
@@ -0,0 +1,206 @@
+/*
+ * Copyright (c) 2009-2012 jMonkeyEngine
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
+ *   may be used to endorse or promote products derived from this software
+ *   without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.jme3.asset.cache;
+
+import com.jme3.asset.AssetKey;
+import com.jme3.asset.CloneableSmartAsset;
+import java.lang.ref.PhantomReference;
+import java.lang.ref.ReferenceQueue;
+import java.lang.ref.WeakReference;
+import java.util.ArrayList;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+/**
+ * <codeWeakRefCloneAssetCache</code> caches cloneable assets in a weak-key
+ * cache, allowing them to be collected when memory is low.
+ * The cache stores weak references to the asset keys, so that
+ * when all clones of the original asset are collected, will cause the 
+ * asset to be automatically removed from the cache.
+ * 
+* @author Kirill Vainer
+ */
+public class WeakRefCloneAssetCache implements AssetCache {
+
+    private static final Logger logger = Logger.getLogger(WeakRefAssetCache.class.getName());
+    
+    private final ReferenceQueue<AssetKey> refQueue = new ReferenceQueue<AssetKey>();
+    
+    /**
+     * Maps cloned key to AssetRef which has a weak ref to the original 
+     * key and a strong ref to the original asset.
+     */
+    private final ConcurrentHashMap<AssetKey, AssetRef> smartCache 
+            = new ConcurrentHashMap<AssetKey, AssetRef>();
+    
+    /**
+     * Stored in the ReferenceQueue to find out when originalKey is collected
+     * by GC. Once collected, the clonedKey is used to remove the asset
+     * from the cache.
+     */
+    private static final class KeyRef extends PhantomReference<AssetKey> {
+        
+        AssetKey clonedKey;
+        
+        public KeyRef(AssetKey originalKey, ReferenceQueue<AssetKey> refQueue) {
+            super(originalKey, refQueue);
+            clonedKey = originalKey.clone();
+        }
+    }
+    
+    /**
+     * Stores the original key and original asset.
+     * The asset info contains a cloneable asset (e.g. the original, from
+     * which all clones are made). Also a weak reference to the 
+     * original key which is used when the clones are produced.
+     */
+    private static final class AssetRef extends WeakReference<AssetKey> {
+
+        CloneableSmartAsset asset;
+
+        public AssetRef(CloneableSmartAsset originalAsset, AssetKey originalKey) {
+            super(originalKey);
+            this.asset = originalAsset;
+        }
+    }
+
+    private final ThreadLocal<ArrayList<AssetKey>> assetLoadStack 
+            = new ThreadLocal<ArrayList<AssetKey>>() {
+        @Override
+        protected ArrayList<AssetKey> initialValue() {
+            return new ArrayList<AssetKey>();
+        }
+    };
+    
+    private void removeCollectedAssets(){
+        int removedAssets = 0;
+        for (KeyRef ref; (ref = (KeyRef)refQueue.poll()) != null;){
+            // (Cannot use ref.get() since it was just collected by GC!)
+            AssetKey key = ref.clonedKey;
+            
+            // Asset was collected, note that at this point the asset cache 
+            // might not even have this asset anymore, it is OK.
+            if (smartCache.remove(key) != null){
+                removedAssets ++;
+                //System.out.println("WeakRefAssetCache: The asset " + ref.assetKey + " was purged from the cache");
+            }
+        }
+        if (removedAssets >= 1) {
+            logger.log(Level.FINE, "WeakRefAssetCache: {0} assets were purged from the cache.", removedAssets);
+        }
+    }
+    
+    public <T> void addToCache(AssetKey<T> originalKey, T obj) {
+        // Make room for new asset
+        removeCollectedAssets();
+        
+        CloneableSmartAsset asset = (CloneableSmartAsset) obj;
+        
+        // No circular references, since the original asset is 
+        // strongly referenced, we don't want the key strongly referenced.
+        asset.setKey(null); 
+        
+        // Start tracking the collection of originalKey
+        // (this adds the KeyRef to the ReferenceQueue)
+        KeyRef ref = new KeyRef(originalKey, refQueue);
+        
+        // Place the asset in the cache, but use a clone of 
+        // the original key.
+        smartCache.put(ref.clonedKey, new AssetRef(asset, originalKey));
+        
+        // Push the original key used to load the asset
+        // so that it can be set on the clone later
+        ArrayList<AssetKey> loadStack = assetLoadStack.get();
+        loadStack.add(originalKey);
+    }
+
+    public <T> void registerAssetClone(AssetKey<T> key, T clone) {
+        ArrayList<AssetKey> loadStack = assetLoadStack.get();
+        ((CloneableSmartAsset)clone).setKey(loadStack.remove(loadStack.size() - 1));
+    }
+    
+    public void notifyNoAssetClone() {
+        ArrayList<AssetKey> loadStack = assetLoadStack.get();
+        loadStack.remove(loadStack.size() - 1);
+    }
+
+    public <T> T getFromCache(AssetKey<T> key) {
+        AssetRef smartInfo;
+        synchronized (smartCache){
+            smartInfo = smartCache.get(key);
+        }
+        
+        if (smartInfo == null) {
+            return null;
+        } else {
+            // NOTE: Optimization so that registerAssetClone()
+            // can check this and determine that the asset clone
+            // belongs to the asset retrieved here.
+            AssetKey keyForTheClone = smartInfo.get();
+            if (keyForTheClone == null){
+                // The asset was JUST collected by GC
+                // (between here and smartCache.get)
+                return null;
+            }
+            
+            // Prevent original key from getting collected
+            // while an asset is loaded for it.
+            ArrayList<AssetKey> loadStack = assetLoadStack.get();
+            loadStack.add(keyForTheClone);
+            
+            return (T) smartInfo.asset;
+        }
+    }
+
+    public boolean deleteFromCache(AssetKey key) {
+        ArrayList<AssetKey> loadStack = assetLoadStack.get();
+        
+        if (!loadStack.isEmpty()){
+            throw new UnsupportedOperationException("Cache cannot be modified"
+                                                  + "while assets are being loaded");
+        }
+        
+        return smartCache.remove(key) != null;
+    }
+    
+    public void clearCache() {
+        ArrayList<AssetKey> loadStack = assetLoadStack.get();
+        
+        if (!loadStack.isEmpty()){
+            throw new UnsupportedOperationException("Cache cannot be modified"
+                                                  + "while assets are being loaded");
+        }
+        
+        smartCache.clear();
+    }
+}