exdlaird.java-ngrok.2.3.1.source-code.overview.html Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of java-ngrok Show documentation
A Java wrapper for ngrok
The newest version!





    
        
    
    
        
    
    
        
    
    
        
    
    
        
    
    
        
    


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


    ngrok Documentation
    java-ngrok on Maven Central
    java-ngrok on GitHub
    Sponsor java-ngrok


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 Started

To get started using java-ngrok, see the docs for the {@link com.github.alexdlaird.ngrok.NgrokClient}.

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.


    Spring
    Dropwizard
    Play (Scala)
    Java HTTP
        Server
    Java TCP Server
        and Client
    


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.