View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3.builder;
18  
19  /**
20   * <p>
21   * The Builder interface is designed to designate a class as a <em>builder</em> 
22   * object in the Builder design pattern. Builders are capable of creating and 
23   * configuring objects or results that normally take multiple steps to construct 
24   * or are very complex to derive. 
25   * </p>
26   * 
27   * <p>
28   * The builder interface defines a single method, {@link #build()}, that 
29   * classes must implement. The result of this method should be the final 
30   * configured object or result after all building operations are performed.
31   * </p>
32   * 
33   * <p>
34   * It is a recommended practice that the methods supplied to configure the 
35   * object or result being built return a reference to {@code this} so that
36   * method calls can be chained together.
37   * </p>
38   * 
39   * <p>
40   * Example Builder:
41   * <pre><code>
42   * class FontBuilder implements Builder&lt;Font&gt; {
43   *     private Font font;
44   *     
45   *     public FontBuilder(String fontName) {
46   *         this.font = new Font(fontName, Font.PLAIN, 12);
47   *     }
48   * 
49   *     public FontBuilder bold() {
50   *         this.font = this.font.deriveFont(Font.BOLD);
51   *         return this; // Reference returned so calls can be chained
52   *     }
53   *     
54   *     public FontBuilder size(float pointSize) {
55   *         this.font = this.font.deriveFont(pointSize);
56   *         return this; // Reference returned so calls can be chained
57   *     }
58   * 
59   *     // Other Font construction methods
60   * 
61   *     public Font build() {
62   *         return this.font;
63   *     }
64   * }
65   * </code></pre>
66   * 
67   * Example Builder Usage:
68   * <pre><code>
69   * Font bold14ptSansSerifFont = new FontBuilder(Font.SANS_SERIF).bold()
70   *                                                              .size(14.0f)
71   *                                                              .build();
72   * </code></pre>
73   *
74   * 
75   * @param <T> the type of object that the builder will construct or compute.
76   * 
77   * @since 3.0
78   * @version $Id: Builder.java 1583482 2014-03-31 22:54:57Z niallp $
79   */
80  public interface Builder<T> {
81  
82      /**
83       * Returns a reference to the object being constructed or result being 
84       * calculated by the builder.
85       * 
86       * @return the object constructed or result calculated by the builder.
87       */
88      T build();
89  }