1 /*
2 * Copyright 2001-2013 Stephen Colebourne
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 org.joda.beans;
17
18 import java.util.Map;
19
20 /**
21 * A builder for a bean, providing a safe way to create it.
22 * <p>
23 * This interface allows a bean to be created even if it is immutable.
24 *
25 * @param <T> the type of the bean
26 * @author Stephen Colebourne
27 */
28 public interface BeanBuilder<T extends Bean> {
29
30 /**
31 * Sets the value of a single property into the builder.
32 * <p>
33 * This will normally behave as per a {@code Map}, however it may not
34 * and as a general rule callers should only set each property once.
35 *
36 * @param propertyName the property name, not null
37 * @param value the property value, may be null
38 * @return {@code this}, for chaining, not null
39 * @throws RuntimeException optionally thrown if the property name is invalid
40 */
41 BeanBuilder<T> set(String propertyName, Object value);
42
43 /**
44 * Sets the value of a single property into the builder.
45 * <p>
46 * This will normally behave as per a {@code Map}, however it may not
47 * and as a general rule callers should only set each property once.
48 *
49 * @param property the property, not null
50 * @param value the property value, may be null
51 * @return {@code this}, for chaining, not null
52 * @throws RuntimeException optionally thrown if the property name is invalid
53 */
54 BeanBuilder<T> set(MetaProperty<?> property, Object value);
55
56 /**
57 * Sets the value of a single property into the builder.
58 * <p>
59 * This converts the string to the correct type for the property.
60 * Conversion uses Joda-Convert.
61 * <p>
62 * This will normally behave as per a {@code Map}, however it may not
63 * and as a general rule callers should only set each property once.
64 *
65 * @param propertyName the property name, not null
66 * @param value the property value, may be null
67 * @return {@code this}, for chaining, not null
68 * @throws RuntimeException optionally thrown if the property name is invalid
69 */
70 BeanBuilder<T> setString(String propertyName, String value);
71
72 /**
73 * Sets the value of a single property into the builder.
74 * <p>
75 * This converts the string to the correct type for the property.
76 * Conversion uses Joda-Convert.
77 * <p>
78 * This will normally behave as per a {@code Map}, however it may not
79 * and as a general rule callers should only set each property once.
80 *
81 * @param property the property name, not null
82 * @param value the property value, may be null
83 * @return {@code this}, for chaining, not null
84 * @throws RuntimeException optionally thrown if the property name is invalid
85 */
86 BeanBuilder<T> setString(MetaProperty<?> property, String value);
87
88 /**
89 * Sets the value of a map of properties into the builder.
90 * <p>
91 * Each map entry is used as the input to {@link #set(String, Object)}.
92 * <p>
93 * This will normally behave as per a {@code Map}, however it may not
94 * and as a general rule callers should only set each property once.
95 *
96 * @param propertyValueMap the property name to value map, not null
97 * @return {@code this}, for chaining, not null
98 * @throws RuntimeException optionally thrown if a property name is invalid
99 */
100 BeanBuilder<T> setAll(Map<String, ? extends Object> propertyValueMap);
101
102 /**
103 * Builds the bean from the state of the builder.
104 * <p>
105 * Once this method has been called, the builder is in an invalid state.
106 * The effect of further method calls is undetermined.
107 *
108 * @return the created bean, not null
109 */
110 T build();
111
112 }