1/*
2 * Copyright (c) 2009-2010 jMonkeyEngine
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are
7 * met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 *   notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 *   notice, this list of conditions and the following disclaimer in the
14 *   documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
17 *   may be used to endorse or promote products derived from this software
18 *   without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
22 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
27 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
28 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
29 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32
33package com.jme3.asset;
34
35/**
36 * Implementing the asset interface allows use of smart asset management.
37 * <p>
38 * Smart asset management requires cooperation from the {@link AssetKey}.
39 * In particular, the AssetKey should return true in its
40 * {@link AssetKey#useSmartCache() } method. Also smart assets MUST
41 * create a clone of the asset and cannot return the same reference,
42 * e.g. {@link AssetKey#createClonedInstance(java.lang.Object) createCloneInstance(someAsset)} <code>!= someAsset</code>.
43 * <p>
44 * If the {@link AssetManager#loadAsset(com.jme3.asset.AssetKey) } method
45 * is called twice with the same asset key (equals() wise, not necessarily reference wise)
46 * then both assets will have the same asset key set (reference wise) via
47 * {@link Asset#setKey(com.jme3.asset.AssetKey) }, then this asset key
48 * is used to track all instances of that asset. Once all clones of the asset
49 * are garbage collected, the shared asset key becomes unreachable and at that
50 * point it is removed from the smart asset cache.
51 */
52public interface Asset {
53
54    /**
55     * Set by the {@link AssetManager} to track this asset.
56     *
57     * Only clones of the asset has this set, the original copy that
58     * was loaded has this key set to null so that only the clones are tracked
59     * for garbage collection.
60     *
61     * @param key The AssetKey to set
62     */
63    public void setKey(AssetKey key);
64
65    /**
66     * Returns the asset key that is used to track this asset for garbage
67     * collection.
68     *
69     * @return the asset key that is used to track this asset for garbage
70     * collection.
71     */
72    public AssetKey getKey();
73}
74