/bbottema/simple-java-mail/issues/121: Added documentation on using a custom mailer

Author: bbottema

Diff for: dist/Features.html

@@ -148,7 +148,8 @@ <h3>Builders all the way down</h3>
       <li><a href="#section-reply-forward">Replying to and forwarding emails</a></li>
       <li><a href="#section-proxy">Send using a proxy</a></li>
       <li><a href="#section-connection-test">Testing a server connection</a></li>
-		<li><a href="#section-serializing-emails">Serializing Email objects</a></li>
+      <li><a href="#section-serializing-emails">Serializing Email objects</a></li>
+      <li><a href="#section-custom-mailer">Plug your own sending logic!</a></li>
     </ul>
   </section>
 
@@ -1214,6 +1215,40 @@ <h2>Serializing Email objects</h2>
       </ul>
 	</section>
 
+
+	<a href="#section-custom-mailer" id="section-custom-mailer" class="section-link h2">&sect;</a>
+	<h2>Plug your own sending logic!</h2>
+
+	<section>
+        <p class="wide">
+          You want to benefit from Simple Java Mail's powerful features, but want to replace the actual
+            server testing and email sending with your own? <br/>Simple Java Mail's got your back!
+        </p>
+
+    <hr/>
+        <div class="wide">
+          <p>Send mail using MailGun REST API:</p>
+		    <pre><code>Mailer mailGunMailer = MailerBuilder
+      .(..)
+      .withCustomMailer(new MailGunMailer())
+      .buildMailer();
+</code></pre>
+		    <pre><code>public class MailGunMailer implements CustomMailer {
+
+	@Override
+	public void testConnection(OperationalConfig operationalConfig, Session session) {
+		// call MailGun rest service to test the provided config
+	}
+
+	@Override
+	public void sendMessage(OperationalConfig operationalConfig, Session session, Email email, MimeMessage message) {
+		// call MailGun rest service to send the email!
+	}
+}
+  </code></pre>
+      </div>
+	</section>
+
 </div>
 
 		</main>

Diff for: dist/configuration.html

@@ -399,8 +399,11 @@ <h3>Programmatic API - other settings</h3>
 // this negates all related properties such as pool size and keepAliveTime
 currentMailerBuilder.withExecutorService(new MyAwesomeCustomThreadPoolExecutor())
 </code></pre>
-      <pre><code class="small">// change the SMTP session timeout (affects socket connect-, read- and write timeouts)
+		  <pre><code class="small">// change the SMTP session timeout (affects socket connect-, read- and write timeouts)
 currentMailerBuilder.withSessionTimeout(10 * 1000); // 10 seconds for quick disconnect
+</code></pre>
+		  <pre><code class="small">// change the default sending logic to your own approach
+currentMailerBuilder.withCustomMailer(yourOwnMailSenderImpl); // send emails, test connections
 </code></pre>
     </div>
   </section>

Diff for: src/pages/Features.hbs

@@ -90,7 +90,8 @@
       <li><a href="#section-reply-forward">Replying to and forwarding emails</a></li>
       <li><a href="#section-proxy">Send using a proxy</a></li>
       <li><a href="#section-connection-test">Testing a server connection</a></li>
-		<li><a href="#section-serializing-emails">Serializing Email objects</a></li>
+      <li><a href="#section-serializing-emails">Serializing Email objects</a></li>
+      <li><a href="#section-custom-mailer">Plug your own sending logic!</a></li>
     </ul>
   </section>
 
@@ -1156,6 +1157,40 @@ mailer.testConnection(/* async? */); // no error means success
       </ul>
 	</section>
 
+
+	<a href="#section-custom-mailer" id="section-custom-mailer" class="section-link h2">&sect;</a>
+	<h2>Plug your own sending logic!</h2>
+
+	<section>
+        <p class="wide">
+          You want to benefit from Simple Java Mail's powerful features, but want to replace the actual
+            server testing and email sending with your own? <br/>Simple Java Mail's got your back!
+        </p>
+
+    <hr/>
+        <div class="wide">
+          <p>Send mail using MailGun REST API:</p>
+		    <pre><code>Mailer mailGunMailer = MailerBuilder
+      .(..)
+      .withCustomMailer(new MailGunMailer())
+      .buildMailer();
+</code></pre>
+		    <pre><code>public class MailGunMailer implements CustomMailer {
+
+	@Override
+	public void testConnection(OperationalConfig operationalConfig, Session session) {
+		// call MailGun rest service to test the provided config
+	}
+
+	@Override
+	public void sendMessage(OperationalConfig operationalConfig, Session session, Email email, MimeMessage message) {
+		// call MailGun rest service to send the email!
+	}
+}
+  </code></pre>
+      </div>
+	</section>
+
 </div>
     {{/inline}}
 

Diff for: src/pages/configuration.hbs

@@ -341,8 +341,11 @@ currentMailerBuilder.withKeepAliveTime(5000);
 // this negates all related properties such as pool size and keepAliveTime
 currentMailerBuilder.withExecutorService(new MyAwesomeCustomThreadPoolExecutor())
 </code></pre>
-      <pre><code class="small">// change the SMTP session timeout (affects socket connect-, read- and write timeouts)
+		  <pre><code class="small">// change the SMTP session timeout (affects socket connect-, read- and write timeouts)
 currentMailerBuilder.withSessionTimeout(10 * 1000); // 10 seconds for quick disconnect
+</code></pre>
+		  <pre><code class="small">// change the default sending logic to your own approach
+currentMailerBuilder.withCustomMailer(yourOwnMailSenderImpl); // send emails, test connections
 </code></pre>
     </div>
   </section>