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   * The Builder interface is designed to designate a class as a <em>builder</em>
21   * object in the Builder design pattern. Builders are capable of creating and
22   * configuring objects or results that normally take multiple steps to construct
23   * or are very complex to derive.
24   *
25   * <p>
26   * The builder interface defines a single method, {@link #build()}, that
27   * classes must implement. The result of this method should be the final
28   * configured object or result after all building operations are performed.
29   * </p>
30   *
31   * <p>
32   * It is a recommended practice that the methods supplied to configure the
33   * object or result being built return a reference to {@code this} so that
34   * method calls can be chained together.
35   * </p>
36   *
37   * <p>
38   * Example Builder:
39   * <pre><code>
40   * class FontBuilder implements Builder&lt;Font&gt; {
41   *     private Font font;
42   *
43   *     public FontBuilder(String fontName) {
44   *         this.font = new Font(fontName, Font.PLAIN, 12);
45   *     }
46   *
47   *     public FontBuilder bold() {
48   *         this.font = this.font.deriveFont(Font.BOLD);
49   *         return this; // Reference returned so calls can be chained
50   *     }
51   *
52   *     public FontBuilder size(float pointSize) {
53   *         this.font = this.font.deriveFont(pointSize);
54   *         return this; // Reference returned so calls can be chained
55   *     }
56   *
57   *     // Other Font construction methods
58   *
59   *     public Font build() {
60   *         return this.font;
61   *     }
62   * }
63   * </code></pre>
64   *
65   * Example Builder Usage:
66   * <pre><code>
67   * Font bold14ptSansSerifFont = new FontBuilder(Font.SANS_SERIF).bold()
68   *                                                              .size(14.0f)
69   *                                                              .build();
70   * </code></pre>
71   *
72   * @param <T> the type of object that the builder will construct or compute.
73   *
74   * @since 3.0
75   */
76  @FunctionalInterface
77  public interface Builder<T> {
78  
79      /**
80       * Returns a reference to the object being constructed or result being
81       * calculated by the builder.
82       *
83       * @return the object constructed or result calculated by the builder.
84       */
85      T build();
86  }