001    /****************************************************************
002     * Licensed to the Apache Software Foundation (ASF) under one   *
003     * or more contributor license agreements.  See the NOTICE file *
004     * distributed with this work for additional information        *
005     * regarding copyright ownership.  The ASF licenses this file   *
006     * to you under the Apache License, Version 2.0 (the            *
007     * "License"); you may not use this file except in compliance   *
008     * with the License.  You may obtain a copy of the License at   *
009     *                                                              *
010     *   http://www.apache.org/licenses/LICENSE-2.0                 *
011     *                                                              *
012     * Unless required by applicable law or agreed to in writing,   *
013     * software distributed under the License is distributed on an  *
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
015     * KIND, either express or implied.  See the License for the    *
016     * specific language governing permissions and limitations      *
017     * under the License.                                           *
018     ****************************************************************/
019    
020    package org.apache.james.mime4j.stream;
021    
022    import org.apache.james.mime4j.MimeException;
023    import org.apache.james.mime4j.util.ByteArrayBuffer;
024    
025    /**
026     * Field builders are intended to construct {@link RawField} instances from multiple lines
027     * contained in {@link ByteArrayBuffer}s.
028     * <p/>
029     * Field builders are stateful and modal as they have to store intermediate results between
030     * method invocations and also rely on a particular sequence of method invocations
031     * (the mode of operation).
032     * <p/>
033     * Consumers are expected to interact with field builder in the following way:
034     * <ul>
035     * <li>Invoke {@link #reset()} method in order to reset builder's internal state and make it
036     *   ready to start the process of building a new {@link RawField}.</li>
037     * <li>Invoke {@link #append(ByteArrayBuffer)} method one or multiple times in order to build
038     *   an internal representation of a MIME field from individual lines of text.</li>
039     * <li>Optionally {@link #getRaw()} method can be invoked in order to get combined content
040     *   of all lines processed so far. Please note builder implementations can return
041     *   <code>null</code> if they do not retain original raw content.</li>
042     * <li>Invoke {@link #build()} method in order to generate a {@link RawField} instance
043     *   based on the internal state of the builder.</li>
044     * </ul>
045     */
046    public interface FieldBuilder {
047    
048        /**
049         * Resets the internal state of the builder making it ready to process new input.
050         */
051        void reset();
052    
053        /**
054         * Updates builder's internal state by adding a new line of text.
055         */
056        void append(ByteArrayBuffer line) throws MimeException;
057    
058        /**
059         * Builds an instance of {@link RawField} based on the internal state.
060         */
061        RawField build() throws MimeException;
062    
063        /**
064         * Returns combined content of all lines processed so far or <code>null</code>
065         * if the builder does not retain original raw content.
066         */
067        ByteArrayBuffer getRaw();
068    
069    }