exdlaird.java-ngrok.2.3.2.source-code.overview.html Maven / Gradle / Ivy
java-ngrok
is a Java wrapper for ngrok
that manages its own binary, making
ngrok
available via a convenient Java API.
ngrok is a reverse proxy tool that opens secure tunnels from public
URLs to localhost,
perfect for exposing local web servers, building webhook integrations, enabling SSH access, testing chatbots,
demoing from your own machine, and more, and its made even more powerful with native Java integration through
java-ngrok
.
Useful Links
Installation
java-ngrok
is available on Maven
Central.
If we want ngrok
to be available from the command line,
pyngrok can be
installed using pip
to manage that for
us.
Getting Around
- {@link com.github.alexdlaird.ngrok.NgrokClient} - Get started using
java-ngrok
, most common uses cases just require the default client behavior
- {@link com.github.alexdlaird.ngrok.conf.JavaNgrokConfig} - Configure configuration for
java-ngrok
- {@link com.github.alexdlaird.ngrok.process.NgrokProcess} - Advanced usage of the
ngrok
process
Integration Examples
java-ngrok
is useful in any number of integrations, for instance to test locally without having to deploy
or configure. Here are some common usage examples.
ngrok
Version Compatibility
java-ngrok
is compatible with ngrok
v2 and v3, but by default it will install v3. To install
v2 instead, set the version with {@link
com.github.alexdlaird.ngrok.conf.JavaNgrokConfig.Builder#withNgrokVersion(NgrokVersion)}
and {@link com.github.alexdlaird.ngrok.protocol.CreateTunnel.Builder#withNgrokVersion(NgrokVersion)}.
Java 8
Java 8 support is not actively maintained, but on a periodic basis, main
may be rebased in to the
1.4.x
branch, where a compatible build of this project does exist for Java 8. To use it, include the
java8-ngrok
dependency from Maven Central.
The Process API
was introduced in Java 9, so certain convenience methods around managing the ngrok
process are
not available in the Java 8 build. For instance, without the Process API, java8-ngrok
cannot teardown
the external ngrok
process for us. So even though the Java process will terminate gracefully,
ngrok
will not. On a Unix-like system, we can remedy this with:
Runtime.getRuntime().addShutdownHook(new Thread(() -> {
try {
// Java 8 doesn't properly manage its child processes, so ensure it's killed
Runtime.getRuntime().exec("killall -9 ngrok");
} catch (final IOException e) {
LOGGER.error("An error occurred while shutting down ngrok", e);
}
}));
But killall
is not available on all platforms, and even on Unix-like systems this workaround is
limited and has side effects.