Skip to content

Commit 582d67d

Browse files
bbottemabbottema
committed
#156: Started documenting CLI support
1 parent 6f1b149 commit 582d67d

File tree

10 files changed

+111
-32
lines changed

10 files changed

+111
-32
lines changed

Diff for: ‎src/app.ts

+2
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ import {Ng2SimplePageScrollModule} from 'ng2-simple-page-scroll/ng2-simple-page-
1010

1111
import {About} from './app/components/about/about';
1212
import {Features} from './app/components/features/features';
13+
import {Cli} from './app/components/cli/cli';
1314
import {Configuration} from './app/components/configuration/configuration';
1415
import {Debugging} from './app/components/debugging/debugging';
1516
import {RfcCompliant} from './app/components/rfc/rfc';
@@ -27,6 +28,7 @@ require('./index.html');
2728
SimpleJavaMailApp,
2829
About,
2930
Features,
31+
Cli,
3032
Configuration,
3133
Debugging,
3234
RfcCompliant,

Diff for: ‎src/app/assets/cli_example.png

45.3 KB
Loading

Diff for: ‎src/app/components/about/about.html

+7-16
Original file line numberDiff line numberDiff line change
@@ -63,26 +63,17 @@ <h3>Simple Java Mail: Simple API, Complex Emails</h3>
6363
.withDebugLogging(true)
6464
.buildMailer();
6565

66-
mailer.sendMail(email);
67-
</code></pre>
66+
mailer.sendMail(email);</code></pre>
6867
</div>
6968
</section>
7069

71-
72-
<a href="#section-getting-started" id="section-getting-started" class="section-link h2">&sect;</a>
73-
<h2>Getting started</h2>
74-
7570
<section>
76-
<div class="view">
77-
<p>Simple Java Mail is a thin layer on top of Oracle's SMTP JavaMail API. For logging purposes, SLF4J is used so
78-
you can use whatever
79-
logging framework you prefer.</p>
80-
<p>Once the dependencies are set up, simply copy the above examples and start mailing!</p>
81-
<p class="button-group">
82-
<a class="button" [routerLink]="['/features']" simplePageScroll href="#navigation">Show Examples</a>
83-
<a class="button" href="http://www.javadoc.io/doc/org.simplejavamail/simple-java-mail">API
84-
Javadoc</a>
85-
</p>
71+
<div class="wide">
72+
What about CLI?
73+
<pre><code>
74+
java -cp all;the;jars.jar org.simplejavamail.cli.SimpleJavaMail --help
75+
</code></pre>
76+
<img src="../../assets/cli_example.png" style="width: 100%;">
8677
</div>
8778
</section>
8879
</div>

Diff for: ‎src/app/components/cli/cli.html

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
<div class="content">
2+
3+
<h1>Simple Java Mail Command Line Interface</h1>
4+
5+
<section class="introduction">
6+
<p class="wide">
7+
Simple Java Mail exposes the complete builder API as CLI commands, which is to say everything you can do with
8+
Simple Java Mail in Java, you can also do that in a terminal.
9+
</p>
10+
11+
<h3>From builder API to CLI commands</h3>
12+
13+
<p class="wide">
14+
To support CLI, the commands and options are generated using <a href="https://picocli.info/">Picocli's Java API</a>
15+
and <a href="https://github.com/dnault/therapi-runtime-javadoc">Therapi's Javadoc bundler</a>. Together with a
16+
lot of custom glue Simple Java Mail's builder API is traversed and converted into CLI commands.
17+
</p>
18+
<p class="wide">
19+
The great benefit from this is that new builder API is supported by CLI automagically and the documentation is
20+
still centralized in the builder API.
21+
</p>
22+
</section>
23+
24+
<section>
25+
<h2>Usage Help</h2>
26+
<p>You can get usage information displayed on any level:</p>
27+
<table>
28+
<colgroup>
29+
<col span="1" style="width: 15%;">
30+
<col span="1" style="width: 40%;">
31+
<col span="1">
32+
</colgroup>
33+
34+
<!-- Put <thead>, <tbody>, and <tr>'s here! -->
35+
<tbody>
36+
<tr>
37+
<td>Global level</td>
38+
<td><code class="inline">--help</code></td>
39+
<td>informs about available commands</td>
40+
</tr>
41+
<tr>
42+
<td>Command level</td>
43+
<td><code class="inline">send --help</code></td>
44+
<td>informs about options available for the "send" command</td>
45+
</tr>
46+
<tr>
47+
<td>Option level</td>
48+
<td><code class="inline">send --email:withSubject--help</code></td>
49+
<td>displays usage help for the "withSubject" option</td>
50+
</tr>
51+
</tbody>
52+
</table>
53+
</section>
54+
55+
<section>
56+
<h2>General Usage</h2>
57+
<p class="wide">For Java libraries CLI support works just like any other Java static void main invocation:</p>
58+
<pre><code>java -cp all;the;jars.jar org.simplejavamail.cli.SimpleJavaMail --help</code></pre>
59+
<p class="wide">
60+
Simple Java Mail's own main jar should be on the classpath of course, as well as all non-optional dependencies,
61+
the optional cli-module dependency and <em>its</em> dependencies.
62+
</p>
63+
</section>
64+
</div>

Diff for: ‎src/app/components/cli/cli.ts

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
import {Component} from '@angular/core';
2+
3+
@Component({
4+
template: require('./cli.html')
5+
})
6+
7+
export class Cli {
8+
}

Diff for: ‎src/app/components/contact/contact.html

+3-5
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,13 @@ <h2>Get help, request features, post bugs</h2>
99
<p>Simple Java Mail is a robust library, but there's always room for improvement: suggest anything you can think of!</p>
1010

1111
<p>The <a href="https://github.com/bbottema/simple-java-mail/"><strong>Simple Java Mail GitHub repository</strong></a> and the <a
12-
href="https://github.com/bbottema/simple-java-mail/issues"><strong>issue tracker</strong></a> are used to discuss feature requests and issues.
12+
href="https://github.com/bbottema/simple-java-mail/issues"><strong>issue tracker</strong></a> are used to discuss feature requests and issues
13+
(I get a notification email right away).
1314
</p>
1415

1516
<p>You can also refer to the <a href="http://www.javadoc.io/doc/org.simplejavamail/simple-java-mail">API documentation</a>.</p>
1617

17-
<p>If you need more general help, you'll usually get an answer by posting a question on <a
18-
href="http://stackoverflow.com">StackOverflow</a>. And you can always post an issue in the issue tracker, I get an email as soon as something
19-
gets posted.
20-
</p>
18+
<p>If you need more general help, you'll usually get an answer by posting a question on <a href="http://stackoverflow.com">StackOverflow</a>.</p>
2119

2220
<iframe src="https://ghbtns.com/github-btn.html?user=bbottema&amp;repo=simple-java-mail&amp;type=star&amp;count=true&amp;size=large"
2321
frameborder="0" scrolling="0" width="160px" height="30px"></iframe>

Diff for: ‎src/app/components/debugging/debugging.html

+5-1
Original file line numberDiff line numberDiff line change
@@ -136,9 +136,10 @@ <h2>Logging output</h2>
136136
log4j2</a>.
137137
</p>
138138
<div>
139-
Aside from the native JavaMail logging, there are three parts of Simple Java Mail that may produce logging:
139+
Aside from the native JavaMail logging, the following parts of Simple Java Mail may produce additional logging:
140140
<ul class="indent">
141141
<li>"org.simplejavamail"</li>
142+
<li>"org.simplejavamail.internal.clisupport"</li>
142143
<li>"socks5bridge"</li>
143144
<li>"org.simplejavamail.mailer.internal.socks"</li>
144145
</ul>
@@ -155,6 +156,9 @@ <h2>Logging output</h2>
155156
When using maven, Simple Java Mail provides some default XML configuration for log4j2, but you can easily switch to something else. Below are
156157
some examples.
157158
</p>
159+
<p>
160+
You can also checkout the <a href="https://github.com/bbottema/simple-java-mail/blob/develop/src/test/resources/log4j2.xml">log4j2 configuration used in our own tests</a>.
161+
</p>
158162
</div>
159163
</section>
160164

Diff for: ‎src/app/components/dependencies/dependencies.html

+19-10
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,18 @@ <h1>Project dependencies</h1>
77
Simple Java Mail can be used without any external libraries, but a few features require additional dependencies.
88
</p>
99
</section>
10+
11+
<h2>CLI support</h2>
12+
13+
<section>
14+
<p>
15+
To enable CLI support, include the following module:
16+
</p>
17+
<pre><code class="language-xml">&lt;dependency&gt;
18+
&lt;groupId&gt;org.simplejavamail&lt;/groupId&gt;
19+
&lt;artifactId&gt;cli-module&lt;/artifactId&gt;
20+
&lt;/dependency&gt;</code></pre>
21+
</section>
1022

1123
<h2>DKIM support</h2>
1224

@@ -16,9 +28,8 @@ <h2>DKIM support</h2>
1628
include the following library:
1729
</p>
1830
<pre><code class="language-xml">&lt;dependency&gt;
19-
&lt;groupId&gt;net.markenwerk&lt;/groupId&gt;
20-
&lt;artifactId&gt;utils-mail-dkim&lt;/artifactId&gt;
21-
&lt;version&gt;X.X.X&lt;/version&gt;
31+
&lt;groupId&gt;org.simplejavamail&lt;/groupId&gt;
32+
&lt;artifactId&gt;dkim-module&lt;/artifactId&gt;
2233
&lt;/dependency&gt;</code></pre>
2334
</section>
2435

@@ -31,8 +42,7 @@ <h2>Outlook support</h2>
3142
</p>
3243
<pre><code class="language-xml">&lt;dependency&gt;
3344
&lt;groupId&gt;org.simplejavamail&lt;/groupId&gt;
34-
&lt;artifactId&gt;outlook-message-parser&lt;/artifactId&gt;
35-
&lt;version&gt;X.X.X&lt;/version&gt;
45+
&lt;artifactId&gt;outlook-module&lt;/artifactId&gt;
3646
&lt;/dependency&gt;</code></pre>
3747
</section>
3848

@@ -43,11 +53,10 @@ <h2>Spring support</h2>
4353
To enable support for Spring (see <a [routerLink]="['/configuration']" simplePageScroll href="#section-spring-support">Configuration</a>),
4454
make sure the following libraries can be found on the classpath (in most cases will be there anyway):
4555
</p>
46-
<ol class="indent">
47-
<li>spring-core</li>
48-
<li>spring-context</li>
49-
<li>spring-beans</li>
50-
</ol>
56+
<pre><code class="language-xml">&lt;dependency&gt;
57+
&lt;groupId&gt;org.simplejavamail&lt;/groupId&gt;
58+
&lt;artifactId&gt;spring-module&lt;/artifactId&gt;
59+
&lt;/dependency&gt;</code></pre>
5160
</section>
5261

5362
</div>

Diff for: ‎src/app/simple-java-mail-app.html

+1
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ <h2>Simple API, Complex Emails</h2>
2727
<a class="bar-link" [routerLinkActive]="['active']" [routerLink]="['/about']" (click)="scrollToTop()">About</a>
2828
<a class="bar-link" [routerLinkActive]="['active']" [routerLink]="['/rfc']" simplePageScroll href="#navigation">RFC Compliant</a>
2929
<a class="bar-link" [routerLinkActive]="['active']" [routerLink]="['/features']" simplePageScroll href="#navigation">Features</a>
30+
<a class="bar-link" [routerLinkActive]="['active']" [routerLink]="['/cli']" simplePageScroll href="#navigation">CLI</a>
3031
<a class="bar-link" [routerLinkActive]="['active']" [routerLink]="['/configuration']" simplePageScroll href="#navigation">Configuration</a>
3132
<a class="bar-link" [routerLinkActive]="['active']" [routerLink]="['/debugging']" simplePageScroll href="#navigation">Logging & Debugging</a>
3233
<a class="bar-link" [routerLinkActive]="['active']" [routerLink]="['/dependencies']" simplePageScroll href="#navigation">Dependencies</a>

Diff for: ‎src/app/simple-java-mail-routes.ts

+2
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import { Routes } from '@angular/router';
22

33
import {About} from './components/about/about';
44
import {Features} from './components/features/features';
5+
import {Cli} from './components/cli/cli';
56
import {Configuration} from './components/configuration/configuration';
67
import {Debugging} from './components/debugging/debugging';
78
import {RfcCompliant} from './components/rfc/rfc';
@@ -12,6 +13,7 @@ import {Dependencies} from "./components/dependencies/dependencies";
1213
export const rootRouterConfig: Routes = [
1314
{path: 'about', component: About},
1415
{path: 'features', component: Features},
16+
{path: 'cli', component: Cli},
1517
{path: 'configuration', component: Configuration},
1618
{path: 'debugging', component: Debugging},
1719
{path: 'rfc', component: RfcCompliant},

0 commit comments

Comments
 (0)