1 /*
2 * Entreri, an entity-component framework in Java
3 *
4 * Copyright (c) 2013, Michael Ludwig
5 * All rights reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without modification,
8 * are permitted provided that the following conditions are met:
9 *
10 * Redistributions of source code must retain the above copyright notice,
11 * this list of conditions and the following disclaimer.
12 * Redistributions in binary form must reproduce the above copyright notice,
13 * this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
20 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
23 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27 package com.lhkbob.entreri.property;
28
29 import com.lhkbob.entreri.Entity;
30 import com.lhkbob.entreri.EntitySystem;
31
32 import java.lang.annotation.Retention;
33 import java.lang.annotation.RetentionPolicy;
34
35 /**
36 * <p/>
37 * Clone is an attribute that can be applied to property declarations to change how the
38 * property's values are cloned when a Component or Entity are created from a template
39 * Component or Entity. At the moment it can be used to: <ol> <li>Copy values using Java's
40 * assignment semantics</li> <li>Clone objects using their clone() method if it
41 * exists</li> <li>Do not copy the value, and use the default value the factory normally
42 * would have assigned</li> </ol>
43 * <p/>
44 * If these options are not sufficient, a custom {@link PropertyFactory} can be
45 * implemented and specified by using the {@link Factory} annotation.
46 *
47 * @author Michael Ludwig
48 */
49 @Attribute
50 @Retention(RetentionPolicy.RUNTIME)
51 public @interface Clone {
52 /**
53 * Policy is an enum describing a number of different behaviors performed by a {@link
54 * PropertyFactory} when its {@link PropertyFactory#clone(Property, int, Property,
55 * int)} method is invoked in response to {@link Entity#add(com.lhkbob.entreri.Component)}
56 * or {@link EntitySystem#addEntity(Entity)}.
57 */
58 public static enum Policy {
59 /**
60 * Cloning policy that disables the clone action for the given property. The new
61 * component being cloned into gets the default value, just as if it was
62 * initialized via {@link Entity#add(Class)}.
63 */
64 DISABLE,
65 /**
66 * <p/>
67 * Cloning policy that follows Java's assignment semantics, e.g. primitives are
68 * copied by value from the component being cloned to the new one, and references
69 * are copied but the actual instances are shared.
70 * <p/>
71 * This is the default policy if the Clone attribute is not present on any of the
72 * property implementations provided in this package.
73 */
74 JAVA_DEFAULT,
75 /**
76 * <p/>
77 * Cloning policy that attempts to invoke {@link Object#clone()} on cloned
78 * component's current value. If the value is null, null is assigned without
79 * throwing an NPE.
80 * <p/>
81 * If the property type is a primitive data type, or is not {@link Cloneable},
82 * this behaves like JAVA_DEFAULT.
83 */
84 INVOKE_CLONE
85 }
86
87 /**
88 * @return The cloning policy to use
89 */
90 Policy value();
91 }