← Back to branch summary

~ubuntu-branches/ubuntu/saucy/apache-mime4j/saucy

« back to all changes in this revision

Viewing changes to src/site/apt/usage.apt

  • Committer: Bazaar Package Importer
  • Author(s): David Paleino
  • Date: 2010-07-13 09:28:28 UTC
  • Revision ID: james.westby@ubuntu.com-20100713092828-g6wafdtidgmtx7su
Tags: upstream-0.6
Import upstream version 0.6

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/site/apt/usage.apt
 
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
 Usage
 
21
 -------------
 
22
 
 
23
{Usage}
 
24
 
 
25
  Mime4j provides two different API's: An event based API by using
 
26
  the {{{apidocs/org/apache/james/mime4j/parser/MimeStreamParser.html}
 
27
  MimeStreamParser}}. Alternatively, you may use the iterative
 
28
  API, which is available through the
 
29
  {{{apidocs/org/apache/james/mime4j/parser/MimeTokenStream.html}
 
30
  MimeTokenStream}}. In terms of speed, you should not note
 
31
  any differences.
 
32
 
 
33
  * {{{#Token Streams}Token Streams}}
 
34
 
 
35
  * {{{#Sample Token Stream}Sample Token Stream}}
 
36
 
 
37
  * {{{#Event Handlers}Event Handlers}}
 
38
 
 
39
  * {{{#Sample Event Stream}Sample Event Stream}}
 
40
 
 
41
{Token Streams}
 
42
 
 
43
  The iterative approach is using the class
 
44
  {{{apidocs/org/apache/james/mime4j/parser/MimeTokenStream.html}
 
45
  MimeTokenStream}}. Here's an example, how you could use
 
46
  the token stream:
 
47
 
 
48
--------------------------------------------------------------------
 
49
  MimeTokenStream stream = new MimeTokenStream();
 
50
  stream.parse(new BufferedInputStream(new FileInputStream("mime.msg")));
 
51
  for (int state = stream.getState();
 
52
       state != MimeTokenStream.T_END_OF_STREAM;
 
53
       state = stream.next()) {
 
54
    switch (state) {
 
55
      case MimeTokenStream.T_BODY:
 
56
        System.out.println("Body detected, contents = "
 
57
          + stream.getInputStream() + ", header data = "
 
58
          + stream.getBodyDescriptor());
 
59
        break;
 
60
      case MimeTokenStream.T_FIELD:
 
61
        System.out.println("Header field detected: "
 
62
          + stream.getField());
 
63
        break;
 
64
      case MimeTokenStream.T_START_MULTIPART:
 
65
        System.out.println("Multipart message detexted,"
 
66
          + " header data = "
 
67
          + stream.getBodyDescriptor());
 
68
      ...
 
69
    }
 
70
  }
 
71
--------------------------------------------------------------------  
 
72
 
 
73
  The token stream provides a set of tokens. Tokens are identified
 
74
  by a state. Most states are simply event indicators, with no
 
75
  additional data available. However, there are some states,
 
76
  which provide additional data. For example, the state
 
77
  <<<T_BODY>>>, which indicates that an actual body is available,
 
78
  If you note this state, then you may ask for the bodies contents,
 
79
  which are provided through the <<<getInputStream()>>> method,
 
80
  or you might ask for the header data by invoking
 
81
  <<<getBodyDescriptor()>>>.
 
82
 
 
83
{Sample Token Stream}
 
84
 
 
85
  The following sample should give you a rough idea of the order,
 
86
  in which you'll receive tokens:
 
87
 
 
88
--------------------------------------------------------------------  
 
89
  T_START_MESSAGE
 
90
      T_START_HEADER
 
91
          T_FIELD
 
92
          T_FIELD
 
93
          ...
 
94
      T_END_HEADER
 
95
      T_START_MULTIPART
 
96
          T_PREAMBLE
 
97
          T_START_BODYPART
 
98
              T_START_HEADER
 
99
                  T_FIELD
 
100
                  T_FIELD
 
101
                  ...
 
102
              T_END_HEADER
 
103
              T_BODY
 
104
          T_END_BODYPART
 
105
          T_START_BODYPART
 
106
              T_START_HEADER
 
107
                  T_FIELD
 
108
                  T_FIELD
 
109
                  ...
 
110
              T_END_HEADER
 
111
              T_BODY
 
112
          T_END_BODYPART
 
113
          T_EPILOGUE
 
114
      T_END_MULTIPART
 
115
   T_END_MESSAGE
 
116
--------------------------------------------------------------------  
 
117
 
 
118
  The example shows a multipart message with two parts.
 
119
 
 
120
{Event Handlers}
 
121
 
 
122
  The event based API requires, that you provide an event handler,
 
123
  which receives events. The event handler is an object, which
 
124
  implements the {{{apidocs/org/apache/james/mime4j/parser/ContentHandler.html}
 
125
  ContentHandler}} interface. Here's an example, how you could
 
126
  implement an event handler:
 
127
 
 
128
--------------------------------------------------------------------  
 
129
  public class MyContentHandler extends org.apache.james.mime4j.parser.ContentHandler {
 
130
      public body(BodyDescriptor bd, InputStream is)
 
131
              throws MimeException, IOException {
 
132
          System.out.println("Body detected, contents = "
 
133
              + is + ", header data = " + bd);
 
134
      }
 
135
      public void field(String fieldData) throws MimeException {
 
136
          System.out.println("Header field detected: "
 
137
              + fieldData);
 
138
      }
 
139
      public void startMultipart(BodyDescriptor bd) throws MimeException {
 
140
          System.out.println("Multipart message detexted, header data = "
 
141
              + bd);
 
142
      }
 
143
      ...
 
144
  }
 
145
--------------------------------------------------------------------  
 
146
 
 
147
  A little bit of additional code allows us to create an example, which
 
148
  is functionally equivalent to the example from the section on
 
149
  {{{#Token Streams}Token Streams}}:
 
150
 
 
151
--------------------------------------------------------------------  
 
152
  ContentHandler handler = new MyContentHandler();
 
153
  MimeStreamParser parser = new MimeStreamParser();
 
154
  parser.setContentHandler(handler);
 
155
  parser.parse(new BufferedInputStream(new FileInputStream("mime.msg")));
 
156
--------------------------------------------------------------------  
 
157
 
 
158
{Sample Event Stream}
 
159
 
 
160
  Like above for tokens, we provide an additional example, which
 
161
  demonstrates the typical order of events that you have to expect:
 
162
 
 
163
--------------------------------------------------------------------
 
164
  startMessage()
 
165
      startHeader()
 
166
          field(...)
 
167
          field(...)
 
168
          ...
 
169
      endHeader()
 
170
      startMultipart()
 
171
          preamble(...)
 
172
          startBodyPart()
 
173
              startHeader()
 
174
                  field(...)
 
175
                  field(...)
 
176
                  ...
 
177
              endHeader()
 
178
              body()
 
179
          endBodyPart()
 
180
          startBodyPart()
 
181
              startHeader()
 
182
                  field(...)
 
183
                  field(...)
 
184
                  ...
 
185
              endHeader()
 
186
              body()
 
187
          endBodyPart()
 
188
          epilogue(...)
 
189
      endMultipart()
 
190
  endMessage()
 
191
--------------------------------------------------------------------