Debian Codegraph @

demo/src/main/java/README.txt

raw
1 README for the demo programs in this directory
2 ==============================================
3
4 These demo programs illustrate how to use the Jakarta Mail API to
5 perform a number of common email functions. Note these these
6 programs are not intended to be examples of good user interfaces,
7 or good command line interfaces. No one is expected to actually
8 *use* these programs for anything real. Rather, their value is
9 in the source code. Don't look at their command line arguments
10 or user interface to figure out what Jakarta Mail can do, look at
11 their source code. We strongly recommend that you read the
12 source code and understand what these programs are doing before
13 running them.
14
15 All of these programs are simple command line tools with a UNIX
16 style interface. On Windows you'll need to run them in an MS-DOS
17 window. We apologize in advance for the inconsistency in how these
18 programs accept options. There are generally two styles. The very
19 simple style (e.g., as used by copier.java) requires a fixed number
20 of arguments in a fixed order. Others (e.g., folderlist.java) take
21 UNIX-style options, many of which are optional, and which may appear
22 in any order. The following notes should help you figure it out,
23 but if in doubt, read the source code.
24
25
26
27 - copier.java
28
29 This program copies the specified messages from one folder to
30 another. Both folders must belong to the same store.
31
32 Usage:
33 java copier <urlname> <src> <dest> <start> <end>
34
35 Arguments (in order):
36
37 <urlname> : URL of the Store. The URL should include
38 the password as well (if needed).
39 Example: "imap://john:[email protected]"
40
41 <src> : source folder
42 <dest> : destination folder
43 <start> : start message number
44 <end> : end message number
45
46
47 - folderlist.java
48
49 This program lists information about the folders in a Store.
50
51 Usage:
52 java folderlist -L <url> -T <protocol> -H <host> -U <user> -P <passwd>
53 [-R <root>] [-r] [-v] [-D] <pattern>
54
55 Options:
56
57 -L <url> : URL of the Store. The URL should include
58 the password as well (if needed).
59 Example: "imap://john:[email protected]"
60 -T <protocol> : store protocol (Ex: "imap")
61 -H <host> : hostname of store.
62 -U <user> : username (if needed)
63 -P <passwd> : password (if needed)
64 -R <root> : root of the folder hierarchy. This is optional. If
65 not present, listing starts from the default folder.
66 -r : list recursively - folder and all subfolders.
67 -v : verbose - show more info about each folder.
68 -D : Turn on session debugging
69 <pattern> : folders that match this pattern are listed. Use "*"
70 as wildcard to match everything.
71
72
73 - monitor.java
74
75 Illustrates how to monitor a folder for interesting events,
76 like new mail arrival.
77
78 Usage:
79 java monitor <host> <user> <password> <mbox> <freq>
80
81 Arguments (in order):
82
83 <host> : hostname of store.
84 <user> : username (if needed)
85 <passwd> : password (if needed)
86 <mbox> : folder to monitor
87 <freq> : frequency of monitoring
88
89
90 - mover.java
91
92 Moves messages between folders. The folders must belong to the
93 same store.
94
95 Usage:
96 java mover -T <protocol> -H <host> -U <user> -P <passwd> [-v]
97 -s <src> -d <dest> [-x] <start> <end>
98
99 Options:
100
101 -T <protocol> : store protocol (Ex: "imap")
102 -H <host> : hostname of store.
103 -U <user> : username (if needed)
104 -P <passwd> : password (if needed)
105 -s <src> : source folder
106 -d <dest> : destination folder
107 -v : Optional verbose option
108 -x : Optional expunge option, to expunge the deleted
109 messages from src
110
111 Arguments (in order):
112
113 <start> : start message number
114 <end> : end message number
115
116
117 - msgmultisendsample.java
118
119 Demonstrates how to construct and send a multipart message.
120
121 Usage:
122 java msgmultisendsample <to> <from> <smtphost> true|false
123
124 Arguments (in order):
125
126 <to> : Recipient address
127 <from> : Sender address
128 <smtphost> : name of SMTP server
129 true|false : "true" to turn on session debugging, "false" otherwise
130
131
132 - msgsend.java
133
134 Send a simple text message. Optionally saves a copy
135 of the outgoing message in a folder (record-folder).
136
137 Most parameters to this program are optional. When
138 the program is run, it interactively asks for
139 the "To" and "Subject" fields if not already available.
140 Then the program expects the body of the message.
141 After you type in the body, hit Ctrl-D on Unix
142 systems or Ctrl-Z on Windows systems to send
143 the message.
144
145 Usage:
146 java msgsend -L <store-url> -T <protocol> -H <host> -U <user>
147 -P <passwd> -s <subject> -o <from> -c <cc> -b <bcc>
148 -f <record> -M <smtphost> [-d] <to>
149
150 Options:
151
152 -L <store-url> : URL of the store for the record-folder
153 -T <protocol> : If <store-url> is not present, this indicates
154 the store protocol for the record-folder.
155 -H <host> : If <store-url> is not present, this indicates
156 the hostname for the record-folder.
157 -U <user> : If <store-url> is not present, this indicates
158 the username for the record-folder.
159 -P <passwd> : If <store-url> is not present, this indicates
160 the password for the record-folder.
161 -f <record> : name of record-folder.
162 -M <smtphost> : Host name of SMTP server. Defaults to "localhost"
163 which often works on UNIX but rarely on Windows.
164 -s <subject> : Subject of message to be sent
165 -o <from> : From address of message to be sent
166 -c <cc> : Cc address of message to be sent
167 -b <bcc> : Bcc address of message to be sent
168 -d : Turn on session debugging.
169 -a <file> : Include file as an attachment with the message
170
171 Argument:
172
173 <to> : To address of message to be sent
174
175
176 - msgsendsample.java
177
178 Demonstrates how to construct and send a simple text message.
179
180 Usage:
181 java msgsendsample <to> <from> <smtphost> true|false
182
183 Arguments (in order):
184
185 <to> : Recipient address
186 <from> : Sender address
187 <smtphost> : name of SMTP server
188 true|false : "true" to turn on session debugging, "false" otherwise
189
190
191 - msgshow.java
192
193 Displays message(s) from a folder or from stdin.
194
195 Usage:
196 java msgshow -L <url> -T <protocol> -H <host> -p <port>
197 -U <user> -P <password> -f <mailbox>
198 [-D] [-s] [-S] [-a] [-v] [msgnum]
199 java msgshow -m [-D] [-s] [-S] [-v]
200
201 Options:
202
203 -L <url> : URL of the Store. The URL should include
204 the password as well (if needed).
205 Example: "imap://john:[email protected]"
206 -T <protocol> : If <url> is not present, this indicates
207 the store protocol
208 -H <host> : If <url> is not present, this indicates
209 the hostname
210 -p <port> : If <url> is not present, this indicates
211 the port number (usually not needed)
212 -U <user> : If <url> is not present, this indicates
213 the username
214 -P <passwd> : If <url> is not present, this indicates
215 the password
216 -f <mailbox> : Folder to open
217 -m : Read message from standard input
218 -D : Turn on session debugging
219 -s : Show the structure of the message, but not the contents
220 -S : Save attachments to appropriately named files
221 -a : Show ALERTS and NOTIFICATIONS from the Store
222 -v : Verbose mode - show total messages and number of new messages
223
224 Argument:
225
226 <msgnum> : the message to be displayed. If this
227 parameter is not present, all messages in the
228 folder are displayed.
229
230
231 - namespace.java
232
233 Displays the namespaces supported by a store.
234
235 Usage:
236 java namespace -L <url> -T <protocol> -H <host> -p <port>
237 -U <user> -P <password> [-D]
238
239 Options:
240
241 -L <url> : URL of the Store. The URL should include
242 the password as well (if needed).
243 Example: "imap://john:[email protected]"
244 -T <protocol> : If <url> is not present, this indicates
245 the store protocol
246 -H <host> : If <url> is not present, this indicates
247 the hostname
248 -p <port> : If <url> is not present, this indicates
249 the port number (usually not needed)
250 -U <user> : If <url> is not present, this indicates
251 the username
252 -P <passwd> : If <url> is not present, this indicates
253 the password
254 -D : Turn on session debugging
255
256
257 - populate.java
258
259 Copies an entire folder hierarchy from one message store to
260 another.
261
262 Usage:
263 java populate -s <src-url> -d <dest-url> -D -f
264
265 Options:
266
267 -s <src-url> : URL of source folder
268 -d <dest-url> : URL of destination folder
269 -D : Turn on session debugging
270 -f : force the copy to occur even if the destination
271 folder already exists
272 -S : skip special folders named "SCCS", "Drafts", "Trash", and
273 "Shared Folders"
274 -c : clear out old folders before copying messages
275 -P : don't preserve flags when copying messages
276
277
278 - registry.java
279
280 Demonstrates how to query the Jakarta Mail "registry" for providers,
281 set default providers, etc.
282
283 Usage:
284 java registry
285
286
287 - search.java
288
289 Search the given folder for messages matching the
290 given criteria. Illustrates the use of the
291 jakarta.mail.search package.
292
293 Usage:
294 java search -L <url> -T <prot> -H <host> -U <user> -P <passwd>
295 -f <folder> -subject <subject> -from <from>
296 -today -or
297
298 Options:
299
300 -L <url> : URL of the store
301 -T <protocol> : If <url> is not present, this indicates
302 the store protocol
303 -H <host> : If <url> is not present, this indicates
304 the hostname
305 -U <user> : If <url> is not present, this indicates
306 the username
307 -P <passwd> : If <url> is not present, this indicates
308 the password
309 -f <folder> : folder to search
310
311 -or : If this flag is present, the search will
312 return messages that match any one of the
313 below criteria. Else the search will only
314 return messages that match all the criteria
315
316 -subject <subject> : search for messages containing this string
317 as the Subject
318 -from <from> : search for messages containing this string
319 as the From address
320 -today : search for messages received today
321
322
323 - sendfile.java
324
325 Send the specified file to the given address. The file
326 is sent as an attachment. An SMTP server must be available.
327
328 Usage:
329 java sendfile <to> <from> <smtphost> <file> true|false
330
331 Arguments (in order):
332
333 <to> : Recipient address
334 <from> : Sender address
335 <smtphost> : name of SMTP server
336 <file> : name of file to be sent
337 true|false : "true" to turn on session debugging, "false" otherwise
338
339
340 - sendhtml.java
341
342 The sendhtml program works like the msgsend program, taking
343 the same options and input, but the text collected from the
344 user is sent as type "text/html" instead of "text/plain".
345
346 This program is a good example of how to send arbitrary
347 string data as any arbitrary MIME type.
348
349
350 - smtpsend.java
351
352 Takes the same options as the msgsend program, but illustrates
353 how to handle SMTP-specific error codes. Also accepts the
354 following options:
355
356 Option:
357
358 -v : verbose output
359 -A : use SMTP authentication
360 -S : use SSL
361
362 - transport.java
363
364 Illustrates how to use an explicit Transport object, how to
365 handle transport exceptions, and how to handle transport events.
366
367 Usage:
368 java transport <to> <from> <smtphost> <file> true|false
369
370 Arguments (in order):
371
372 <to> : Recipient address
373 <from> : Sender address
374 <smtphost> : name of SMTP server
375 <file> : name of file to be sent
376 true|false : "true" to turn on session debugging, "false" otherwise
377
378
379 - uidmsgshow.java
380
381 The uidmsgshow program works like the msgshow program, taking
382 the same options, except instead of using message numbers, it
383 uses message UID's. This will typically only work with IMAP
384 message stores.