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.impl;
28
29 import com.lhkbob.entreri.property.PropertyFactory;
30
31 /**
32 * PropertyDeclaration represents a particular "property" instance declared in a Component
33 * sub-interface. A property is represented by a bean getter method and an associated
34 * setter. This interface captures the requisite information needed to implement a
35 * component type.
36 *
37 * @author Michael Ludwig
38 */
39 public interface PropertyDeclaration extends Comparable<PropertyDeclaration> {
40 /**
41 * Get the logical name of the property, either the name extracted from the getter
42 * bean method, or from the {@link com.lhkbob.entreri.property.Named} annotation.
43 *
44 * @return The property name
45 */
46 public String getName();
47
48 /**
49 * Get the canonical class name of the type of value stored by this property.
50 *
51 * @return The type of this property, suitable for inclusion in source code
52 */
53 public String getType();
54
55 /**
56 * Get the canonical class name of the {@link com.lhkbob.entreri.property.Property
57 * Property} implementation corresponding to the type of this property.
58 *
59 * @return The property implementation, suitable for inclusion in source code
60 */
61 public String getPropertyImplementation();
62
63 /**
64 * Get the name of the setter method that will be used to modify this property value.
65 * Multiply properties may use the same setter, and {@link #getSetterParameter()}
66 * determines their order in the signature. All properties in a ComponentSpecification
67 * that share a setter name use the same setter method.
68 *
69 * @return The name of the setter method
70 */
71 public String getSetterMethod();
72
73 /**
74 * Get the name of the getter method that is used to access the value of this
75 * property. Its return type is equal to {@link #getType()} and it will not take any
76 * arguments.
77 *
78 * @return The bean getter method
79 */
80 public String getGetterMethod();
81
82 /**
83 * Get the parameter index used by this property in the signature of its corresponding
84 * setter method. This will be 0 for properties that use the standard bean setter
85 * method, but may be different when properties share the same setter with multiple
86 * parameters.
87 *
88 * @return The method parameter corresponding to this property
89 */
90 public int getSetterParameter();
91
92 /**
93 * Get whether or not the signature of the setter method of this property returns the
94 * owning Component or if it returns void. When multiple properties have the same
95 * setter method name, this will always agree.
96 *
97 * @return True if the method signature returns the component
98 */
99 public boolean getSetterReturnsComponent();
100
101 /**
102 * Get whether or not this property should use the shared instance API to store and
103 * get values of the property.
104 *
105 * @return True if the getter was annotated with {@link com.lhkbob.entreri.property.SharedInstance}
106 */
107 public boolean isShared();
108
109 /**
110 * Get the PropertyFactory instance that was configured for this property. It must be
111 * used to instantiate the property objects that will be assignable to the type
112 * returned by {@link #getPropertyImplementation()}, and will be configured by all
113 * attribute annotations applied to the getter method.
114 * <p/>
115 * This is only available during a runtime situation, and should not be called when
116 * ComponentSpecification came from the mirror API.
117 *
118 * @return The property factory for this property
119 */
120 public PropertyFactory<?> getPropertyFactory();
121 }