Merge branch 'develop'

CHANGELOG.md

@@ -7,6 +7,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ## [Unreleased](https://github.com/alexdlaird/java-ngrok/compare/2.3.4...HEAD)
 
 ### Added
+
 - Support for `ngrok` config version 3.
 - Support for `traffic_policy` tunnel definition, which `ngrok` renamed from `policy`.
 - Support for `traffic_policy.on_http_request` and `traffic_policy.on_http_response`, which `ngrok` added unique keys for in HTTP tunnels.

README.md

@@ -54,18 +54,17 @@ final Tunnel sshTunnel = ngrokClient.connect(sshCreateTunnel);
 
 // Open a named tunnel from the config file
 final CreateTunnel createNamedTunnel = new CreateTunnel.Builder()
-        .withName("my_tunnel_name")
+        .withName("my-config-file-tunnel")
         .build();
 final Tunnel namedTunnel = ngrokClient.connect(createNamedTunnel);
 ```
 
 The [`connect`](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/NgrokClient.html#connect(com.github.alexdlaird.ngrok.protocol.CreateTunnel))
 method can also take
-a [`CreateTunnel`](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/protocol/CreateTunnel.html) (
-which can be built
-through [its Builder](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/protocol/CreateTunnel.Builder.html))
+a [`CreateTunnel`](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/protocol/CreateTunnel.html) (which can be built through [its Builder](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/protocol/CreateTunnel.Builder.html))
 that allows us to pass additional properties that
-are supported by `ngrok`, [as documented here](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/NgrokClient.html#tunnel-configurations).
+are supported by `ngrok` (or [`withName()`](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/protocol/CreateTunnel.Builder.html#withName(java.lang.String))
+to use a tunnel defined in `ngrok`'s config file), [as documented here](https://javadoc.io/doc/com.github.alexdlaird/java-ngrok/latest/com.github.alexdlaird.ngrok/com/github/alexdlaird/ngrok/NgrokClient.html#tunnel-configurations).
 
 ### `ngrok`'s Edge
 To use [`ngrok`'s Edge](https://ngrok.com/docs/network-edge/edges/) with `java-ngrok`, first

src/main/java/com/github/alexdlaird/ngrok/NgrokClient.java

@@ -62,14 +62,15 @@
  *
  * // Open a named tunnel from the config file
  * final CreateTunnel createNamedTunnel = new CreateTunnel.Builder()
- *         .withName("my_tunnel_name")
+ *         .withName("my-config-file-tunnel")
  *         .build();
  * final Tunnel namedTunnel = ngrokClient.connect(createNamedTunnel);
  * </pre>
  *
  * <p>The {@link NgrokClient#connect(CreateTunnel) NgrokClient.connect()} method can also take a {@link CreateTunnel}
  * (which can be built through {@link CreateTunnel.Builder its Builder}), which allows us to pass additional tunnel
- * configurations that are supported by ngrok, <a href="#tunnel-configurations">as documented here</a>.
+ * configurations that are supported by <code>ngrok</code> (or {@link CreateTunnel.Builder#withName(String)} to use a
+ * tunnel defined in <code>ngrok</code>`'s config file), <a href="#tunnel-configurations">as documented here</a>.
  *
  * <p><p><code>java-ngrok</code> is compatible with <code>ngrok</code> v2 and v3, but by default it will install v3. To
  * install v2 instead, set the version with {@link JavaNgrokConfig.Builder#withNgrokVersion(NgrokVersion)} and
@@ -156,9 +157,9 @@
  * </pre>
  * <h3 id="tunnel-configurations">Tunnel Configurations</h3>
  * It is possible to configure the tunnel when it is created, for instance adding authentication, a subdomain, or other
- * additional <a href="https://ngrok.com/docs/agent/config/v2/#tunnel-configurations" target="_blank">tunnel
- * configurations that are supported by ngrok</a>. This is accomplished by using {@link CreateTunnel.Builder} to set
- * what properties will be used when the tunnel is created.
+ * additional <a href="https://ngrok.com/docs/agent/config/v2/#common-tunnel-configuration-properties"
+ * target="_blank">tunnel configurations that are supported by ngrok</a>. This is accomplished by using
+ * {@link CreateTunnel.Builder} to set what properties will be used when the tunnel is created.
  *
  * <p>Here is an example that opens a tunnel with subdomain <code>foo</code>, requires basic authentication for
  * requests, and defines a circuit breaker.
@@ -174,6 +175,20 @@
  *
  * final Tunnel tunnel = ngrokClient.connect(createTunnel);
  * </pre>
+ *
+ * <p>If we already have a tunnel
+ * <a href ="https://ngrok.com/docs/agent/config/v2/#tunnel-configurations" target="_blank">defined in
+ * <code>ngrok</code>'s config file</a>, we can start it by its <code>name</code>.</p>
+ *
+ * <pre>
+ * final NgrokClient ngrokClient = new NgrokClient.Builder().build();
+ *
+ * final CreateTunnel createTunnel = new CreateTunnel.Builder()
+ *         .withName("my-config-file-tunnel")
+ *         .build();
+ *
+ * final Tunnel tunnel = ngrokClient.connect(createTunnel);
+ * </pre>
  * <h2>Integration Examples</h2>
  * <code>java-ngrok</code> is useful in any number of integrations, for instance to test locally without having to
  * deploy or configure. Here are some common usage examples.
@@ -385,8 +400,8 @@ public void kill() {
     }
 
     /**
-     * Set the <code>ngrok</code> auth token in the config file, enabling authenticated features (for instance, more
-     * concurrent tunnels, custom subdomains, etc.).
+     * Set the <code>ngrok</code> auth token in the config file, enabling authenticated features (for instance,
+     * opening multiple concurrent tunnels, custom domains, etc.).
      *
      * @param authToken The auth token.
      */

src/main/java/com/github/alexdlaird/ngrok/conf/JavaNgrokConfig.java

@@ -29,6 +29,7 @@
  * };
  * final JavaNgrokConfig javaNgrokConfig = new JavaNgrokConfig.Builder()
  *         .withAuthToken("<NGROK_AUTHTOKEN>")
+ *         .withApiKey("<NGROK_API_KEY>")
  *         .withRegion(Region.AU)
  *         .withLogEventCallback(logEventCallback)
  *         .withMaxLogs(10);

src/main/java/com/github/alexdlaird/ngrok/process/NgrokProcess.java

@@ -217,8 +217,8 @@ public void stop() {
     }
 
     /**
-     * Set the <code>ngrok</code> auth token in the config file, enabling authenticated features (for instance, more
-     * concurrent tunnels, custom subdomains, etc.).
+     * Set the <code>ngrok</code> auth token in the config file, enabling authenticated features (for instance, opening
+     * multiple concurrent tunnels, custom domains, etc.).
      *
      * <pre>
      * // Setting an auth token allows us to do things like open multiple tunnels at the same time

src/main/java/com/github/alexdlaird/ngrok/protocol/CreateTunnel.java

@@ -439,7 +439,7 @@ public Builder withNgrokVersion(final NgrokVersion ngrokVersion) {
         /**
          * A friendly name for the tunnel, or the name of a <a
          * href="https://ngrok.com/docs/agent/config/v2/#tunnel-configurations"
-         * target="_blank">ngrok tunnel definition</a> to be used.
+         * target="_blank">ngrok tunnel definition</a> defined in <code>ngrok</code>'s config file.
          */
         public Builder withName(final String name) {
             this.name = name;