1 /*******************************************************************************
2 * Copyright 2013 André Rouél and Dominik Seichter
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 ******************************************************************************/
16 package net.sf.qualitytest.blueprint;
17
18 import java.lang.reflect.Field;
19 import java.lang.reflect.Method;
20
21 import javax.annotation.Nonnull;
22 import javax.annotation.Nullable;
23
24 import net.sf.qualitytest.exception.BlueprintCycleException;
25
26 /**
27 * Defines a blueprint configuration
28 *
29 * @author André Rouél
30 */
31 public interface BlueprintConfiguration {
32
33 /**
34 * Construct a Java-Object using a class as a blueprint.
35 *
36 * @see Blueprint
37 *
38 * @param <T>
39 * @param clazz
40 * a class
41 * @return a blue printed instance of {@code T}
42 */
43 @Nullable
44 <T> T construct(@Nonnull final Class<T> clazz);
45
46 /**
47 * Find a creation strategy that matches on the given field.
48 *
49 * @param field
50 * A field
51 *
52 * @return a {@code ValueCreationStrategy} or {@code null}
53 */
54 @Nullable
55 CreationStrategy<?> findCreationStrategyForField(@Nonnull final Field field);
56
57 /**
58 * Find a creation strategy that matches on the given method.
59 *
60 * @param method
61 * A setter method
62 *
63 * @return a {@code ValueCreationStrategy} or {@code null}
64 */
65 @Nullable
66 CreationStrategy<?> findCreationStrategyForMethod(@Nonnull final Method method);
67
68 /**
69 * Find a creation strategy that matches on a given type.
70 *
71 * @param class A class
72 *
73 * @return a {@code ValueCreationStrategy} or {@code null}
74 */
75 @Nullable
76 CreationStrategy<?> findCreationStrategyForType(@Nonnull final Class<?> clazz);
77
78 /**
79 * Handle the situation that a BlueprintCycle was detected for a particular class.
80 *
81 * @see Blueprint
82 *
83 * @param <T>
84 * @param session
85 * The current {@link BlueprintSession}
86 * @param clazz
87 * The class which caused cycle in the blueprinting graph
88 * @return a blue printed instance of {@code T}
89 */
90 @Nullable
91 <T> T handleCycle(@Nonnull final BlueprintSession session, @Nonnull final Class<T> clazz);
92
93 /**
94 * Retrieve if public attributes are filled during blueprinting.
95 *
96 * @return {@code true} if public attributes are filled during blueprinting
97 */
98 boolean isWithPublicAttributes();
99
100 /**
101 * Replace every attribute with the type {@code type} with a given value.
102 *
103 * @param type
104 * a Java type.
105 * @param creator
106 * Creation strategy which actually creates a new value.
107 *
108 * @return the changed blueprint configuration.
109 */
110 @Nonnull
111 <T> BlueprintConfiguration with(@Nonnull final Class<T> type, @Nullable final CreationStrategy<?> creator);
112
113 /**
114 * Replace every attribute with the type {@code type} with a given value.
115 *
116 * @param type
117 * a Java type.
118 * @param value
119 * value which should be assigned to the attribute
120 *
121 * @return the changed blueprint configuration.
122 */
123 @Nonnull
124 <T> BlueprintConfiguration with(@Nonnull final Class<T> type, @Nullable final T value);
125
126 /**
127 * Handle detected cycles in the blueprinting graph using an additional strategy. The default is to throw a
128 * {@link BlueprintCycleException}.
129 *
130 * @param cycleHandlingStrategy
131 * Strategy to define how cycles for a certain type are handled
132 *
133 * @return the changed blueprint configuration
134 */
135 @Nonnull
136 <T> BlueprintConfiguration with(@Nonnull final CycleHandlingStrategy<T> cycleHandlingStrategy);
137
138 /**
139 * Blueprint everything matching a given {@code MatchingStrategy} using this configuration.
140 *
141 * @param matchingStrategy
142 * Matching strategy to define if a given type or method should be constructed using blueprint.
143 * @return the changed blueprint configuration
144 */
145 @Nonnull
146 <T> BlueprintConfiguration with(@Nonnull final MatchingStrategy matchingStrategy);
147
148 /**
149 * Replace every attribute which matches a given strategy with a given value.
150 *
151 * @param matcher
152 * Matching strategy to define if the replaced should be applied.
153 * @param creator
154 * Creation strategy which actually creates a new value.
155 *
156 * @return the changed blueprint configuration.
157 */
158 @Nonnull
159 BlueprintConfiguration with(final MatchingStrategy matcher, final CreationStrategy<?> creator);
160
161 /**
162 * Replace every attribute with the name {@code name} with a given value.
163 *
164 * @param name
165 * case insensitive name of an attribute.
166 * @param value
167 * value which should be assigned to the attribute
168 *
169 * @return the changed blueprint configuration.
170 */
171 @Nonnull
172 <T> BlueprintConfiguration with(@Nonnull final String name, @Nullable final T value);
173
174 /**
175 * Configure whether public attributes should be filled with values during blueprinting.
176 *
177 * @param withPublicAttributes
178 * if {@code true} public attributes will be filled during blueprinting, otherwise they will be ignored.
179 *
180 * @return the changed blueprint configuration.
181 */
182 @Nonnull
183 BlueprintConfiguration withPublicAttributes(final boolean withPublicAttributes);
184
185 }