    001    /*
    002     * Licensed to the Apache Software Foundation (ASF) under one or more
    003     * contributor license agreements.  See the NOTICE file distributed with
    004     * this work for additional information regarding copyright ownership.
    005     * The ASF licenses this file to You under the Apache License, Version 2.0
    006     * (the "License"); you may not use this file except in compliance with
    007     * the License.  You may obtain a copy of the License at
    008     *
    009     *      http://www.apache.org/licenses/LICENSE-2.0
    010     *
    011     * Unless required by applicable law or agreed to in writing, software
    012     * distributed under the License is distributed on an "AS IS" BASIS,
    013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014     * See the License for the specific language governing permissions and
    015     * limitations under the License.
    016     */
    017    package org.apache.commons.lang3.builder;
    018
    019    /**
    020     * <p>
    021     * The Builder interface is designed to designate a class as a <em>builder</em>
    022     * object in the Builder design pattern. Builders are capable of creating and
    023     * configuring objects or results that normally take multiple steps to construct
    024     * or are very complex to derive.
    025     * </p>
    026     *
    027     * <p>
    028     * The builder interface defines a single method, {@link #build()}, that
    029     * classes must implement. The result of this method should be the final
    030     * configured object or result after all building operations are performed.
    031     * </p>
    032     *
    033     * <p>
    034     * It is a recommended practice that the methods supplied to configure the
    035     * object or result being built return a reference to {@code this} so that
    036     * method calls can be chained together.
    037     * </p>
    038     *
    039     * <p>
    040     * Example Builder:
    041     * <code><pre>
    042     * class FontBuilder implements Builder&lt;Font&gt; {
    043     *     private Font font;
    044     *
    045     *     public FontBuilder(String fontName) {
    046     *         this.font = new Font(fontName, Font.PLAIN, 12);
    047     *     }
    048     *
    049     *     public FontBuilder bold() {
    050     *         this.font = this.font.deriveFont(Font.BOLD);
    051     *         return this; // Reference returned so calls can be chained
    052     *     }
    053     *
    054     *     public FontBuilder size(float pointSize) {
    055     *         this.font = this.font.deriveFont(pointSize);
    056     *         return this; // Reference returned so calls can be chained
    057     *     }
    058     *
    059     *     // Other Font construction methods
    060     *
    061     *     public Font build() {
    062     *         return this.font;
    063     *     }
    064     * }
    065     * </pre></code>
    066     *
    067     * Example Builder Usage:
    068     * <code><pre>
    069     * Font bold14ptSansSerifFont = new FontBuilder(Font.SANS_SERIF).bold()
    070     *                                                              .size(14.0f)
    071     *                                                              .build();
    072     * </pre></code>
    073     * </p>
    074     *
    075     * @param <T> the type of object that the builder will construct or compute.
    076     *
    077     * @since 3.0
    078     * @version $Id: Builder.java 1088899 2011-04-05 05:31:27Z bayard $
    079     */
    080    public interface Builder<T> {
    081
    082        /**
    083         * Returns a reference to the object being constructed or result being
    084         * calculated by the builder.
    085         *
    086         * @return the object constructed or result calculated by the builder.
    087         */
    088        public T build();
    089    }