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