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 /**
30 * <p/>
31 * Property represents a generic field or property of a Component definition. A component
32 * can have multiple properties. A single property instance holds the corresponding values
33 * for every component of that type in an EntitySystem. It is effectively an indexed map
34 * from component index to property value.
35 * <p/>
36 * This is an approach to mapped-objects where Components can be mapped onto primitive
37 * arrays so that iteration sees optimal cache locality. As an example, there could be two
38 * instances of type A, with properties a and b. The two 'a' properties would share the
39 * same data store, and the two 'b' properties would share another store.
40 * <p/>
41 * All property implementations must expose two methods: <code>T get(int)</code> and
42 * <code>void set(int, T)</code> to get and set values at a particular index. To support
43 * primitives without boxing, they are not part of the interface definition but are
44 * required. The exposed get() and set() methods, and potentially a bulk accessor (such as
45 * returning the underlying array) are the supported methods for manipulating decorated
46 * property values.
47 * <p/>
48 * Property instances are carefully managed by an EntitySystem. There is ever only one
49 * property instance per defined property in a component type for a system. Property
50 * instances are created by {@link PropertyFactory PropertyFactories}. Every concrete
51 * Property class must be annotated with {@link Factory} to specify the PropertyFactory
52 * class that constructs it. That PropertyFactory must expose a no-argument constructor,
53 * or a constructor that takes an {@link Attributes} instance as its only argument.
54 *
55 * @author Michael Ludwig
56 */
57 public interface Property {
58 /**
59 * Resize the internal storage to support indexed lookups from 0 to <code>size -
60 * 1</code>. If <var>>size</var> is less than the current capacity, all previous
61 * values with an index less than <var>size</var> must be preserved, and the remainder
62 * are discarded. If <var>size</var> is greater than the current capacity, all
63 * previous indexed values must be preserved and the new values can be undefined.
64 * <p/>
65 * This is for internal use only to manage, and should not be called on decorated
66 * properties returned by {@link com.lhkbob.entreri.EntitySystem#decorate(Class,
67 * PropertyFactory)}.
68 *
69 * @param size The new capacity, will be at least 1
70 */
71 public void setCapacity(int size);
72
73 /**
74 * Get the current capacity of the property. All instances must start with a capacity
75 * of at least 1. The capacity represents the number of component instances the
76 * property can handle. If a component property is decomposed into multiple primitives
77 * that is still a single value instance when considering the capacity.
78 * <p/>
79 * This is for internal use only to manage, and should not be called on decorated
80 * properties returned by {@link com.lhkbob.entreri.EntitySystem#decorate(Class,
81 * PropertyFactory)}.
82 *
83 * @return The current capacity of the property
84 */
85 public int getCapacity();
86
87 /**
88 * Swap the value at <var>indexA</var> with <var>indexB</var>.
89 * <p/>
90 * This is for internal use only to manage, and should not be called on decorated
91 * properties returned by {@link com.lhkbob.entreri.EntitySystem#decorate(Class,
92 * PropertyFactory)}.
93 *
94 * @param indexA The index of the first value
95 * @param indexB The index of the second value
96 */
97 public void swap(int indexA, int indexB);
98 }