← Back to branch summary

~ubuntu-branches/ubuntu/utopic/apache-mime4j/utopic-proposed

« back to all changes in this revision

Viewing changes to core/src/main/java/org/apache/james/mime4j/stream/BodyDescriptorBuilder.java

  • Committer: Package Import Robot
  • Author(s): David Paleino
  • Date: 2013-11-03 11:13:27 UTC
  • mfrom: (2.1.2 experimental)
  • Revision ID: package-import@ubuntu.com-20131103111327-09huep00ex05z113
Tags: 0.7.2-2
* Upload to unstable
* Fixed Vcs-* fields in debian/control
* Updated debian/watch
* Standards-Version bump to 3.9.5, no changes needed

Show diffs side-by-side

added added

removed removed

Lines of Context:
core/src/main/java/org/apache/james/mime4j/stream/BodyDescriptorBuilder.java
 
1
/****************************************************************
 
2
 * Licensed to the Apache Software Foundation (ASF) under one   *
 
3
 * or more contributor license agreements.  See the NOTICE file *
 
4
 * distributed with this work for additional information        *
 
5
 * regarding copyright ownership.  The ASF licenses this file   *
 
6
 * to you under the Apache License, Version 2.0 (the            *
 
7
 * "License"); you may not use this file except in compliance   *
 
8
 * with the License.  You may obtain a copy of the License at   *
 
9
 *                                                              *
 
10
 *   http://www.apache.org/licenses/LICENSE-2.0                 *
 
11
 *                                                              *
 
12
 * Unless required by applicable law or agreed to in writing,   *
 
13
 * software distributed under the License is distributed on an  *
 
14
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
 
15
 * KIND, either express or implied.  See the License for the    *
 
16
 * specific language governing permissions and limitations      *
 
17
 * under the License.                                           *
 
18
 ****************************************************************/
 
19
 
 
20
package org.apache.james.mime4j.stream;
 
21
 
 
22
import org.apache.james.mime4j.MimeException;
 
23
 
 
24
/**
 
25
 * Body descriptor builders are intended to construct {@link BodyDescriptor} instances from
 
26
 * multiple unstructured {@link RawField}s.
 
27
 * <p/>
 
28
 * Body descriptor builders are stateful and modal as they have to store intermediate results
 
29
 * between method invocations and also rely on a particular sequence of method invocations
 
30
 * (the mode of operation).
 
31
 * <p/>
 
32
 * Consumers are expected to interact with body descriptor builders in the following way:
 
33
 * <ul>
 
34
 * <li>Invoke {@link #reset()} method in order to reset builder's internal state and make it
 
35
 *   ready to start the process of building a new {@link BodyDescriptor}.</li>
 
36
 * <li>Invoke {@link #addField(RawField)} multiple times method in order to collect
 
37
 *   necessary details for building a body descriptor. The builder can optionally
 
38
 *   transform the unstructured field given an an input into a structured one and return
 
39
 *   an instance {@link Field} that also implements a richer interface for a particular type
 
40
 *   of fields such as <code>Content-Type</code>. The builder can also return <code>null</code>
 
41
 *   if the field is to be ignored</li>
 
42
 * <li>Optionally invoke {@link #newChild()} for each embedded body of content. Please note that
 
43
 *   the resultant {@link BodyDescriptorBuilder}} child instance can inherit some its parent
 
44
 *   properties such as MIME type.</li>
 
45
 * <li>Invoke {@link #build()()} method in order to generate a {@link BodyDescriptor}} instance
 
46
 *   based on the internal state of the builder.</li>
 
47
 * </ul>
 
48
 */
 
49
public interface BodyDescriptorBuilder {
 
50
 
 
51
    /**
 
52
     * Resets the internal state of the builder making it ready to process new input.
 
53
     */
 
54
    void reset();
 
55
 
 
56
    /**
 
57
     * Updates builder's internal state by adding a new field. The builder can optionally
 
58
     * transform the unstructured field given an an input into a structured one and return
 
59
     * an instance {@link Field} that also implements a richer interface for a particular type
 
60
     * of fields such as <code>Content-Type</code>. The builder can also return <code>null</code>
 
61
     * if the field is to be ignored.
 
62
     */
 
63
    Field addField(RawField field) throws MimeException;
 
64
 
 
65
    /**
 
66
     * Builds an instance of {@link BodyDescriptor} based on the internal state.
 
67
     */
 
68
    BodyDescriptor build();
 
69
 
 
70
    /**
 
71
     * Creates an instance of {@link BodyDescriptorBuilder} to be used for processing of an
 
72
     * embedded content body. Please the child instance can inherit some of its parent properties
 
73
     * such as MIME type.
 
74
     */
 
75
    BodyDescriptorBuilder newChild();
 
76
 
 
77
}