Return-Path: X-Original-To: apmail-commons-notifications-archive@minotaur.apache.org Delivered-To: apmail-commons-notifications-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 84CBB17841 for ; Sat, 23 May 2015 06:51:05 +0000 (UTC) Received: (qmail 89200 invoked by uid 500); 23 May 2015 06:51:05 -0000 Delivered-To: apmail-commons-notifications-archive@commons.apache.org Received: (qmail 89161 invoked by uid 500); 23 May 2015 06:51:05 -0000 Mailing-List: contact notifications-help@commons.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@commons.apache.org Delivered-To: mailing list notifications@commons.apache.org Received: (qmail 88925 invoked by uid 99); 23 May 2015 06:51:05 -0000 Received: from eris.apache.org (HELO hades.apache.org) (140.211.11.105) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 23 May 2015 06:51:05 +0000 Received: from hades.apache.org (localhost [127.0.0.1]) by hades.apache.org (ASF Mail Server at hades.apache.org) with ESMTP id 3CBE9AC0735 for ; Sat, 23 May 2015 06:51:05 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r952406 [37/42] - in /websites/production/commons/content/proper/commons-email: ./ apidocs/ apidocs/org/apache/commons/mail/ apidocs/org/apache/commons/mail/class-use/ apidocs/org/apache/commons/mail/resolver/ apidocs/org/apache/commons/mai... Date: Sat, 23 May 2015 06:51:00 -0000 To: notifications@commons.apache.org From: tn@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20150523065105.3CBE9AC0735@hades.apache.org> Modified: websites/production/commons/content/proper/commons-email/xref/org/apache/commons/mail/Email.html ============================================================================== --- websites/production/commons/content/proper/commons-email/xref/org/apache/commons/mail/Email.html (original) +++ websites/production/commons/content/proper/commons-email/xref/org/apache/commons/mail/Email.html Sat May 23 06:50:57 2015 @@ -57,7 +57,7 @@ 49 * Subclasses are responsible for setting the message body. 50 * 51 * @since 1.0 -52 * @version $Id: Email.java 1606709 2014-06-30 12:26:06Z ggregory $ +52 * @version $Id: Email.java 1665699 2015-03-10 21:12:09Z tn $ 53 */ 54 public abstract class Email 55 { @@ -1223,723 +1223,734 @@ 1215 } 1216 1217 /** -1218 * Set the "bounce address" - the address to which undeliverable messages -1219 * will be returned. If this value is never set, then the message will be -1220 * sent to the address specified with the System property "mail.smtp.from", -1221 * or if that value is not set, then to the "from" address. -1222 * -1223 * @param email A String. -1224 * @return An Email. -1225 * @throws IllegalStateException when the mail session is already initialized -1226 * @since 1.0 -1227 */ -1228 public Email setBounceAddress(final String email) -1229 { -1230 checkSessionAlreadyInitialized(); -1231 this.bounceAddress = email; -1232 return this; -1233 } -1234 -1235 -1236 /** -1237 * Define the content of the mail. It should be overridden by the -1238 * subclasses. -1239 * -1240 * @param msg A String. -1241 * @return An Email. -1242 * @throws EmailException generic exception. -1243 * @since 1.0 -1244 */ -1245 public abstract Email setMsg(String msg) throws EmailException; -1246 -1247 /** -1248 * Does the work of actually building the MimeMessage. Please note that -1249 * a user rarely calls this method directly and only if he/she is -1250 * interested in the sending the underlying MimeMessage without -1251 * commons-email. -1252 * -1253 * @throws IllegalStateException if the MimeMessage was already built -1254 * @throws EmailException if there was an error. -1255 * @since 1.0 -1256 */ -1257 public void buildMimeMessage() throws EmailException -1258 { -1259 if (this.message != null) -1260 { -1261 // [EMAIL-95] we assume that an email is not reused therefore invoking -1262 // buildMimeMessage() more than once is illegal. -1263 throw new IllegalStateException("The MimeMessage is already built."); -1264 } -1265 -1266 try -1267 { -1268 this.message = this.createMimeMessage(this.getMailSession()); -1269 -1270 if (EmailUtils.isNotEmpty(this.subject)) -1271 { -1272 if (EmailUtils.isNotEmpty(this.charset)) -1273 { -1274 this.message.setSubject(this.subject, this.charset); -1275 } -1276 else -1277 { -1278 this.message.setSubject(this.subject); -1279 } -1280 } -1281 -1282 // update content type (and encoding) -1283 this.updateContentType(this.contentType); -1284 -1285 if (this.content != null) -1286 { -1287 if (EmailConstants.TEXT_PLAIN.equalsIgnoreCase(this.contentType) -1288 && this.content instanceof String) -1289 { -1290 // EMAIL-104: call explicitly setText to use default mime charset -1291 // (property "mail.mime.charset") in case none has been set -1292 this.message.setText(this.content.toString(), this.charset); -1293 } -1294 else -1295 { -1296 this.message.setContent(this.content, this.contentType); -1297 } -1298 } -1299 else if (this.emailBody != null) -1300 { -1301 if (this.contentType == null) -1302 { -1303 this.message.setContent(this.emailBody); -1304 } -1305 else -1306 { -1307 this.message.setContent(this.emailBody, this.contentType); -1308 } -1309 } -1310 else -1311 { -1312 this.message.setText(""); -1313 } -1314 -1315 if (this.fromAddress != null) -1316 { -1317 this.message.setFrom(this.fromAddress); -1318 } -1319 else -1320 { -1321 if (session.getProperty(MAIL_SMTP_FROM) == null) -1322 { -1323 throw new EmailException("From address required"); -1324 } -1325 } -1326 -1327 if (this.toList.size() + this.ccList.size() + this.bccList.size() == 0) -1328 { -1329 throw new EmailException("At least one receiver address required"); -1330 } -1331 -1332 if (this.toList.size() > 0) -1333 { -1334 this.message.setRecipients( -1335 Message.RecipientType.TO, -1336 this.toInternetAddressArray(this.toList)); -1337 } -1338 -1339 if (this.ccList.size() > 0) -1340 { -1341 this.message.setRecipients( -1342 Message.RecipientType.CC, -1343 this.toInternetAddressArray(this.ccList)); -1344 } -1345 -1346 if (this.bccList.size() > 0) -1347 { -1348 this.message.setRecipients( -1349 Message.RecipientType.BCC, -1350 this.toInternetAddressArray(this.bccList)); -1351 } -1352 -1353 if (this.replyList.size() > 0) -1354 { -1355 this.message.setReplyTo( -1356 this.toInternetAddressArray(this.replyList)); -1357 } -1358 -1359 -1360 if (this.headers.size() > 0) -1361 { -1362 for (final Map.Entry<String, String> entry : this.headers.entrySet()) -1363 { -1364 final String foldedValue = createFoldedHeaderValue(entry.getKey(), entry.getValue()); -1365 this.message.addHeader(entry.getKey(), foldedValue); -1366 } -1367 } -1368 -1369 if (this.message.getSentDate() == null) -1370 { -1371 this.message.setSentDate(getSentDate()); -1372 } -1373 -1374 if (this.popBeforeSmtp) -1375 { -1376 final Store store = session.getStore("pop3"); -1377 store.connect(this.popHost, this.popUsername, this.popPassword); +1218 * Gets the "bounce address" of this email. +1219 * +1220 * @return the bounce address as string +1221 * @since 1.4 +1222 */ +1223 public String getBounceAddress() +1224 { +1225 return this.bounceAddress; +1226 } +1227 +1228 /** +1229 * Set the "bounce address" - the address to which undeliverable messages +1230 * will be returned. If this value is never set, then the message will be +1231 * sent to the address specified with the System property "mail.smtp.from", +1232 * or if that value is not set, then to the "from" address. +1233 * +1234 * @param email A String. +1235 * @return An Email. +1236 * @throws IllegalStateException when the mail session is already initialized +1237 * @since 1.0 +1238 */ +1239 public Email setBounceAddress(final String email) +1240 { +1241 checkSessionAlreadyInitialized(); +1242 this.bounceAddress = email; +1243 return this; +1244 } +1245 +1246 /** +1247 * Define the content of the mail. It should be overridden by the +1248 * subclasses. +1249 * +1250 * @param msg A String. +1251 * @return An Email. +1252 * @throws EmailException generic exception. +1253 * @since 1.0 +1254 */ +1255 public abstract Email setMsg(String msg) throws EmailException; +1256 +1257 /** +1258 * Does the work of actually building the MimeMessage. Please note that +1259 * a user rarely calls this method directly and only if he/she is +1260 * interested in the sending the underlying MimeMessage without +1261 * commons-email. +1262 * +1263 * @throws IllegalStateException if the MimeMessage was already built +1264 * @throws EmailException if there was an error. +1265 * @since 1.0 +1266 */ +1267 public void buildMimeMessage() throws EmailException +1268 { +1269 if (this.message != null) +1270 { +1271 // [EMAIL-95] we assume that an email is not reused therefore invoking +1272 // buildMimeMessage() more than once is illegal. +1273 throw new IllegalStateException("The MimeMessage is already built."); +1274 } +1275 +1276 try +1277 { +1278 this.message = this.createMimeMessage(this.getMailSession()); +1279 +1280 if (EmailUtils.isNotEmpty(this.subject)) +1281 { +1282 if (EmailUtils.isNotEmpty(this.charset)) +1283 { +1284 this.message.setSubject(this.subject, this.charset); +1285 } +1286 else +1287 { +1288 this.message.setSubject(this.subject); +1289 } +1290 } +1291 +1292 // update content type (and encoding) +1293 this.updateContentType(this.contentType); +1294 +1295 if (this.content != null) +1296 { +1297 if (EmailConstants.TEXT_PLAIN.equalsIgnoreCase(this.contentType) +1298 && this.content instanceof String) +1299 { +1300 // EMAIL-104: call explicitly setText to use default mime charset +1301 // (property "mail.mime.charset") in case none has been set +1302 this.message.setText(this.content.toString(), this.charset); +1303 } +1304 else +1305 { +1306 this.message.setContent(this.content, this.contentType); +1307 } +1308 } +1309 else if (this.emailBody != null) +1310 { +1311 if (this.contentType == null) +1312 { +1313 this.message.setContent(this.emailBody); +1314 } +1315 else +1316 { +1317 this.message.setContent(this.emailBody, this.contentType); +1318 } +1319 } +1320 else +1321 { +1322 this.message.setText(""); +1323 } +1324 +1325 if (this.fromAddress != null) +1326 { +1327 this.message.setFrom(this.fromAddress); +1328 } +1329 else +1330 { +1331 if (session.getProperty(EmailConstants.MAIL_SMTP_FROM) == null +1332 && session.getProperty(EmailConstants.MAIL_FROM) == null) +1333 { +1334 throw new EmailException("From address required"); +1335 } +1336 } +1337 +1338 if (this.toList.size() + this.ccList.size() + this.bccList.size() == 0) +1339 { +1340 throw new EmailException("At least one receiver address required"); +1341 } +1342 +1343 if (this.toList.size() > 0) +1344 { +1345 this.message.setRecipients( +1346 Message.RecipientType.TO, +1347 this.toInternetAddressArray(this.toList)); +1348 } +1349 +1350 if (this.ccList.size() > 0) +1351 { +1352 this.message.setRecipients( +1353 Message.RecipientType.CC, +1354 this.toInternetAddressArray(this.ccList)); +1355 } +1356 +1357 if (this.bccList.size() > 0) +1358 { +1359 this.message.setRecipients( +1360 Message.RecipientType.BCC, +1361 this.toInternetAddressArray(this.bccList)); +1362 } +1363 +1364 if (this.replyList.size() > 0) +1365 { +1366 this.message.setReplyTo( +1367 this.toInternetAddressArray(this.replyList)); +1368 } +1369 +1370 +1371 if (this.headers.size() > 0) +1372 { +1373 for (final Map.Entry<String, String> entry : this.headers.entrySet()) +1374 { +1375 final String foldedValue = createFoldedHeaderValue(entry.getKey(), entry.getValue()); +1376 this.message.addHeader(entry.getKey(), foldedValue); +1377 } 1378 } -1379 } -1380 catch (final MessagingException me) -1381 { -1382 throw new EmailException(me); -1383 } -1384 } -1385 -1386 /** -1387 * Sends the previously created MimeMessage to the SMTP server. -1388 * -1389 * @return the message id of the underlying MimeMessage -1390 * @throws IllegalArgumentException if the MimeMessage has not been created -1391 * @throws EmailException the sending failed -1392 */ -1393 public String sendMimeMessage() -1394 throws EmailException -1395 { -1396 EmailUtils.notNull(this.message, "MimeMessage has not been created yet"); -1397 -1398 try -1399 { -1400 Transport.send(this.message); -1401 return this.message.getMessageID(); -1402 } -1403 catch (final Throwable t) -1404 { -1405 final String msg = "Sending the email to the following server failed : " -1406 + this.getHostName() -1407 + ":" -1408 + this.getSmtpPort(); -1409 -1410 throw new EmailException(msg, t); -1411 } -1412 } -1413 -1414 /** -1415 * Returns the internal MimeMessage. Please not that the -1416 * MimeMessage is build by the buildMimeMessage() method. -1417 * -1418 * @return the MimeMessage -1419 */ -1420 public MimeMessage getMimeMessage() -1421 { -1422 return this.message; +1379 +1380 if (this.message.getSentDate() == null) +1381 { +1382 this.message.setSentDate(getSentDate()); +1383 } +1384 +1385 if (this.popBeforeSmtp) +1386 { +1387 final Store store = session.getStore("pop3"); +1388 store.connect(this.popHost, this.popUsername, this.popPassword); +1389 } +1390 } +1391 catch (final MessagingException me) +1392 { +1393 throw new EmailException(me); +1394 } +1395 } +1396 +1397 /** +1398 * Sends the previously created MimeMessage to the SMTP server. +1399 * +1400 * @return the message id of the underlying MimeMessage +1401 * @throws IllegalArgumentException if the MimeMessage has not been created +1402 * @throws EmailException the sending failed +1403 */ +1404 public String sendMimeMessage() +1405 throws EmailException +1406 { +1407 EmailUtils.notNull(this.message, "MimeMessage has not been created yet"); +1408 +1409 try +1410 { +1411 Transport.send(this.message); +1412 return this.message.getMessageID(); +1413 } +1414 catch (final Throwable t) +1415 { +1416 final String msg = "Sending the email to the following server failed : " +1417 + this.getHostName() +1418 + ":" +1419 + this.getSmtpPort(); +1420 +1421 throw new EmailException(msg, t); +1422 } 1423 } 1424 1425 /** -1426 * Sends the email. Internally we build a MimeMessage -1427 * which is afterwards sent to the SMTP server. +1426 * Returns the internal MimeMessage. Please not that the +1427 * MimeMessage is build by the buildMimeMessage() method. 1428 * -1429 * @return the message id of the underlying MimeMessage -1430 * @throws IllegalStateException if the MimeMessage was already built, ie {@link #buildMimeMessage()} -1431 * was already called -1432 * @throws EmailException the sending failed -1433 */ -1434 public String send() throws EmailException -1435 { -1436 this.buildMimeMessage(); -1437 return this.sendMimeMessage(); -1438 } -1439 -1440 /** -1441 * Sets the sent date for the email. The sent date will default to the -1442 * current date if not explicitly set. -1443 * -1444 * @param date Date to use as the sent date on the email -1445 * @since 1.0 -1446 */ -1447 public void setSentDate(final Date date) -1448 { -1449 if (date != null) -1450 { -1451 // create a separate instance to keep findbugs happy -1452 this.sentDate = new Date(date.getTime()); -1453 } -1454 } -1455 -1456 /** -1457 * Gets the sent date for the email. -1458 * -1459 * @return date to be used as the sent date for the email -1460 * @since 1.0 -1461 */ -1462 public Date getSentDate() -1463 { -1464 if (this.sentDate == null) -1465 { -1466 return new Date(); -1467 } -1468 return new Date(this.sentDate.getTime()); -1469 } -1470 -1471 /** -1472 * Gets the subject of the email. -1473 * -1474 * @return email subject -1475 */ -1476 public String getSubject() -1477 { -1478 return this.subject; -1479 } -1480 -1481 /** -1482 * Gets the sender of the email. -1483 * -1484 * @return from address -1485 */ -1486 public InternetAddress getFromAddress() -1487 { -1488 return this.fromAddress; -1489 } -1490 -1491 /** -1492 * Gets the host name of the SMTP server, -1493 * -1494 * @return host name -1495 */ -1496 public String getHostName() -1497 { -1498 if (this.session != null) -1499 { -1500 return this.session.getProperty(MAIL_HOST); -1501 } -1502 else if (EmailUtils.isNotEmpty(this.hostName)) -1503 { -1504 return this.hostName; -1505 } -1506 return null; -1507 } -1508 -1509 /** -1510 * Gets the listening port of the SMTP server. -1511 * -1512 * @return smtp port -1513 */ -1514 public String getSmtpPort() -1515 { -1516 if (this.session != null) -1517 { -1518 return this.session.getProperty(MAIL_PORT); -1519 } -1520 else if (EmailUtils.isNotEmpty(this.smtpPort)) -1521 { -1522 return this.smtpPort; -1523 } -1524 return null; -1525 } -1526 -1527 /** -1528 * Gets whether the client is configured to require STARTTLS. -1529 * -1530 * @return true if using STARTTLS for authentication, false otherwise -1531 * @since 1.3 -1532 */ -1533 public boolean isStartTLSRequired() -1534 { -1535 return this.startTlsRequired; +1429 * @return the MimeMessage +1430 */ +1431 public MimeMessage getMimeMessage() +1432 { +1433 return this.message; +1434 } +1435 +1436 /** +1437 * Sends the email. Internally we build a MimeMessage +1438 * which is afterwards sent to the SMTP server. +1439 * +1440 * @return the message id of the underlying MimeMessage +1441 * @throws IllegalStateException if the MimeMessage was already built, ie {@link #buildMimeMessage()} +1442 * was already called +1443 * @throws EmailException the sending failed +1444 */ +1445 public String send() throws EmailException +1446 { +1447 this.buildMimeMessage(); +1448 return this.sendMimeMessage(); +1449 } +1450 +1451 /** +1452 * Sets the sent date for the email. The sent date will default to the +1453 * current date if not explicitly set. +1454 * +1455 * @param date Date to use as the sent date on the email +1456 * @since 1.0 +1457 */ +1458 public void setSentDate(final Date date) +1459 { +1460 if (date != null) +1461 { +1462 // create a separate instance to keep findbugs happy +1463 this.sentDate = new Date(date.getTime()); +1464 } +1465 } +1466 +1467 /** +1468 * Gets the sent date for the email. +1469 * +1470 * @return date to be used as the sent date for the email +1471 * @since 1.0 +1472 */ +1473 public Date getSentDate() +1474 { +1475 if (this.sentDate == null) +1476 { +1477 return new Date(); +1478 } +1479 return new Date(this.sentDate.getTime()); +1480 } +1481 +1482 /** +1483 * Gets the subject of the email. +1484 * +1485 * @return email subject +1486 */ +1487 public String getSubject() +1488 { +1489 return this.subject; +1490 } +1491 +1492 /** +1493 * Gets the sender of the email. +1494 * +1495 * @return from address +1496 */ +1497 public InternetAddress getFromAddress() +1498 { +1499 return this.fromAddress; +1500 } +1501 +1502 /** +1503 * Gets the host name of the SMTP server, +1504 * +1505 * @return host name +1506 */ +1507 public String getHostName() +1508 { +1509 if (this.session != null) +1510 { +1511 return this.session.getProperty(MAIL_HOST); +1512 } +1513 else if (EmailUtils.isNotEmpty(this.hostName)) +1514 { +1515 return this.hostName; +1516 } +1517 return null; +1518 } +1519 +1520 /** +1521 * Gets the listening port of the SMTP server. +1522 * +1523 * @return smtp port +1524 */ +1525 public String getSmtpPort() +1526 { +1527 if (this.session != null) +1528 { +1529 return this.session.getProperty(MAIL_PORT); +1530 } +1531 else if (EmailUtils.isNotEmpty(this.smtpPort)) +1532 { +1533 return this.smtpPort; +1534 } +1535 return null; 1536 } 1537 1538 /** -1539 * Gets whether the client is configured to try to enable STARTTLS. +1539 * Gets whether the client is configured to require STARTTLS. 1540 * 1541 * @return true if using STARTTLS for authentication, false otherwise 1542 * @since 1.3 1543 */ -1544 public boolean isStartTLSEnabled() +1544 public boolean isStartTLSRequired() 1545 { -1546 return this.startTlsEnabled || tls; +1546 return this.startTlsRequired; 1547 } 1548 1549 /** 1550 * Gets whether the client is configured to try to enable STARTTLS. -1551 * See EMAIL-105 for reason of deprecation. -1552 * -1553 * @deprecated since 1.3, use isStartTLSEnabled() instead -1554 * @return true if using STARTTLS for authentication, false otherwise -1555 * @since 1.1 -1556 */ -1557 @Deprecated -1558 public boolean isTLS() -1559 { -1560 return isStartTLSEnabled(); -1561 } -1562 -1563 /** -1564 * Utility to copy List of known InternetAddress objects into an -1565 * array. -1566 * -1567 * @param list A List. -1568 * @return An InternetAddress[]. -1569 * @since 1.0 -1570 */ -1571 protected InternetAddress[] toInternetAddressArray(final List<InternetAddress> list) -1572 { -1573 return list.toArray(new InternetAddress[list.size()]); -1574 } -1575 -1576 /** -1577 * Set details regarding "pop3 before smtp" authentication. -1578 * -1579 * @param newPopBeforeSmtp Whether or not to log into pop3 server before sending mail. -1580 * @param newPopHost The pop3 host to use. -1581 * @param newPopUsername The pop3 username. -1582 * @param newPopPassword The pop3 password. -1583 * @since 1.0 -1584 */ -1585 public void setPopBeforeSmtp( -1586 final boolean newPopBeforeSmtp, -1587 final String newPopHost, -1588 final String newPopUsername, -1589 final String newPopPassword) -1590 { [... 723 lines stripped ...]