Added: dev/commons/email/2.0.0-M1-RC1/site/apidocs/src-html/org/apache/commons/mail2/javax/EmailAttachment.html ============================================================================== --- dev/commons/email/2.0.0-M1-RC1/site/apidocs/src-html/org/apache/commons/mail2/javax/EmailAttachment.html (added) +++ dev/commons/email/2.0.0-M1-RC1/site/apidocs/src-html/org/apache/commons/mail2/javax/EmailAttachment.html Sat Jun 15 15:07:30 2024 @@ -0,0 +1,236 @@ +<!DOCTYPE HTML> +<html lang="en"> +<head> +<!-- Generated by javadoc (17) --> +<title>Source code</title> +<meta name="viewport" content="width=device-width, initial-scale=1"> +<meta name="description" content="source: package: org.apache.commons.mail2.javax, class: EmailAttachment"> +<meta name="generator" content="javadoc/SourceToHTMLConverter"> +<link rel="stylesheet" type="text/css" href="../../../../../../stylesheet.css" title="Style"> +</head> +<body class="source-page"> +<main role="main"> +<div class="source-container"> +<pre><span class="source-line-no">001</span><span id="line-1">/*</span> +<span class="source-line-no">002</span><span id="line-2"> * Licensed to the Apache Software Foundation (ASF) under one or more</span> +<span class="source-line-no">003</span><span id="line-3"> * contributor license agreements. See the NOTICE file distributed with</span> +<span class="source-line-no">004</span><span id="line-4"> * this work for additional information regarding copyright ownership.</span> +<span class="source-line-no">005</span><span id="line-5"> * The ASF licenses this file to You under the Apache License, Version 2.0</span> +<span class="source-line-no">006</span><span id="line-6"> * (the "License"); you may not use this file except in compliance with</span> +<span class="source-line-no">007</span><span id="line-7"> * the License. You may obtain a copy of the License at</span> +<span class="source-line-no">008</span><span id="line-8"> *</span> +<span class="source-line-no">009</span><span id="line-9"> * http://www.apache.org/licenses/LICENSE-2.0</span> +<span class="source-line-no">010</span><span id="line-10"> *</span> +<span class="source-line-no">011</span><span id="line-11"> * Unless required by applicable law or agreed to in writing, software</span> +<span class="source-line-no">012</span><span id="line-12"> * distributed under the License is distributed on an "AS IS" BASIS,</span> +<span class="source-line-no">013</span><span id="line-13"> * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.</span> +<span class="source-line-no">014</span><span id="line-14"> * See the License for the specific language governing permissions and</span> +<span class="source-line-no">015</span><span id="line-15"> * limitations under the License.</span> +<span class="source-line-no">016</span><span id="line-16"> */</span> +<span class="source-line-no">017</span><span id="line-17">package org.apache.commons.mail2.javax;</span> +<span class="source-line-no">018</span><span id="line-18"></span> +<span class="source-line-no">019</span><span id="line-19">import java.net.URL;</span> +<span class="source-line-no">020</span><span id="line-20"></span> +<span class="source-line-no">021</span><span id="line-21">/**</span> +<span class="source-line-no">022</span><span id="line-22"> * This class models an email attachment. Used by {@link MultiPartEmail}.</span> +<span class="source-line-no">023</span><span id="line-23"> *</span> +<span class="source-line-no">024</span><span id="line-24"> * @since 1.0</span> +<span class="source-line-no">025</span><span id="line-25"> */</span> +<span class="source-line-no">026</span><span id="line-26">public class EmailAttachment {</span> +<span class="source-line-no">027</span><span id="line-27"></span> +<span class="source-line-no">028</span><span id="line-28"> /** Definition of the part being an attachment. */</span> +<span class="source-line-no">029</span><span id="line-29"> public static final String ATTACHMENT = javax.mail.Part.ATTACHMENT;</span> +<span class="source-line-no">030</span><span id="line-30"></span> +<span class="source-line-no">031</span><span id="line-31"> /** Definition of the part being inline. */</span> +<span class="source-line-no">032</span><span id="line-32"> public static final String INLINE = javax.mail.Part.INLINE;</span> +<span class="source-line-no">033</span><span id="line-33"></span> +<span class="source-line-no">034</span><span id="line-34"> /** The name of this attachment. */</span> +<span class="source-line-no">035</span><span id="line-35"> private String name = "";</span> +<span class="source-line-no">036</span><span id="line-36"></span> +<span class="source-line-no">037</span><span id="line-37"> /** The description of this attachment. */</span> +<span class="source-line-no">038</span><span id="line-38"> private String description = "";</span> +<span class="source-line-no">039</span><span id="line-39"></span> +<span class="source-line-no">040</span><span id="line-40"> /** The path to this attachment (ie c:/path/to/file.jpg). */</span> +<span class="source-line-no">041</span><span id="line-41"> private String path = "";</span> +<span class="source-line-no">042</span><span id="line-42"></span> +<span class="source-line-no">043</span><span id="line-43"> /** The HttpURI where the file can be got. */</span> +<span class="source-line-no">044</span><span id="line-44"> private URL url;</span> +<span class="source-line-no">045</span><span id="line-45"></span> +<span class="source-line-no">046</span><span id="line-46"> /** The disposition. */</span> +<span class="source-line-no">047</span><span id="line-47"> private String disposition = ATTACHMENT;</span> +<span class="source-line-no">048</span><span id="line-48"></span> +<span class="source-line-no">049</span><span id="line-49"> /**</span> +<span class="source-line-no">050</span><span id="line-50"> * Constructs a new instance.</span> +<span class="source-line-no">051</span><span id="line-51"> */</span> +<span class="source-line-no">052</span><span id="line-52"> public EmailAttachment() {</span> +<span class="source-line-no">053</span><span id="line-53"> // empty</span> +<span class="source-line-no">054</span><span id="line-54"> }</span> +<span class="source-line-no">055</span><span id="line-55"></span> +<span class="source-line-no">056</span><span id="line-56"> /**</span> +<span class="source-line-no">057</span><span id="line-57"> * Gets the description.</span> +<span class="source-line-no">058</span><span id="line-58"> *</span> +<span class="source-line-no">059</span><span id="line-59"> * @return A String.</span> +<span class="source-line-no">060</span><span id="line-60"> * @since 1.0</span> +<span class="source-line-no">061</span><span id="line-61"> */</span> +<span class="source-line-no">062</span><span id="line-62"> public String getDescription() {</span> +<span class="source-line-no">063</span><span id="line-63"> return description;</span> +<span class="source-line-no">064</span><span id="line-64"> }</span> +<span class="source-line-no">065</span><span id="line-65"></span> +<span class="source-line-no">066</span><span id="line-66"> /**</span> +<span class="source-line-no">067</span><span id="line-67"> * Gets the disposition.</span> +<span class="source-line-no">068</span><span id="line-68"> *</span> +<span class="source-line-no">069</span><span id="line-69"> * @return A String.</span> +<span class="source-line-no">070</span><span id="line-70"> * @since 1.0</span> +<span class="source-line-no">071</span><span id="line-71"> */</span> +<span class="source-line-no">072</span><span id="line-72"> public String getDisposition() {</span> +<span class="source-line-no">073</span><span id="line-73"> return disposition;</span> +<span class="source-line-no">074</span><span id="line-74"> }</span> +<span class="source-line-no">075</span><span id="line-75"></span> +<span class="source-line-no">076</span><span id="line-76"> /**</span> +<span class="source-line-no">077</span><span id="line-77"> * Gets the name.</span> +<span class="source-line-no">078</span><span id="line-78"> *</span> +<span class="source-line-no">079</span><span id="line-79"> * @return A String.</span> +<span class="source-line-no">080</span><span id="line-80"> * @since 1.0</span> +<span class="source-line-no">081</span><span id="line-81"> */</span> +<span class="source-line-no">082</span><span id="line-82"> public String getName() {</span> +<span class="source-line-no">083</span><span id="line-83"> return name;</span> +<span class="source-line-no">084</span><span id="line-84"> }</span> +<span class="source-line-no">085</span><span id="line-85"></span> +<span class="source-line-no">086</span><span id="line-86"> /**</span> +<span class="source-line-no">087</span><span id="line-87"> * Gets the path.</span> +<span class="source-line-no">088</span><span id="line-88"> *</span> +<span class="source-line-no">089</span><span id="line-89"> * @return A String.</span> +<span class="source-line-no">090</span><span id="line-90"> * @since 1.0</span> +<span class="source-line-no">091</span><span id="line-91"> */</span> +<span class="source-line-no">092</span><span id="line-92"> public String getPath() {</span> +<span class="source-line-no">093</span><span id="line-93"> return path;</span> +<span class="source-line-no">094</span><span id="line-94"> }</span> +<span class="source-line-no">095</span><span id="line-95"></span> +<span class="source-line-no">096</span><span id="line-96"> /**</span> +<span class="source-line-no">097</span><span id="line-97"> * Gets the URL.</span> +<span class="source-line-no">098</span><span id="line-98"> *</span> +<span class="source-line-no">099</span><span id="line-99"> * @return A URL.</span> +<span class="source-line-no">100</span><span id="line-100"> * @since 1.0</span> +<span class="source-line-no">101</span><span id="line-101"> */</span> +<span class="source-line-no">102</span><span id="line-102"> public URL getURL() {</span> +<span class="source-line-no">103</span><span id="line-103"> return url;</span> +<span class="source-line-no">104</span><span id="line-104"> }</span> +<span class="source-line-no">105</span><span id="line-105"></span> +<span class="source-line-no">106</span><span id="line-106"> /**</span> +<span class="source-line-no">107</span><span id="line-107"> * Sets the description.</span> +<span class="source-line-no">108</span><span id="line-108"> *</span> +<span class="source-line-no">109</span><span id="line-109"> * @param desc A String.</span> +<span class="source-line-no">110</span><span id="line-110"> * @since 1.0</span> +<span class="source-line-no">111</span><span id="line-111"> */</span> +<span class="source-line-no">112</span><span id="line-112"> public void setDescription(final String desc) {</span> +<span class="source-line-no">113</span><span id="line-113"> this.description = desc;</span> +<span class="source-line-no">114</span><span id="line-114"> }</span> +<span class="source-line-no">115</span><span id="line-115"></span> +<span class="source-line-no">116</span><span id="line-116"> /**</span> +<span class="source-line-no">117</span><span id="line-117"> * Sets the disposition.</span> +<span class="source-line-no">118</span><span id="line-118"> *</span> +<span class="source-line-no">119</span><span id="line-119"> * @param aDisposition A String.</span> +<span class="source-line-no">120</span><span id="line-120"> * @since 1.0</span> +<span class="source-line-no">121</span><span id="line-121"> */</span> +<span class="source-line-no">122</span><span id="line-122"> public void setDisposition(final String aDisposition) {</span> +<span class="source-line-no">123</span><span id="line-123"> this.disposition = aDisposition;</span> +<span class="source-line-no">124</span><span id="line-124"> }</span> +<span class="source-line-no">125</span><span id="line-125"></span> +<span class="source-line-no">126</span><span id="line-126"> /**</span> +<span class="source-line-no">127</span><span id="line-127"> * Sets the name.</span> +<span class="source-line-no">128</span><span id="line-128"> *</span> +<span class="source-line-no">129</span><span id="line-129"> * @param aName A String.</span> +<span class="source-line-no">130</span><span id="line-130"> * @since 1.0</span> +<span class="source-line-no">131</span><span id="line-131"> */</span> +<span class="source-line-no">132</span><span id="line-132"> public void setName(final String aName) {</span> +<span class="source-line-no">133</span><span id="line-133"> this.name = aName;</span> +<span class="source-line-no">134</span><span id="line-134"> }</span> +<span class="source-line-no">135</span><span id="line-135"></span> +<span class="source-line-no">136</span><span id="line-136"> /**</span> +<span class="source-line-no">137</span><span id="line-137"> * Sets the path to the attachment. The path can be absolute or relative and should include the file name.</span> +<span class="source-line-no">138</span><span id="line-138"> * <p></span> +<span class="source-line-no">139</span><span id="line-139"> * Example: /home/user/images/image.jpg<br></span> +<span class="source-line-no">140</span><span id="line-140"> * Example: images/image.jpg</span> +<span class="source-line-no">141</span><span id="line-141"> *</span> +<span class="source-line-no">142</span><span id="line-142"> * @param aPath A String.</span> +<span class="source-line-no">143</span><span id="line-143"> * @since 1.0</span> +<span class="source-line-no">144</span><span id="line-144"> */</span> +<span class="source-line-no">145</span><span id="line-145"> public void setPath(final String aPath) {</span> +<span class="source-line-no">146</span><span id="line-146"> this.path = aPath;</span> +<span class="source-line-no">147</span><span id="line-147"> }</span> +<span class="source-line-no">148</span><span id="line-148"></span> +<span class="source-line-no">149</span><span id="line-149"> /**</span> +<span class="source-line-no">150</span><span id="line-150"> * Sets the URL.</span> +<span class="source-line-no">151</span><span id="line-151"> *</span> +<span class="source-line-no">152</span><span id="line-152"> * @param aUrl A URL.</span> +<span class="source-line-no">153</span><span id="line-153"> * @since 1.0</span> +<span class="source-line-no">154</span><span id="line-154"> */</span> +<span class="source-line-no">155</span><span id="line-155"> public void setURL(final URL aUrl) {</span> +<span class="source-line-no">156</span><span id="line-156"> this.url = aUrl;</span> +<span class="source-line-no">157</span><span id="line-157"> }</span> +<span class="source-line-no">158</span><span id="line-158">}</span> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +</pre> +</div> +</main> +</body> +</html>
Added: dev/commons/email/2.0.0-M1-RC1/site/apidocs/src-html/org/apache/commons/mail2/javax/HtmlEmail.html ============================================================================== --- dev/commons/email/2.0.0-M1-RC1/site/apidocs/src-html/org/apache/commons/mail2/javax/HtmlEmail.html (added) +++ dev/commons/email/2.0.0-M1-RC1/site/apidocs/src-html/org/apache/commons/mail2/javax/HtmlEmail.html Sat Jun 15 15:07:30 2024 @@ -0,0 +1,646 @@ +<!DOCTYPE HTML> +<html lang="en"> +<head> +<!-- Generated by javadoc (17) --> +<title>Source code</title> +<meta name="viewport" content="width=device-width, initial-scale=1"> +<meta name="description" content="source: package: org.apache.commons.mail2.javax, class: HtmlEmail"> +<meta name="generator" content="javadoc/SourceToHTMLConverter"> +<link rel="stylesheet" type="text/css" href="../../../../../../stylesheet.css" title="Style"> +</head> +<body class="source-page"> +<main role="main"> +<div class="source-container"> +<pre><span class="source-line-no">001</span><span id="line-1">/*</span> +<span class="source-line-no">002</span><span id="line-2"> * Licensed to the Apache Software Foundation (ASF) under one or more</span> +<span class="source-line-no">003</span><span id="line-3"> * contributor license agreements. See the NOTICE file distributed with</span> +<span class="source-line-no">004</span><span id="line-4"> * this work for additional information regarding copyright ownership.</span> +<span class="source-line-no">005</span><span id="line-5"> * The ASF licenses this file to You under the Apache License, Version 2.0</span> +<span class="source-line-no">006</span><span id="line-6"> * (the "License"); you may not use this file except in compliance with</span> +<span class="source-line-no">007</span><span id="line-7"> * the License. You may obtain a copy of the License at</span> +<span class="source-line-no">008</span><span id="line-8"> *</span> +<span class="source-line-no">009</span><span id="line-9"> * http://www.apache.org/licenses/LICENSE-2.0</span> +<span class="source-line-no">010</span><span id="line-10"> *</span> +<span class="source-line-no">011</span><span id="line-11"> * Unless required by applicable law or agreed to in writing, software</span> +<span class="source-line-no">012</span><span id="line-12"> * distributed under the License is distributed on an "AS IS" BASIS,</span> +<span class="source-line-no">013</span><span id="line-13"> * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.</span> +<span class="source-line-no">014</span><span id="line-14"> * See the License for the specific language governing permissions and</span> +<span class="source-line-no">015</span><span id="line-15"> * limitations under the License.</span> +<span class="source-line-no">016</span><span id="line-16"> */</span> +<span class="source-line-no">017</span><span id="line-17">package org.apache.commons.mail2.javax;</span> +<span class="source-line-no">018</span><span id="line-18"></span> +<span class="source-line-no">019</span><span id="line-19">import java.io.File;</span> +<span class="source-line-no">020</span><span id="line-20">import java.io.IOException;</span> +<span class="source-line-no">021</span><span id="line-21">import java.io.InputStream;</span> +<span class="source-line-no">022</span><span id="line-22">import java.net.MalformedURLException;</span> +<span class="source-line-no">023</span><span id="line-23">import java.net.URL;</span> +<span class="source-line-no">024</span><span id="line-24">import java.util.HashMap;</span> +<span class="source-line-no">025</span><span id="line-25">import java.util.Map;</span> +<span class="source-line-no">026</span><span id="line-26">import java.util.Objects;</span> +<span class="source-line-no">027</span><span id="line-27"></span> +<span class="source-line-no">028</span><span id="line-28">import javax.activation.DataHandler;</span> +<span class="source-line-no">029</span><span id="line-29">import javax.activation.DataSource;</span> +<span class="source-line-no">030</span><span id="line-30">import javax.activation.FileDataSource;</span> +<span class="source-line-no">031</span><span id="line-31">import javax.activation.URLDataSource;</span> +<span class="source-line-no">032</span><span id="line-32">import javax.mail.BodyPart;</span> +<span class="source-line-no">033</span><span id="line-33">import javax.mail.MessagingException;</span> +<span class="source-line-no">034</span><span id="line-34">import javax.mail.internet.MimeBodyPart;</span> +<span class="source-line-no">035</span><span id="line-35">import javax.mail.internet.MimeMultipart;</span> +<span class="source-line-no">036</span><span id="line-36"></span> +<span class="source-line-no">037</span><span id="line-37">import org.apache.commons.mail2.core.EmailConstants;</span> +<span class="source-line-no">038</span><span id="line-38">import org.apache.commons.mail2.core.EmailException;</span> +<span class="source-line-no">039</span><span id="line-39">import org.apache.commons.mail2.core.EmailUtils;</span> +<span class="source-line-no">040</span><span id="line-40"></span> +<span class="source-line-no">041</span><span id="line-41">/**</span> +<span class="source-line-no">042</span><span id="line-42"> * An HTML multipart email.</span> +<span class="source-line-no">043</span><span id="line-43"> * <p></span> +<span class="source-line-no">044</span><span id="line-44"> * This class is used to send HTML formatted email. A text message can also be set for HTML unaware email clients, such as text-based email clients.</span> +<span class="source-line-no">045</span><span id="line-45"> * </p></span> +<span class="source-line-no">046</span><span id="line-46"> * <p></span> +<span class="source-line-no">047</span><span id="line-47"> * This class also inherits from {@link MultiPartEmail}, so it is easy to add attachments to the email.</span> +<span class="source-line-no">048</span><span id="line-48"> * </p></span> +<span class="source-line-no">049</span><span id="line-49"> * <p></span> +<span class="source-line-no">050</span><span id="line-50"> * To send an email in HTML, one should create a {@code HtmlEmail}, then use the {@link #setFrom(String)}, {@link #addTo(String)} etc. methods. The HTML content</span> +<span class="source-line-no">051</span><span id="line-51"> * can be set with the {@link #setHtmlMsg(String)} method. The alternative text content can be set with {@link #setTextMsg(String)}.</span> +<span class="source-line-no">052</span><span id="line-52"> * </p></span> +<span class="source-line-no">053</span><span id="line-53"> * <p></span> +<span class="source-line-no">054</span><span id="line-54"> * Either the text or HTML can be omitted, in which case the "main" part of the multipart becomes whichever is supplied rather than a</span> +<span class="source-line-no">055</span><span id="line-55"> * {@code multipart/alternative}.</span> +<span class="source-line-no">056</span><span id="line-56"> * </p></span> +<span class="source-line-no">057</span><span id="line-57"> * <h2>Embedding Images and Media</h2></span> +<span class="source-line-no">058</span><span id="line-58"> * <p></span> +<span class="source-line-no">059</span><span id="line-59"> * It is also possible to embed URLs, files, or arbitrary {@code DataSource}s directly into the body of the mail:</span> +<span class="source-line-no">060</span><span id="line-60"> * </p></span> +<span class="source-line-no">061</span><span id="line-61"> *</span> +<span class="source-line-no">062</span><span id="line-62"> * <pre></span> +<span class="source-line-no">063</span><span id="line-63"> * HtmlEmail he = new HtmlEmail();</span> +<span class="source-line-no">064</span><span id="line-64"> * File img = new File("my/image.gif");</span> +<span class="source-line-no">065</span><span id="line-65"> * PNGDataSource png = new PNGDataSource(decodedPNGOutputStream); // a custom class</span> +<span class="source-line-no">066</span><span id="line-66"> * StringBuffer msg = new StringBuffer();</span> +<span class="source-line-no">067</span><span id="line-67"> * msg.append("&lt;html&gt;&lt;body&gt;");</span> +<span class="source-line-no">068</span><span id="line-68"> * msg.append("&lt;img src=cid:").append(he.embed(img)).append("&gt;");</span> +<span class="source-line-no">069</span><span id="line-69"> * msg.append("&lt;img src=cid:").append(he.embed(png)).append("&gt;");</span> +<span class="source-line-no">070</span><span id="line-70"> * msg.append("&lt;/body&gt;&lt;/html&gt;");</span> +<span class="source-line-no">071</span><span id="line-71"> * he.setHtmlMsg(msg.toString());</span> +<span class="source-line-no">072</span><span id="line-72"> * // code to set the other email fields (not shown)</span> +<span class="source-line-no">073</span><span id="line-73"> * </pre></span> +<span class="source-line-no">074</span><span id="line-74"> * <p></span> +<span class="source-line-no">075</span><span id="line-75"> * Embedded entities are tracked by their name, which for {@code File}s is the file name itself and for {@code URL}s is the canonical path. It is an error to</span> +<span class="source-line-no">076</span><span id="line-76"> * bind the same name to more than one entity, and this class will attempt to validate that for {@code File}s and {@code URL}s. When embedding a</span> +<span class="source-line-no">077</span><span id="line-77"> * {@code DataSource}, the code uses the {@code equals()} method defined on the {@code DataSource}s to make the determination.</span> +<span class="source-line-no">078</span><span id="line-78"> * </p></span> +<span class="source-line-no">079</span><span id="line-79"> *</span> +<span class="source-line-no">080</span><span id="line-80"> * @since 1.0</span> +<span class="source-line-no">081</span><span id="line-81"> */</span> +<span class="source-line-no">082</span><span id="line-82">public class HtmlEmail extends MultiPartEmail {</span> +<span class="source-line-no">083</span><span id="line-83"></span> +<span class="source-line-no">084</span><span id="line-84"> /**</span> +<span class="source-line-no">085</span><span id="line-85"> * Private bean class that encapsulates data about URL contents that are embedded in the final email.</span> +<span class="source-line-no">086</span><span id="line-86"> *</span> +<span class="source-line-no">087</span><span id="line-87"> * @since 1.1</span> +<span class="source-line-no">088</span><span id="line-88"> */</span> +<span class="source-line-no">089</span><span id="line-89"> private static final class InlineImage {</span> +<span class="source-line-no">090</span><span id="line-90"></span> +<span class="source-line-no">091</span><span id="line-91"> /** Content id. */</span> +<span class="source-line-no">092</span><span id="line-92"> private final String cid;</span> +<span class="source-line-no">093</span><span id="line-93"></span> +<span class="source-line-no">094</span><span id="line-94"> /** {@code DataSource} for the content. */</span> +<span class="source-line-no">095</span><span id="line-95"> private final DataSource dataSource;</span> +<span class="source-line-no">096</span><span id="line-96"></span> +<span class="source-line-no">097</span><span id="line-97"> /** The {@code MimeBodyPart} that contains the encoded data. */</span> +<span class="source-line-no">098</span><span id="line-98"> private final MimeBodyPart mimeBodyPart;</span> +<span class="source-line-no">099</span><span id="line-99"></span> +<span class="source-line-no">100</span><span id="line-100"> /**</span> +<span class="source-line-no">101</span><span id="line-101"> * Creates an InlineImage object to represent the specified content ID and {@code MimeBodyPart}.</span> +<span class="source-line-no">102</span><span id="line-102"> *</span> +<span class="source-line-no">103</span><span id="line-103"> * @param cid the generated content ID, not null.</span> +<span class="source-line-no">104</span><span id="line-104"> * @param dataSource the {@code DataSource} that represents the content, not null.</span> +<span class="source-line-no">105</span><span id="line-105"> * @param mimeBodyPart the {@code MimeBodyPart} that contains the encoded data, not null.</span> +<span class="source-line-no">106</span><span id="line-106"> */</span> +<span class="source-line-no">107</span><span id="line-107"> private InlineImage(final String cid, final DataSource dataSource, final MimeBodyPart mimeBodyPart) {</span> +<span class="source-line-no">108</span><span id="line-108"> this.cid = Objects.requireNonNull(cid, "cid");</span> +<span class="source-line-no">109</span><span id="line-109"> this.dataSource = Objects.requireNonNull(dataSource, "dataSource");</span> +<span class="source-line-no">110</span><span id="line-110"> this.mimeBodyPart = Objects.requireNonNull(mimeBodyPart, "mimeBodyPart");</span> +<span class="source-line-no">111</span><span id="line-111"> }</span> +<span class="source-line-no">112</span><span id="line-112"></span> +<span class="source-line-no">113</span><span id="line-113"> @Override</span> +<span class="source-line-no">114</span><span id="line-114"> public boolean equals(final Object obj) {</span> +<span class="source-line-no">115</span><span id="line-115"> if (this == obj) {</span> +<span class="source-line-no">116</span><span id="line-116"> return true;</span> +<span class="source-line-no">117</span><span id="line-117"> }</span> +<span class="source-line-no">118</span><span id="line-118"> if (!(obj instanceof InlineImage)) {</span> +<span class="source-line-no">119</span><span id="line-119"> return false;</span> +<span class="source-line-no">120</span><span id="line-120"> }</span> +<span class="source-line-no">121</span><span id="line-121"> final InlineImage other = (InlineImage) obj;</span> +<span class="source-line-no">122</span><span id="line-122"> return Objects.equals(cid, other.cid);</span> +<span class="source-line-no">123</span><span id="line-123"> }</span> +<span class="source-line-no">124</span><span id="line-124"></span> +<span class="source-line-no">125</span><span id="line-125"> /**</span> +<span class="source-line-no">126</span><span id="line-126"> * Returns the unique content ID of this InlineImage.</span> +<span class="source-line-no">127</span><span id="line-127"> *</span> +<span class="source-line-no">128</span><span id="line-128"> * @return the unique content ID of this InlineImage</span> +<span class="source-line-no">129</span><span id="line-129"> */</span> +<span class="source-line-no">130</span><span id="line-130"> private String getCid() {</span> +<span class="source-line-no">131</span><span id="line-131"> return cid;</span> +<span class="source-line-no">132</span><span id="line-132"> }</span> +<span class="source-line-no">133</span><span id="line-133"></span> +<span class="source-line-no">134</span><span id="line-134"> /**</span> +<span class="source-line-no">135</span><span id="line-135"> * Returns the {@code DataSource} that represents the encoded content.</span> +<span class="source-line-no">136</span><span id="line-136"> *</span> +<span class="source-line-no">137</span><span id="line-137"> * @return the {@code DataSource} representing the encoded content</span> +<span class="source-line-no">138</span><span id="line-138"> */</span> +<span class="source-line-no">139</span><span id="line-139"> private DataSource getDataSource() {</span> +<span class="source-line-no">140</span><span id="line-140"> return dataSource;</span> +<span class="source-line-no">141</span><span id="line-141"> }</span> +<span class="source-line-no">142</span><span id="line-142"></span> +<span class="source-line-no">143</span><span id="line-143"> /**</span> +<span class="source-line-no">144</span><span id="line-144"> * Returns the {@code MimeBodyPart} that contains the encoded InlineImage data.</span> +<span class="source-line-no">145</span><span id="line-145"> *</span> +<span class="source-line-no">146</span><span id="line-146"> * @return the {@code MimeBodyPart} containing the encoded InlineImage data</span> +<span class="source-line-no">147</span><span id="line-147"> */</span> +<span class="source-line-no">148</span><span id="line-148"> private MimeBodyPart getMimeBodyPart() {</span> +<span class="source-line-no">149</span><span id="line-149"> return mimeBodyPart;</span> +<span class="source-line-no">150</span><span id="line-150"> }</span> +<span class="source-line-no">151</span><span id="line-151"></span> +<span class="source-line-no">152</span><span id="line-152"> @Override</span> +<span class="source-line-no">153</span><span id="line-153"> public int hashCode() {</span> +<span class="source-line-no">154</span><span id="line-154"> return Objects.hash(cid);</span> +<span class="source-line-no">155</span><span id="line-155"> }</span> +<span class="source-line-no">156</span><span id="line-156"> }</span> +<span class="source-line-no">157</span><span id="line-157"></span> +<span class="source-line-no">158</span><span id="line-158"> /** Definition of the length of generated CID's. */</span> +<span class="source-line-no">159</span><span id="line-159"> public static final int CID_LENGTH = 10;</span> +<span class="source-line-no">160</span><span id="line-160"></span> +<span class="source-line-no">161</span><span id="line-161"> /** Prefix for default HTML mail. */</span> +<span class="source-line-no">162</span><span id="line-162"> private static final String HTML_MESSAGE_START = "<html><body><pre>";</span> +<span class="source-line-no">163</span><span id="line-163"></span> +<span class="source-line-no">164</span><span id="line-164"> /** Suffix for default HTML mail. */</span> +<span class="source-line-no">165</span><span id="line-165"> private static final String HTML_MESSAGE_END = "</pre></body></html>";</span> +<span class="source-line-no">166</span><span id="line-166"></span> +<span class="source-line-no">167</span><span id="line-167"> /**</span> +<span class="source-line-no">168</span><span id="line-168"> * Text part of the message. This will be used as alternative text if the email client does not support HTML messages.</span> +<span class="source-line-no">169</span><span id="line-169"> */</span> +<span class="source-line-no">170</span><span id="line-170"> private String text;</span> +<span class="source-line-no">171</span><span id="line-171"></span> +<span class="source-line-no">172</span><span id="line-172"> /**</span> +<span class="source-line-no">173</span><span id="line-173"> * HTML part of the message.</span> +<span class="source-line-no">174</span><span id="line-174"> */</span> +<span class="source-line-no">175</span><span id="line-175"> private String html;</span> +<span class="source-line-no">176</span><span id="line-176"></span> +<span class="source-line-no">177</span><span id="line-177"> /**</span> +<span class="source-line-no">178</span><span id="line-178"> * Embedded images Map&lt;String, InlineImage&gt; where the key is the user-defined image name.</span> +<span class="source-line-no">179</span><span id="line-179"> */</span> +<span class="source-line-no">180</span><span id="line-180"> private final Map<String, InlineImage> inlineEmbeds = new HashMap<>();</span> +<span class="source-line-no">181</span><span id="line-181"></span> +<span class="source-line-no">182</span><span id="line-182"> /**</span> +<span class="source-line-no">183</span><span id="line-183"> * Constructs a new instance.</span> +<span class="source-line-no">184</span><span id="line-184"> */</span> +<span class="source-line-no">185</span><span id="line-185"> public HtmlEmail() {</span> +<span class="source-line-no">186</span><span id="line-186"> // empty</span> +<span class="source-line-no">187</span><span id="line-187"> }</span> +<span class="source-line-no">188</span><span id="line-188"></span> +<span class="source-line-no">189</span><span id="line-189"> /**</span> +<span class="source-line-no">190</span><span id="line-190"> * @throws EmailException EmailException</span> +<span class="source-line-no">191</span><span id="line-191"> * @throws MessagingException MessagingException</span> +<span class="source-line-no">192</span><span id="line-192"> */</span> +<span class="source-line-no">193</span><span id="line-193"> private void build() throws MessagingException, EmailException {</span> +<span class="source-line-no">194</span><span id="line-194"> final MimeMultipart rootContainer = getContainer();</span> +<span class="source-line-no">195</span><span id="line-195"> MimeMultipart bodyEmbedsContainer = rootContainer;</span> +<span class="source-line-no">196</span><span id="line-196"> MimeMultipart bodyContainer = rootContainer;</span> +<span class="source-line-no">197</span><span id="line-197"> MimeBodyPart msgHtml = null;</span> +<span class="source-line-no">198</span><span id="line-198"> MimeBodyPart msgText = null;</span> +<span class="source-line-no">199</span><span id="line-199"></span> +<span class="source-line-no">200</span><span id="line-200"> rootContainer.setSubType("mixed");</span> +<span class="source-line-no">201</span><span id="line-201"></span> +<span class="source-line-no">202</span><span id="line-202"> // determine how to form multiparts of email</span> +<span class="source-line-no">203</span><span id="line-203"></span> +<span class="source-line-no">204</span><span id="line-204"> if (EmailUtils.isNotEmpty(html) && !EmailUtils.isEmpty(inlineEmbeds)) {</span> +<span class="source-line-no">205</span><span id="line-205"> // If HTML body and embeds are used, create a related container and add it to the root container</span> +<span class="source-line-no">206</span><span id="line-206"> bodyEmbedsContainer = new MimeMultipart("related");</span> +<span class="source-line-no">207</span><span id="line-207"> bodyContainer = bodyEmbedsContainer;</span> +<span class="source-line-no">208</span><span id="line-208"> addPart(bodyEmbedsContainer, 0);</span> +<span class="source-line-no">209</span><span id="line-209"></span> +<span class="source-line-no">210</span><span id="line-210"> // If TEXT body was specified, create a alternative container and add it to the embeds container</span> +<span class="source-line-no">211</span><span id="line-211"> if (EmailUtils.isNotEmpty(text)) {</span> +<span class="source-line-no">212</span><span id="line-212"> bodyContainer = new MimeMultipart("alternative");</span> +<span class="source-line-no">213</span><span id="line-213"> final BodyPart bodyPart = createBodyPart();</span> +<span class="source-line-no">214</span><span id="line-214"> try {</span> +<span class="source-line-no">215</span><span id="line-215"> bodyPart.setContent(bodyContainer);</span> +<span class="source-line-no">216</span><span id="line-216"> bodyEmbedsContainer.addBodyPart(bodyPart, 0);</span> +<span class="source-line-no">217</span><span id="line-217"> } catch (final MessagingException e) {</span> +<span class="source-line-no">218</span><span id="line-218"> throw new EmailException(e);</span> +<span class="source-line-no">219</span><span id="line-219"> }</span> +<span class="source-line-no">220</span><span id="line-220"> }</span> +<span class="source-line-no">221</span><span id="line-221"> } else if (EmailUtils.isNotEmpty(text) && EmailUtils.isNotEmpty(html)) {</span> +<span class="source-line-no">222</span><span id="line-222"> // EMAIL-142: if we have both an HTML and TEXT body, but no attachments or</span> +<span class="source-line-no">223</span><span id="line-223"> // inline images, the root container should have mimetype</span> +<span class="source-line-no">224</span><span id="line-224"> // "multipart/alternative".</span> +<span class="source-line-no">225</span><span id="line-225"> // reference: https://tools.ietf.org/html/rfc2046#section-5.1.4</span> +<span class="source-line-no">226</span><span id="line-226"> if (!EmailUtils.isEmpty(inlineEmbeds) || isBoolHasAttachments()) {</span> +<span class="source-line-no">227</span><span id="line-227"> // If both HTML and TEXT bodies are provided, create an alternative</span> +<span class="source-line-no">228</span><span id="line-228"> // container and add it to the root container</span> +<span class="source-line-no">229</span><span id="line-229"> bodyContainer = new MimeMultipart("alternative");</span> +<span class="source-line-no">230</span><span id="line-230"> this.addPart(bodyContainer, 0);</span> +<span class="source-line-no">231</span><span id="line-231"> } else {</span> +<span class="source-line-no">232</span><span id="line-232"> // no attachments or embedded images present, change the mimetype</span> +<span class="source-line-no">233</span><span id="line-233"> // of the root container (= body container)</span> +<span class="source-line-no">234</span><span id="line-234"> rootContainer.setSubType("alternative");</span> +<span class="source-line-no">235</span><span id="line-235"> }</span> +<span class="source-line-no">236</span><span id="line-236"> }</span> +<span class="source-line-no">237</span><span id="line-237"></span> +<span class="source-line-no">238</span><span id="line-238"> if (EmailUtils.isNotEmpty(html)) {</span> +<span class="source-line-no">239</span><span id="line-239"> msgHtml = new MimeBodyPart();</span> +<span class="source-line-no">240</span><span id="line-240"> bodyContainer.addBodyPart(msgHtml, 0);</span> +<span class="source-line-no">241</span><span id="line-241"></span> +<span class="source-line-no">242</span><span id="line-242"> // EMAIL-104: call explicitly setText to use default mime charset</span> +<span class="source-line-no">243</span><span id="line-243"> // (property "mail.mime.charset") in case none has been set</span> +<span class="source-line-no">244</span><span id="line-244"> msgHtml.setText(html, getCharsetName(), EmailConstants.TEXT_SUBTYPE_HTML);</span> +<span class="source-line-no">245</span><span id="line-245"></span> +<span class="source-line-no">246</span><span id="line-246"> // EMAIL-147: work-around for buggy JavaMail implementations;</span> +<span class="source-line-no">247</span><span id="line-247"> // in case setText(...) does not set the correct content type,</span> +<span class="source-line-no">248</span><span id="line-248"> // use the setContent() method instead.</span> +<span class="source-line-no">249</span><span id="line-249"> final String contentType = msgHtml.getContentType();</span> +<span class="source-line-no">250</span><span id="line-250"> if (contentType == null || !contentType.equals(EmailConstants.TEXT_HTML)) {</span> +<span class="source-line-no">251</span><span id="line-251"> // apply default charset if one has been set</span> +<span class="source-line-no">252</span><span id="line-252"> if (EmailUtils.isNotEmpty(getCharsetName())) {</span> +<span class="source-line-no">253</span><span id="line-253"> msgHtml.setContent(html, EmailConstants.TEXT_HTML + "; charset=" + getCharsetName());</span> +<span class="source-line-no">254</span><span id="line-254"> } else {</span> +<span class="source-line-no">255</span><span id="line-255"> // unfortunately, MimeUtility.getDefaultMIMECharset() is package private</span> +<span class="source-line-no">256</span><span id="line-256"> // and thus can not be used to set the default system charset in case</span> +<span class="source-line-no">257</span><span id="line-257"> // no charset has been provided by the user</span> +<span class="source-line-no">258</span><span id="line-258"> msgHtml.setContent(html, EmailConstants.TEXT_HTML);</span> +<span class="source-line-no">259</span><span id="line-259"> }</span> +<span class="source-line-no">260</span><span id="line-260"> }</span> +<span class="source-line-no">261</span><span id="line-261"></span> +<span class="source-line-no">262</span><span id="line-262"> for (final InlineImage image : inlineEmbeds.values()) {</span> +<span class="source-line-no">263</span><span id="line-263"> bodyEmbedsContainer.addBodyPart(image.getMimeBodyPart());</span> +<span class="source-line-no">264</span><span id="line-264"> }</span> +<span class="source-line-no">265</span><span id="line-265"> }</span> +<span class="source-line-no">266</span><span id="line-266"></span> +<span class="source-line-no">267</span><span id="line-267"> if (EmailUtils.isNotEmpty(text)) {</span> +<span class="source-line-no">268</span><span id="line-268"> msgText = new MimeBodyPart();</span> +<span class="source-line-no">269</span><span id="line-269"> bodyContainer.addBodyPart(msgText, 0);</span> +<span class="source-line-no">270</span><span id="line-270"></span> +<span class="source-line-no">271</span><span id="line-271"> // EMAIL-104: call explicitly setText to use default mime charset</span> +<span class="source-line-no">272</span><span id="line-272"> // (property "mail.mime.charset") in case none has been set</span> +<span class="source-line-no">273</span><span id="line-273"> msgText.setText(text, getCharsetName());</span> +<span class="source-line-no">274</span><span id="line-274"> }</span> +<span class="source-line-no">275</span><span id="line-275"> }</span> +<span class="source-line-no">276</span><span id="line-276"></span> +<span class="source-line-no">277</span><span id="line-277"> /**</span> +<span class="source-line-no">278</span><span id="line-278"> * Builds the MimeMessage. Please note that a user rarely calls this method directly and only if he/she is interested in the sending the underlying</span> +<span class="source-line-no">279</span><span id="line-279"> * MimeMessage without commons-email.</span> +<span class="source-line-no">280</span><span id="line-280"> *</span> +<span class="source-line-no">281</span><span id="line-281"> * @throws EmailException if there was an error.</span> +<span class="source-line-no">282</span><span id="line-282"> * @since 1.0</span> +<span class="source-line-no">283</span><span id="line-283"> */</span> +<span class="source-line-no">284</span><span id="line-284"> @Override</span> +<span class="source-line-no">285</span><span id="line-285"> public void buildMimeMessage() throws EmailException {</span> +<span class="source-line-no">286</span><span id="line-286"> try {</span> +<span class="source-line-no">287</span><span id="line-287"> build();</span> +<span class="source-line-no">288</span><span id="line-288"> } catch (final MessagingException e) {</span> +<span class="source-line-no">289</span><span id="line-289"> throw new EmailException(e);</span> +<span class="source-line-no">290</span><span id="line-290"> }</span> +<span class="source-line-no">291</span><span id="line-291"> super.buildMimeMessage();</span> +<span class="source-line-no">292</span><span id="line-292"> }</span> +<span class="source-line-no">293</span><span id="line-293"></span> +<span class="source-line-no">294</span><span id="line-294"> /**</span> +<span class="source-line-no">295</span><span id="line-295"> * Embeds the specified {@code DataSource} in the HTML using a randomly generated Content-ID. Returns the generated Content-ID string.</span> +<span class="source-line-no">296</span><span id="line-296"> *</span> +<span class="source-line-no">297</span><span id="line-297"> * @param dataSource the {@code DataSource} to embed</span> +<span class="source-line-no">298</span><span id="line-298"> * @param name the name that will be set in the file name header field</span> +<span class="source-line-no">299</span><span id="line-299"> * @return the generated Content-ID for this {@code DataSource}</span> +<span class="source-line-no">300</span><span id="line-300"> * @throws EmailException if the embedding fails or if {@code name} is null or empty</span> +<span class="source-line-no">301</span><span id="line-301"> * @see #embed(DataSource, String, String)</span> +<span class="source-line-no">302</span><span id="line-302"> * @since 1.1</span> +<span class="source-line-no">303</span><span id="line-303"> */</span> +<span class="source-line-no">304</span><span id="line-304"> public String embed(final DataSource dataSource, final String name) throws EmailException {</span> +<span class="source-line-no">305</span><span id="line-305"> // check if the DataSource has already been attached;</span> +<span class="source-line-no">306</span><span id="line-306"> // if so, return the cached CID value.</span> +<span class="source-line-no">307</span><span id="line-307"> final InlineImage inlineImage = inlineEmbeds.get(name);</span> +<span class="source-line-no">308</span><span id="line-308"> if (inlineImage != null) {</span> +<span class="source-line-no">309</span><span id="line-309"> // make sure the supplied URL points to the same thing</span> +<span class="source-line-no">310</span><span id="line-310"> // as the one already associated with this name.</span> +<span class="source-line-no">311</span><span id="line-311"> if (dataSource.equals(inlineImage.getDataSource())) {</span> +<span class="source-line-no">312</span><span id="line-312"> return inlineImage.getCid();</span> +<span class="source-line-no">313</span><span id="line-313"> }</span> +<span class="source-line-no">314</span><span id="line-314"> throw new EmailException("embedded DataSource '" + name + "' is already bound to name " + inlineImage.getDataSource().toString()</span> +<span class="source-line-no">315</span><span id="line-315"> + "; existing names cannot be rebound");</span> +<span class="source-line-no">316</span><span id="line-316"> }</span> +<span class="source-line-no">317</span><span id="line-317"></span> +<span class="source-line-no">318</span><span id="line-318"> final String cid = EmailUtils.toLower(EmailUtils.randomAlphabetic(CID_LENGTH));</span> +<span class="source-line-no">319</span><span id="line-319"> return embed(dataSource, name, cid);</span> +<span class="source-line-no">320</span><span id="line-320"> }</span> +<span class="source-line-no">321</span><span id="line-321"></span> +<span class="source-line-no">322</span><span id="line-322"> /**</span> +<span class="source-line-no">323</span><span id="line-323"> * Embeds the specified {@code DataSource} in the HTML using the specified Content-ID. Returns the specified Content-ID string.</span> +<span class="source-line-no">324</span><span id="line-324"> *</span> +<span class="source-line-no">325</span><span id="line-325"> * @param dataSource the {@code DataSource} to embed</span> +<span class="source-line-no">326</span><span id="line-326"> * @param name the name that will be set in the file name header field</span> +<span class="source-line-no">327</span><span id="line-327"> * @param cid the Content-ID to use for this {@code DataSource}</span> +<span class="source-line-no">328</span><span id="line-328"> * @return the URL encoded Content-ID for this {@code DataSource}</span> +<span class="source-line-no">329</span><span id="line-329"> * @throws EmailException if the embedding fails or if {@code name} is null or empty</span> +<span class="source-line-no">330</span><span id="line-330"> * @since 1.1</span> +<span class="source-line-no">331</span><span id="line-331"> */</span> +<span class="source-line-no">332</span><span id="line-332"> public String embed(final DataSource dataSource, final String name, final String cid) throws EmailException {</span> +<span class="source-line-no">333</span><span id="line-333"> EmailException.checkNonEmpty(name, () -> "Name cannot be null or empty");</span> +<span class="source-line-no">334</span><span id="line-334"> final MimeBodyPart mbp = new MimeBodyPart();</span> +<span class="source-line-no">335</span><span id="line-335"> try {</span> +<span class="source-line-no">336</span><span id="line-336"> // URL encode the cid according to RFC 2392</span> +<span class="source-line-no">337</span><span id="line-337"> final String encodedCid = EmailUtils.encodeUrl(cid);</span> +<span class="source-line-no">338</span><span id="line-338"> mbp.setDataHandler(new DataHandler(dataSource));</span> +<span class="source-line-no">339</span><span id="line-339"> mbp.setFileName(name);</span> +<span class="source-line-no">340</span><span id="line-340"> mbp.setDisposition(EmailAttachment.INLINE);</span> +<span class="source-line-no">341</span><span id="line-341"> mbp.setContentID("<" + encodedCid + ">");</span> +<span class="source-line-no">342</span><span id="line-342"> this.inlineEmbeds.put(name, new InlineImage(encodedCid, dataSource, mbp));</span> +<span class="source-line-no">343</span><span id="line-343"> return encodedCid;</span> +<span class="source-line-no">344</span><span id="line-344"> } catch (final MessagingException e) {</span> +<span class="source-line-no">345</span><span id="line-345"> throw new EmailException(e);</span> +<span class="source-line-no">346</span><span id="line-346"> }</span> +<span class="source-line-no">347</span><span id="line-347"> }</span> +<span class="source-line-no">348</span><span id="line-348"></span> +<span class="source-line-no">349</span><span id="line-349"> /**</span> +<span class="source-line-no">350</span><span id="line-350"> * Embeds a file in the HTML. This implementation delegates to {@link #embed(File, String)}.</span> +<span class="source-line-no">351</span><span id="line-351"> *</span> +<span class="source-line-no">352</span><span id="line-352"> * @param file The {@code File} object to embed</span> +<span class="source-line-no">353</span><span id="line-353"> * @return A String with the Content-ID of the file.</span> +<span class="source-line-no">354</span><span id="line-354"> * @throws EmailException when the supplied {@code File} cannot be used; also see {@link javax.mail.internet.MimeBodyPart} for definitions</span> +<span class="source-line-no">355</span><span id="line-355"> *</span> +<span class="source-line-no">356</span><span id="line-356"> * @see #embed(File, String)</span> +<span class="source-line-no">357</span><span id="line-357"> * @since 1.1</span> +<span class="source-line-no">358</span><span id="line-358"> */</span> +<span class="source-line-no">359</span><span id="line-359"> public String embed(final File file) throws EmailException {</span> +<span class="source-line-no">360</span><span id="line-360"> return embed(file, EmailUtils.toLower(EmailUtils.randomAlphabetic(CID_LENGTH)));</span> +<span class="source-line-no">361</span><span id="line-361"> }</span> +<span class="source-line-no">362</span><span id="line-362"></span> +<span class="source-line-no">363</span><span id="line-363"> /**</span> +<span class="source-line-no">364</span><span id="line-364"> * Embeds a file in the HTML.</span> +<span class="source-line-no">365</span><span id="line-365"> *</span> +<span class="source-line-no">366</span><span id="line-366"> * <p></span> +<span class="source-line-no">367</span><span id="line-367"> * This method embeds a file located by an URL into the mail body. It allows, for instance, to add inline images to the email. Inline files may be</span> +<span class="source-line-no">368</span><span id="line-368"> * referenced with a {@code cid:xxxxxx} URL, where xxxxxx is the Content-ID returned by the embed function. Files are bound to their names, which is the</span> +<span class="source-line-no">369</span><span id="line-369"> * value returned by {@link java.io.File#getName()}. If the same file is embedded multiple times, the same CID is guaranteed to be returned.</span> +<span class="source-line-no">370</span><span id="line-370"> *</span> +<span class="source-line-no">371</span><span id="line-371"> * <p></span> +<span class="source-line-no">372</span><span id="line-372"> * While functionally the same as passing {@code FileDataSource} to {@link #embed(DataSource, String, String)}, this method attempts to validate the file</span> +<span class="source-line-no">373</span><span id="line-373"> * before embedding it in the message and will throw {@code EmailException} if the validation fails. In this case, the {@code HtmlEmail} object will not be</span> +<span class="source-line-no">374</span><span id="line-374"> * changed.</span> +<span class="source-line-no">375</span><span id="line-375"> *</span> +<span class="source-line-no">376</span><span id="line-376"> * @param file The {@code File} to embed</span> +<span class="source-line-no">377</span><span id="line-377"> * @param cid the Content-ID to use for the embedded {@code File}</span> +<span class="source-line-no">378</span><span id="line-378"> * @return A String with the Content-ID of the file.</span> +<span class="source-line-no">379</span><span id="line-379"> * @throws EmailException when the supplied {@code File} cannot be used or if the file has already been embedded; also see</span> +<span class="source-line-no">380</span><span id="line-380"> * {@link javax.mail.internet.MimeBodyPart} for definitions</span> +<span class="source-line-no">381</span><span id="line-381"> * @since 1.1</span> +<span class="source-line-no">382</span><span id="line-382"> */</span> +<span class="source-line-no">383</span><span id="line-383"> public String embed(final File file, final String cid) throws EmailException {</span> +<span class="source-line-no">384</span><span id="line-384"> EmailException.checkNonEmpty(file.getName(), () -> "File name cannot be null or empty");</span> +<span class="source-line-no">385</span><span id="line-385"></span> +<span class="source-line-no">386</span><span id="line-386"> // verify that the File can provide a canonical path</span> +<span class="source-line-no">387</span><span id="line-387"> String filePath = null;</span> +<span class="source-line-no">388</span><span id="line-388"> try {</span> +<span class="source-line-no">389</span><span id="line-389"> filePath = file.getCanonicalPath();</span> +<span class="source-line-no">390</span><span id="line-390"> } catch (final IOException e) {</span> +<span class="source-line-no">391</span><span id="line-391"> throw new EmailException("couldn't get canonical path for " + file.getName(), e);</span> +<span class="source-line-no">392</span><span id="line-392"> }</span> +<span class="source-line-no">393</span><span id="line-393"></span> +<span class="source-line-no">394</span><span id="line-394"> // check if a FileDataSource for this name has already been attached;</span> +<span class="source-line-no">395</span><span id="line-395"> // if so, return the cached CID value.</span> +<span class="source-line-no">396</span><span id="line-396"> final InlineImage inlineImage = inlineEmbeds.get(file.getName());</span> +<span class="source-line-no">397</span><span id="line-397"> if (inlineImage != null) {</span> +<span class="source-line-no">398</span><span id="line-398"> final FileDataSource fileDataSource = (FileDataSource) inlineImage.getDataSource();</span> +<span class="source-line-no">399</span><span id="line-399"> // make sure the supplied file has the same canonical path</span> +<span class="source-line-no">400</span><span id="line-400"> // as the one already associated with this name.</span> +<span class="source-line-no">401</span><span id="line-401"> String existingFilePath = null;</span> +<span class="source-line-no">402</span><span id="line-402"> try {</span> +<span class="source-line-no">403</span><span id="line-403"> existingFilePath = fileDataSource.getFile().getCanonicalPath();</span> +<span class="source-line-no">404</span><span id="line-404"> } catch (final IOException e) {</span> +<span class="source-line-no">405</span><span id="line-405"> throw new EmailException("couldn't get canonical path for file " + fileDataSource.getFile().getName() + "which has already been embedded", e);</span> +<span class="source-line-no">406</span><span id="line-406"> }</span> +<span class="source-line-no">407</span><span id="line-407"> if (filePath.equals(existingFilePath)) {</span> +<span class="source-line-no">408</span><span id="line-408"> return inlineImage.getCid();</span> +<span class="source-line-no">409</span><span id="line-409"> }</span> +<span class="source-line-no">410</span><span id="line-410"> throw new EmailException(</span> +<span class="source-line-no">411</span><span id="line-411"> "embedded name '" + file.getName() + "' is already bound to file " + existingFilePath + "; existing names cannot be rebound");</span> +<span class="source-line-no">412</span><span id="line-412"> }</span> +<span class="source-line-no">413</span><span id="line-413"></span> +<span class="source-line-no">414</span><span id="line-414"> // verify that the file is valid</span> +<span class="source-line-no">415</span><span id="line-415"> if (!file.exists()) {</span> +<span class="source-line-no">416</span><span id="line-416"> throw new EmailException("file " + filePath + " doesn't exist");</span> +<span class="source-line-no">417</span><span id="line-417"> }</span> +<span class="source-line-no">418</span><span id="line-418"> if (!file.isFile()) {</span> +<span class="source-line-no">419</span><span id="line-419"> throw new EmailException("file " + filePath + " isn't a normal file");</span> +<span class="source-line-no">420</span><span id="line-420"> }</span> +<span class="source-line-no">421</span><span id="line-421"> if (!file.canRead()) {</span> +<span class="source-line-no">422</span><span id="line-422"> throw new EmailException("file " + filePath + " isn't readable");</span> +<span class="source-line-no">423</span><span id="line-423"> }</span> +<span class="source-line-no">424</span><span id="line-424"></span> +<span class="source-line-no">425</span><span id="line-425"> return embed(new FileDataSource(file), file.getName(), cid);</span> +<span class="source-line-no">426</span><span id="line-426"> }</span> +<span class="source-line-no">427</span><span id="line-427"></span> +<span class="source-line-no">428</span><span id="line-428"> /**</span> +<span class="source-line-no">429</span><span id="line-429"> * Parses the specified {@code String} as a URL that will then be embedded in the message.</span> +<span class="source-line-no">430</span><span id="line-430"> *</span> +<span class="source-line-no">431</span><span id="line-431"> * @param urlString String representation of the URL.</span> +<span class="source-line-no">432</span><span id="line-432"> * @param name The name that will be set in the file name header field.</span> +<span class="source-line-no">433</span><span id="line-433"> * @return A String with the Content-ID of the URL.</span> +<span class="source-line-no">434</span><span id="line-434"> * @throws EmailException when URL supplied is invalid or if {@code name} is null or empty; also see {@link javax.mail.internet.MimeBodyPart} for</span> +<span class="source-line-no">435</span><span id="line-435"> * definitions</span> +<span class="source-line-no">436</span><span id="line-436"> *</span> +<span class="source-line-no">437</span><span id="line-437"> * @see #embed(URL, String)</span> +<span class="source-line-no">438</span><span id="line-438"> * @since 1.1</span> +<span class="source-line-no">439</span><span id="line-439"> */</span> +<span class="source-line-no">440</span><span id="line-440"> public String embed(final String urlString, final String name) throws EmailException {</span> +<span class="source-line-no">441</span><span id="line-441"> try {</span> +<span class="source-line-no">442</span><span id="line-442"> return embed(new URL(urlString), name);</span> +<span class="source-line-no">443</span><span id="line-443"> } catch (final MalformedURLException e) {</span> +<span class="source-line-no">444</span><span id="line-444"> throw new EmailException("Invalid URL", e);</span> +<span class="source-line-no">445</span><span id="line-445"> }</span> +<span class="source-line-no">446</span><span id="line-446"> }</span> +<span class="source-line-no">447</span><span id="line-447"></span> +<span class="source-line-no">448</span><span id="line-448"> /**</span> +<span class="source-line-no">449</span><span id="line-449"> * Embeds an URL in the HTML.</span> +<span class="source-line-no">450</span><span id="line-450"> *</span> +<span class="source-line-no">451</span><span id="line-451"> * <p></span> +<span class="source-line-no">452</span><span id="line-452"> * This method embeds a file located by an URL into the mail body. It allows, for instance, to add inline images to the email. Inline files may be</span> +<span class="source-line-no">453</span><span id="line-453"> * referenced with a {@code cid:xxxxxx} URL, where xxxxxx is the Content-ID returned by the embed function. It is an error to bind the same name to more</span> +<span class="source-line-no">454</span><span id="line-454"> * than one URL; if the same URL is embedded multiple times, the same Content-ID is guaranteed to be returned.</span> +<span class="source-line-no">455</span><span id="line-455"> * </p></span> +<span class="source-line-no">456</span><span id="line-456"> * <p></span> +<span class="source-line-no">457</span><span id="line-457"> * While functionally the same as passing {@code URLDataSource} to {@link #embed(DataSource, String, String)}, this method attempts to validate the URL</span> +<span class="source-line-no">458</span><span id="line-458"> * before embedding it in the message and will throw {@code EmailException} if the validation fails. In this case, the {@code HtmlEmail} object will not be</span> +<span class="source-line-no">459</span><span id="line-459"> * changed.</span> +<span class="source-line-no">460</span><span id="line-460"> * </p></span> +<span class="source-line-no">461</span><span id="line-461"> * <p></span> +<span class="source-line-no">462</span><span id="line-462"> * NOTE: Clients should take care to ensure that different URLs are bound to different names. This implementation tries to detect this and throw</span> +<span class="source-line-no">463</span><span id="line-463"> * {@code EmailException}. However, it is not guaranteed to catch all cases, especially when the URL refers to a remote HTTP host that may be part of a</span> +<span class="source-line-no">464</span><span id="line-464"> * virtual host cluster.</span> +<span class="source-line-no">465</span><span id="line-465"> * </p></span> +<span class="source-line-no">466</span><span id="line-466"> *</span> +<span class="source-line-no">467</span><span id="line-467"> * @param url The URL of the file.</span> +<span class="source-line-no">468</span><span id="line-468"> * @param name The name that will be set in the file name header field.</span> +<span class="source-line-no">469</span><span id="line-469"> * @return A String with the Content-ID of the file.</span> +<span class="source-line-no">470</span><span id="line-470"> * @throws EmailException when URL supplied is invalid or if {@code name} is null or empty; also see {@link javax.mail.internet.MimeBodyPart} for</span> +<span class="source-line-no">471</span><span id="line-471"> * definitions</span> +<span class="source-line-no">472</span><span id="line-472"> * @since 1.0</span> +<span class="source-line-no">473</span><span id="line-473"> */</span> +<span class="source-line-no">474</span><span id="line-474"> public String embed(final URL url, final String name) throws EmailException {</span> +<span class="source-line-no">475</span><span id="line-475"> EmailException.checkNonEmpty(name, () -> "Name cannot be null or empty");</span> +<span class="source-line-no">476</span><span id="line-476"> // check if a URLDataSource for this name has already been attached;</span> +<span class="source-line-no">477</span><span id="line-477"> // if so, return the cached CID value.</span> +<span class="source-line-no">478</span><span id="line-478"> final InlineImage inlineImage = inlineEmbeds.get(name);</span> +<span class="source-line-no">479</span><span id="line-479"> if (inlineImage != null) {</span> +<span class="source-line-no">480</span><span id="line-480"> final URLDataSource urlDataSource = (URLDataSource) inlineImage.getDataSource();</span> +<span class="source-line-no">481</span><span id="line-481"> // make sure the supplied URL points to the same thing</span> +<span class="source-line-no">482</span><span id="line-482"> // as the one already associated with this name.</span> +<span class="source-line-no">483</span><span id="line-483"> // NOTE: Comparing URLs with URL.equals() is a blocking operation</span> +<span class="source-line-no">484</span><span id="line-484"> // in the case of a network failure therefore we use</span> +<span class="source-line-no">485</span><span id="line-485"> // url.toExternalForm().equals() here.</span> +<span class="source-line-no">486</span><span id="line-486"> if (url.toExternalForm().equals(urlDataSource.getURL().toExternalForm())) {</span> +<span class="source-line-no">487</span><span id="line-487"> return inlineImage.getCid();</span> +<span class="source-line-no">488</span><span id="line-488"> }</span> +<span class="source-line-no">489</span><span id="line-489"> throw new EmailException("embedded name '" + name + "' is already bound to URL " + urlDataSource.getURL() + "; existing names cannot be rebound");</span> +<span class="source-line-no">490</span><span id="line-490"> }</span> +<span class="source-line-no">491</span><span id="line-491"> // verify that the URL is valid</span> +<span class="source-line-no">492</span><span id="line-492"> try (InputStream inputStream = url.openStream()) {</span> +<span class="source-line-no">493</span><span id="line-493"> // Make sure we can read.</span> +<span class="source-line-no">494</span><span id="line-494"> inputStream.read();</span> +<span class="source-line-no">495</span><span id="line-495"> } catch (final IOException e) {</span> +<span class="source-line-no">496</span><span id="line-496"> throw new EmailException("Invalid URL", e);</span> +<span class="source-line-no">497</span><span id="line-497"> }</span> +<span class="source-line-no">498</span><span id="line-498"> return embed(new URLDataSource(url), name);</span> +<span class="source-line-no">499</span><span id="line-499"> }</span> +<span class="source-line-no">500</span><span id="line-500"></span> +<span class="source-line-no">501</span><span id="line-501"> /**</span> +<span class="source-line-no">502</span><span id="line-502"> * Gets the HTML content.</span> +<span class="source-line-no">503</span><span id="line-503"> *</span> +<span class="source-line-no">504</span><span id="line-504"> * @return the HTML content.</span> +<span class="source-line-no">505</span><span id="line-505"> * @since 1.6.0</span> +<span class="source-line-no">506</span><span id="line-506"> */</span> +<span class="source-line-no">507</span><span id="line-507"> public String getHtml() {</span> +<span class="source-line-no">508</span><span id="line-508"> return html;</span> +<span class="source-line-no">509</span><span id="line-509"> }</span> +<span class="source-line-no">510</span><span id="line-510"></span> +<span class="source-line-no">511</span><span id="line-511"> /**</span> +<span class="source-line-no">512</span><span id="line-512"> * Gets the message text.</span> +<span class="source-line-no">513</span><span id="line-513"> *</span> +<span class="source-line-no">514</span><span id="line-514"> * @return the message text.</span> +<span class="source-line-no">515</span><span id="line-515"> * @since 1.6.0</span> +<span class="source-line-no">516</span><span id="line-516"> */</span> +<span class="source-line-no">517</span><span id="line-517"> public String getText() {</span> +<span class="source-line-no">518</span><span id="line-518"> return text;</span> +<span class="source-line-no">519</span><span id="line-519"> }</span> +<span class="source-line-no">520</span><span id="line-520"></span> +<span class="source-line-no">521</span><span id="line-521"> /**</span> +<span class="source-line-no">522</span><span id="line-522"> * Sets the HTML content.</span> +<span class="source-line-no">523</span><span id="line-523"> *</span> +<span class="source-line-no">524</span><span id="line-524"> * @param html A String.</span> +<span class="source-line-no">525</span><span id="line-525"> * @return An HtmlEmail.</span> +<span class="source-line-no">526</span><span id="line-526"> * @throws EmailException see javax.mail.internet.MimeBodyPart for definitions</span> +<span class="source-line-no">527</span><span id="line-527"> * @since 1.0</span> +<span class="source-line-no">528</span><span id="line-528"> */</span> +<span class="source-line-no">529</span><span id="line-529"> public HtmlEmail setHtmlMsg(final String html) throws EmailException {</span> +<span class="source-line-no">530</span><span id="line-530"> this.html = EmailException.checkNonEmpty(html, () -> "Invalid message.");</span> +<span class="source-line-no">531</span><span id="line-531"> return this;</span> +<span class="source-line-no">532</span><span id="line-532"> }</span> +<span class="source-line-no">533</span><span id="line-533"></span> +<span class="source-line-no">534</span><span id="line-534"> /**</span> +<span class="source-line-no">535</span><span id="line-535"> * Sets the message.</span> +<span class="source-line-no">536</span><span id="line-536"> *</span> +<span class="source-line-no">537</span><span id="line-537"> * <p></span> +<span class="source-line-no">538</span><span id="line-538"> * This method overrides {@link MultiPartEmail#setMsg(String)} in order to send an HTML message instead of a plain text message in the mail body. The</span> +<span class="source-line-no">539</span><span id="line-539"> * message is formatted in HTML for the HTML part of the message; it is left as is in the alternate text part.</span> +<span class="source-line-no">540</span><span id="line-540"> * </p></span> +<span class="source-line-no">541</span><span id="line-541"> *</span> +<span class="source-line-no">542</span><span id="line-542"> * @param msg the message text to use</span> +<span class="source-line-no">543</span><span id="line-543"> * @return this {@code HtmlEmail}</span> +<span class="source-line-no">544</span><span id="line-544"> * @throws EmailException if msg is null or empty; see javax.mail.internet.MimeBodyPart for definitions</span> +<span class="source-line-no">545</span><span id="line-545"> * @since 1.0</span> +<span class="source-line-no">546</span><span id="line-546"> */</span> +<span class="source-line-no">547</span><span id="line-547"> @Override</span> +<span class="source-line-no">548</span><span id="line-548"> public Email setMsg(final String msg) throws EmailException {</span> +<span class="source-line-no">549</span><span id="line-549"> setTextMsg(msg);</span> +<span class="source-line-no">550</span><span id="line-550"> final StringBuilder htmlMsgBuf = new StringBuilder(msg.length() + HTML_MESSAGE_START.length() + HTML_MESSAGE_END.length());</span> +<span class="source-line-no">551</span><span id="line-551"> htmlMsgBuf.append(HTML_MESSAGE_START).append(msg).append(HTML_MESSAGE_END);</span> +<span class="source-line-no">552</span><span id="line-552"> setHtmlMsg(htmlMsgBuf.toString());</span> +<span class="source-line-no">553</span><span id="line-553"> return this;</span> +<span class="source-line-no">554</span><span id="line-554"> }</span> +<span class="source-line-no">555</span><span id="line-555"></span> +<span class="source-line-no">556</span><span id="line-556"> /**</span> +<span class="source-line-no">557</span><span id="line-557"> * Sets the text content.</span> +<span class="source-line-no">558</span><span id="line-558"> *</span> +<span class="source-line-no">559</span><span id="line-559"> * @param text A String.</span> +<span class="source-line-no">560</span><span id="line-560"> * @return An HtmlEmail.</span> +<span class="source-line-no">561</span><span id="line-561"> * @throws EmailException see javax.mail.internet.MimeBodyPart for definitions</span> +<span class="source-line-no">562</span><span id="line-562"> * @since 1.0</span> +<span class="source-line-no">563</span><span id="line-563"> */</span> +<span class="source-line-no">564</span><span id="line-564"> public HtmlEmail setTextMsg(final String text) throws EmailException {</span> +<span class="source-line-no">565</span><span id="line-565"> this.text = EmailException.checkNonEmpty(text, () -> "Invalid message.");</span> +<span class="source-line-no">566</span><span id="line-566"> return this;</span> +<span class="source-line-no">567</span><span id="line-567"> }</span> +<span class="source-line-no">568</span><span id="line-568">}</span> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +</pre> +</div> +</main> +</body> +</html>
