%line	%branch
org.apache.commons.net.smtp.SMTPClient	0%	0%

1		/*
2		* Copyright 2001-2005 The Apache Software Foundation
3		*
4		* Licensed under the Apache License, Version 2.0 (the "License");
5		* you may not use this file except in compliance with the License.
6		* You may obtain a copy of the License at
7		*
8		* http://www.apache.org/licenses/LICENSE-2.0
9		*
10		* Unless required by applicable law or agreed to in writing, software
11		* distributed under the License is distributed on an "AS IS" BASIS,
12		* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13		* See the License for the specific language governing permissions and
14		* limitations under the License.
15		*/
16		package org.apache.commons.net.smtp;
17
18		import java.io.IOException;
19		import java.io.Writer;
20		import java.net.InetAddress;
21		import org.apache.commons.net.io.DotTerminatedMessageWriter;
22
23		/***
24		* SMTPClient encapsulates all the functionality necessary to send files
25		* through an SMTP server. This class takes care of all
26		* low level details of interacting with an SMTP server and provides
27		* a convenient higher level interface. As with all classes derived
28		* from {@link org.apache.commons.net.SocketClient},
29		* you must first connect to the server with
30		* {@link org.apache.commons.net.SocketClient#connect connect }
31		* before doing anything, and finally
32		* {@link org.apache.commons.net.SocketClient#disconnect disconnect }
33		* after you're completely finished interacting with the server.
34		* Then you need to check the SMTP reply code to see if the connection
35		* was successful. For example:
36		* <pre>
37		* try {
38		* int reply;
39		* client.connect("mail.foobar.com");
40		* System.out.print(client.getReplyString());
41		*
42		* // After connection attempt, you should check the reply code to verify
43		* // success.
44		* reply = client.getReplyCode();
45		*
46		* if(!SMTPReply.isPositiveCompletion(reply)) {
47		* client.disconnect();
48		* System.err.println("SMTP server refused connection.");
49		* System.exit(1);
50		* }
51		*
52		* // Do useful stuff here.
53		* ...
54		* } catch(IOException e) {
55		* if(client.isConnected()) {
56		* try {
57		* client.disconnect();
58		* } catch(IOException f) {
59		* // do nothing
60		* }
61		* }
62		* System.err.println("Could not connect to server.");
63		* e.printStackTrace();
64		* System.exit(1);
65		* }
66		* </pre>
67		* <p>
68		* Immediately after connecting is the only real time you need to check the
69		* reply code (because connect is of type void). The convention for all the
70		* SMTP command methods in SMTPClient is such that they either return a
71		* boolean value or some other value.
72		* The boolean methods return true on a successful completion reply from
73		* the SMTP server and false on a reply resulting in an error condition or
74		* failure. The methods returning a value other than boolean return a value
75		* containing the higher level data produced by the SMTP command, or null if a
76		* reply resulted in an error condition or failure. If you want to access
77		* the exact SMTP reply code causing a success or failure, you must call
78		* {@link org.apache.commons.net.smtp.SMTP#getReplyCode getReplyCode } after
79		* a success or failure.
80		* <p>
81		* You should keep in mind that the SMTP server may choose to prematurely
82		* close a connection for various reasons. The SMTPClient class will detect a
83		* premature SMTP server connection closing when it receives a
84		* {@link org.apache.commons.net.smtp.SMTPReply#SERVICE_NOT_AVAILABLE SMTPReply.SERVICE_NOT_AVAILABLE }
85		* response to a command.
86		* When that occurs, the method encountering that reply will throw
87		* an {@link org.apache.commons.net.smtp.SMTPConnectionClosedException}
88		* .
89		* <code>SMTPConectionClosedException</code>
90		* is a subclass of <code> IOException </code> and therefore need not be
91		* caught separately, but if you are going to catch it separately, its
92		* catch block must appear before the more general <code> IOException </code>
93		* catch block. When you encounter an
94		* {@link org.apache.commons.net.smtp.SMTPConnectionClosedException}
95		* , you must disconnect the connection with
96		* {@link #disconnect disconnect() } to properly clean up the
97		* system resources used by SMTPClient. Before disconnecting, you may check
98		* the last reply code and text with
99		* {@link org.apache.commons.net.smtp.SMTP#getReplyCode getReplyCode },
100		* {@link org.apache.commons.net.smtp.SMTP#getReplyString getReplyString },
101		* and
102		* {@link org.apache.commons.net.smtp.SMTP#getReplyStrings getReplyStrings}.
103		* <p>
104		* Rather than list it separately for each method, we mention here that
105		* every method communicating with the server and throwing an IOException
106		* can also throw a
107		* {@link org.apache.commons.net.MalformedServerReplyException}
108		* , which is a subclass
109		* of IOException. A MalformedServerReplyException will be thrown when
110		* the reply received from the server deviates enough from the protocol
111		* specification that it cannot be interpreted in a useful manner despite
112		* attempts to be as lenient as possible.
113		* <p>
114		* <p>
115		* @author Daniel F. Savarese
116		* @see SMTP
117		* @see SimpleSMTPHeader
118		* @see RelayPath
119		* @see SMTPConnectionClosedException
120		* @see org.apache.commons.net.MalformedServerReplyException
121		***/
122
123	0	public class SMTPClient extends SMTP
124		{
125
126		/*
127		* Default SMTPClient constructor. Creates a new SMTPClient instance.
128		*/
129		//public SMTPClient() { }
130
131
132		/***
133		* At least one SMTPClient method ({@link #sendMessageData sendMessageData })
134		* does not complete the entire sequence of SMTP commands to complete a
135		* transaction. These types of commands require some action by the
136		* programmer after the reception of a positive intermediate command.
137		* After the programmer's code completes its actions, it must call this
138		* method to receive the completion reply from the server and verify the
139		* success of the entire transaction.
140		* <p>
141		* For example,
142		* <pre>
143		* writer = client.sendMessage();
144		* if(writer == null) // failure
145		* return false;
146		* header =
147		* new SimpleSMTPHeader("foobar@foo.com", "foo@foobar.com", "Re: Foo");
148		* writer.write(header.toString());
149		* writer.write("This is just a test");
150		* writer.close();
151		* if(!client.completePendingCommand()) // failure
152		* return false;
153		* </pre>
154		* <p>
155		* @return True if successfully completed, false if not.
156		* @exception SMTPConnectionClosedException
157		* If the SMTP server prematurely closes the connection as a result
158		* of the client being idle or some other reason causing the server
159		* to send SMTP reply code 421. This exception may be caught either
160		* as an IOException or independently as itself.
161		* @exception IOException If an I/O error occurs while either sending a
162		* command to the server or receiving a reply from the server.
163		***/
164		public boolean completePendingCommand() throws IOException
165		{
166	0	return SMTPReply.isPositiveCompletion(getReply());
167		}
168
169
170		/***
171		* Login to the SMTP server by sending the HELO command with the
172		* given hostname as an argument. Before performing any mail commands,
173		* you must first login.
174		* <p>
175		* @param hostname The hostname with which to greet the SMTP server.
176		* @return True if successfully completed, false if not.
177		* @exception SMTPConnectionClosedException
178		* If the SMTP server prematurely closes the connection as a result
179		* of the client being idle or some other reason causing the server
180		* to send SMTP reply code 421. This exception may be caught either
181		* as an IOException or independently as itself.
182		* @exception IOException If an I/O error occurs while either sending a
183		* command to the server or receiving a reply from the server.
184		***/
185		public boolean login(String hostname) throws IOException
186		{
187	0	return SMTPReply.isPositiveCompletion(helo(hostname));
188		}
189
190
191		/***
192		* Login to the SMTP server by sending the HELO command with the
193		* client hostname as an argument. Before performing any mail commands,
194		* you must first login.
195		* <p>
196		* @return True if successfully completed, false if not.
197		* @exception SMTPConnectionClosedException
198		* If the SMTP server prematurely closes the connection as a result
199		* of the client being idle or some other reason causing the server
200		* to send SMTP reply code 421. This exception may be caught either
201		* as an IOException or independently as itself.
202		* @exception IOException If an I/O error occurs while either sending a
203		* command to the server or receiving a reply from the server.
204		***/
205		public boolean login() throws IOException
206		{
207		String name;
208		InetAddress host;
209
210	0	host = getLocalAddress();
211	0	name = host.getHostName();
212
213	0	if (name == null)
214	0	return false;
215
216	0	return SMTPReply.isPositiveCompletion(helo(name));
217		}
218
219
220		/***
221		* Set the sender of a message using the SMTP MAIL command, specifying
222		* a reverse relay path. The sender must be set first before any
223		* recipients may be specified, otherwise the mail server will reject
224		* your commands.
225		* <p>
226		* @param path The reverse relay path pointing back to the sender.
227		* @return True if successfully completed, false if not.
228		* @exception SMTPConnectionClosedException
229		* If the SMTP server prematurely closes the connection as a result
230		* of the client being idle or some other reason causing the server
231		* to send SMTP reply code 421. This exception may be caught either
232		* as an IOException or independently as itself.
233		* @exception IOException If an I/O error occurs while either sending a
234		* command to the server or receiving a reply from the server.
235		***/
236		public boolean setSender(RelayPath path) throws IOException
237		{
238	0	return SMTPReply.isPositiveCompletion(mail(path.toString()));
239		}
240
241
242		/***
243		* Set the sender of a message using the SMTP MAIL command, specifying
244		* the sender's email address. The sender must be set first before any
245		* recipients may be specified, otherwise the mail server will reject
246		* your commands.
247		* <p>
248		* @param address The sender's email address.
249		* @return True if successfully completed, false if not.
250		* @exception SMTPConnectionClosedException
251		* If the SMTP server prematurely closes the connection as a result
252		* of the client being idle or some other reason causing the server
253		* to send SMTP reply code 421. This exception may be caught either
254		* as an IOException or independently as itself.
255		* @exception IOException If an I/O error occurs while either sending a
256		* command to the server or receiving a reply from the server.
257		***/
258		public boolean setSender(String address) throws IOException
259		{
260	0	return SMTPReply.isPositiveCompletion(mail("<" + address + ">"));
261		}
262
263
264		/***
265		* Add a recipient for a message using the SMTP RCPT command, specifying
266		* a forward relay path. The sender must be set first before any
267		* recipients may be specified, otherwise the mail server will reject
268		* your commands.
269		* <p>
270		* @param path The forward relay path pointing to the recipient.
271		* @return True if successfully completed, false if not.
272		* @exception SMTPConnectionClosedException
273		* If the SMTP server prematurely closes the connection as a result
274		* of the client being idle or some other reason causing the server
275		* to send SMTP reply code 421. This exception may be caught either
276		* as an IOException or independently as itself.
277		* @exception IOException If an I/O error occurs while either sending a
278		* command to the server or receiving a reply from the server.
279		***/
280		public boolean addRecipient(RelayPath path) throws IOException
281		{
282	0	return SMTPReply.isPositiveCompletion(rcpt(path.toString()));
283		}
284
285
286		/***
287		* Add a recipient for a message using the SMTP RCPT command, the
288		* recipient's email address. The sender must be set first before any
289		* recipients may be specified, otherwise the mail server will reject
290		* your commands.
291		* <p>
292		* @param address The recipient's email address.
293		* @return True if successfully completed, false if not.
294		* @exception SMTPConnectionClosedException
295		* If the SMTP server prematurely closes the connection as a result
296		* of the client being idle or some other reason causing the server
297		* to send SMTP reply code 421. This exception may be caught either
298		* as an IOException or independently as itself.
299		* @exception IOException If an I/O error occurs while either sending a
300		* command to the server or receiving a reply from the server.
301		***/
302		public boolean addRecipient(String address) throws IOException
303		{
304	0	return SMTPReply.isPositiveCompletion(rcpt("<" + address + ">"));
305		}
306
307
308
309		/***
310		* Send the SMTP DATA command in preparation to send an email message.
311		* This method returns a DotTerminatedMessageWriter instance to which
312		* the message can be written. Null is returned if the DATA command
313		* fails.
314		* <p>
315		* You must not issue any commands to the SMTP server (i.e., call any
316		* (other methods) until you finish writing to the returned Writer
317		* instance and close it. The SMTP protocol uses the same stream for
318		* issuing commands as it does for returning results. Therefore the
319		* returned Writer actually writes directly to the SMTP connection.
320		* After you close the writer, you can execute new commands. If you
321		* do not follow these requirements your program will not work properly.
322		* <p>
323		* You can use the provided
324		* {@link org.apache.commons.net.smtp.SimpleSMTPHeader}
325		* class to construct a bare minimum header.
326		* To construct more complicated headers you should
327		* refer to RFC 822. When the Java Mail API is finalized, you will be
328		* able to use it to compose fully compliant Internet text messages.
329		* The DotTerminatedMessageWriter takes care of doubling line-leading
330		* dots and ending the message with a single dot upon closing, so all
331		* you have to worry about is writing the header and the message.
332		* <p>
333		* Upon closing the returned Writer, you need to call
334		* {@link #completePendingCommand completePendingCommand() }
335		* to finalize the transaction and verify its success or failure from
336		* the server reply.
337		* <p>
338		* @return A DotTerminatedMessageWriter to which the message (including
339		* header) can be written. Returns null if the command fails.
340		* @exception SMTPConnectionClosedException
341		* If the SMTP server prematurely closes the connection as a result
342		* of the client being idle or some other reason causing the server
343		* to send SMTP reply code 421. This exception may be caught either
344		* as an IOException or independently as itself.
345		* @exception IOException If an I/O error occurs while either sending a
346		* command to the server or receiving a reply from the server.
347		***/
348		public Writer sendMessageData() throws IOException
349		{
350	0	if (!SMTPReply.isPositiveIntermediate(data()))
351	0	return null;
352
353	0	return new DotTerminatedMessageWriter(_writer);
354		}
355
356
357		/***
358		* A convenience method for sending short messages. This method fetches
359		* the Writer returned by {@link #sendMessageData sendMessageData() }
360		* and writes the specified String to it. After writing the message,
361		* this method calls {@link #completePendingCommand completePendingCommand() }
362		* to finalize the transaction and returns
363		* its success or failure.
364		* <p>
365		* @param message The short email message to send.
366		* @return True if successfully completed, false if not.
367		* @exception SMTPConnectionClosedException
368		* If the SMTP server prematurely closes the connection as a result
369		* of the client being idle or some other reason causing the server
370		* to send SMTP reply code 421. This exception may be caught either
371		* as an IOException or independently as itself.
372		* @exception IOException If an I/O error occurs while either sending a
373		* command to the server or receiving a reply from the server.
374		***/
375		public boolean sendShortMessageData(String message) throws IOException
376		{
377		Writer writer;
378
379	0	writer = sendMessageData();
380
381	0	if (writer == null)
382	0	return false;
383
384	0	writer.write(message);
385	0	writer.close();
386
387	0	return completePendingCommand();
388		}
389
390
391		/***
392		* A convenience method for a sending short email without having to
393		* explicitly set the sender and recipient(s). This method
394		* sets the sender and recipient using
395		* {@link #setSender setSender } and
396		* {@link #addRecipient addRecipient }, and then sends the
397		* message using {@link #sendShortMessageData sendShortMessageData }.
398		* <p>
399		* @param sender The email address of the sender.
400		* @param recipient The email address of the recipient.
401		* @param message The short email message to send.
402		* @return True if successfully completed, false if not.
403		* @exception SMTPConnectionClosedException
404		* If the SMTP server prematurely closes the connection as a result
405		* of the client being idle or some other reason causing the server
406		* to send SMTP reply code 421. This exception may be caught either
407		* as an IOException or independently as itself.
408		* @exception IOException If an I/O error occurs while either sending a
409		* command to the server or receiving a reply from the server.
410		***/
411		public boolean sendSimpleMessage(String sender, String recipient,
412		String message)
413		throws IOException
414		{
415	0	if (!setSender(sender))
416	0	return false;
417
418	0	if (!addRecipient(recipient))
419	0	return false;
420
421	0	return sendShortMessageData(message);
422		}
423
424
425
426		/***
427		* A convenience method for a sending short email without having to
428		* explicitly set the sender and recipient(s). This method
429		* sets the sender and recipients using
430		* {@link #setSender setSender } and
431		* {@link #addRecipient addRecipient }, and then sends the
432		* message using {@link #sendShortMessageData sendShortMessageData }.
433		* <p>
434		* @param sender The email address of the sender.
435		* @param recipients An array of recipient email addresses.
436		* @param message The short email message to send.
437		* @return True if successfully completed, false if not.
438		* @exception SMTPConnectionClosedException
439		* If the SMTP server prematurely closes the connection as a result
440		* of the client being idle or some other reason causing the server
441		* to send SMTP reply code 421. This exception may be caught either
442		* as an IOException or independently as itself.
443		* @exception IOException If an I/O error occurs while either sending a
444		* command to the server or receiving a reply from the server.
445		***/
446		public boolean sendSimpleMessage(String sender, String[] recipients,
447		String message)
448		throws IOException
449		{
450	0	boolean oneSuccess = false;
451		int count;
452
453	0	if (!setSender(sender))
454	0	return false;
455
456	0	for (count = 0; count < recipients.length; count++)
457		{
458	0	if (addRecipient(recipients[count]))
459	0	oneSuccess = true;
460		}
461
462	0	if (!oneSuccess)
463	0	return false;
464
465	0	return sendShortMessageData(message);
466		}
467
468
469		/***
470		* Logout of the SMTP server by sending the QUIT command.
471		* <p>
472		* @return True if successfully completed, false if not.
473		* @exception SMTPConnectionClosedException
474		* If the SMTP server prematurely closes the connection as a result
475		* of the client being idle or some other reason causing the server
476		* to send SMTP reply code 421. This exception may be caught either
477		* as an IOException or independently as itself.
478		* @exception IOException If an I/O error occurs while either sending a
479		* command to the server or receiving a reply from the server.
480		***/
481		public boolean logout() throws IOException
482		{
483	0	return SMTPReply.isPositiveCompletion(quit());
484		}
485
486
487
488		/***
489		* Aborts the current mail transaction, resetting all server stored
490		* sender, recipient, and mail data, cleaing all buffers and tables.
491		* <p>
492		* @return True if successfully completed, false if not.
493		* @exception SMTPConnectionClosedException
494		* If the SMTP server prematurely closes the connection as a result
495		* of the client being idle or some other reason causing the server
496		* to send SMTP reply code 421. This exception may be caught either
497		* as an IOException or independently as itself.
498		* @exception IOException If an I/O error occurs while either sending a
499		* command to the server or receiving a reply from the server.
500		***/
501		public boolean reset() throws IOException
502		{
503	0	return SMTPReply.isPositiveCompletion(rset());
504		}
505
506
507		/***
508		* Verify that a username or email address is valid, i.e., that mail
509		* can be delivered to that mailbox on the server.
510		* <p>
511		* @param username The username or email address to validate.
512		* @return True if the username is valid, false if not.
513		* @exception SMTPConnectionClosedException
514		* If the SMTP server prematurely closes the connection as a result
515		* of the client being idle or some other reason causing the server
516		* to send SMTP reply code 421. This exception may be caught either
517		* as an IOException or independently as itself.
518		* @exception IOException If an I/O error occurs while either sending a
519		* command to the server or receiving a reply from the server.
520		***/
521		public boolean verify(String username) throws IOException
522		{
523		int result;
524
525	0	result = vrfy(username);
526
527	0	return (result == SMTPReply.ACTION_OK ||
528		result == SMTPReply.USER_NOT_LOCAL_WILL_FORWARD);
529		}
530
531
532		/***
533		* Fetches the system help information from the server and returns the
534		* full string.
535		* <p>
536		* @return The system help string obtained from the server. null if the
537		* information could not be obtained.
538		* @exception SMTPConnectionClosedException
539		* If the SMTP server prematurely closes the connection as a result
540		* of the client being idle or some other reason causing the server
541		* to send SMTP reply code 421. This exception may be caught either
542		* as an IOException or independently as itself.
543		* @exception IOException If an I/O error occurs while either sending a
544		* command to the server or receiving a reply from the server.
545		***/
546		public String listHelp() throws IOException
547		{
548	0	if (SMTPReply.isPositiveCompletion(help()))
549	0	return getReplyString();
550	0	return null;
551		}
552
553
554		/***
555		* Fetches the help information for a given command from the server and
556		* returns the full string.
557		* <p>
558		* @param command The command on which to ask for help.
559		* @return The command help string obtained from the server. null if the
560		* information could not be obtained.
561		* @exception SMTPConnectionClosedException
562		* If the SMTP server prematurely closes the connection as a result
563		* of the client being idle or some other reason causing the server
564		* to send SMTP reply code 421. This exception may be caught either
565		* as an IOException or independently as itself.
566		* @exception IOException If an I/O error occurs while either sending a
567		* command to the server or receiving a reply from the server.
568		***/
569		public String listHelp(String command) throws IOException
570		{
571	0	if (SMTPReply.isPositiveCompletion(help(command)))
572	0	return getReplyString();
573	0	return null;
574		}
575
576
577		/***
578		* Sends a NOOP command to the SMTP server. This is useful for preventing
579		* server timeouts.
580		* <p>
581		* @return True if successfully completed, false if not.
582		* @exception SMTPConnectionClosedException
583		* If the SMTP server prematurely closes the connection as a result
584		* of the client being idle or some other reason causing the server
585		* to send SMTP reply code 421. This exception may be caught either
586		* as an IOException or independently as itself.
587		* @exception IOException If an I/O error occurs while either sending a
588		* command to the server or receiving a reply from the server.
589		***/
590		public boolean sendNoOp() throws IOException
591		{
592	0	return SMTPReply.isPositiveCompletion(noop());
593		}
594
595		}

This report is generated by jcoverage, Maven and Maven JCoverage Plugin.