Using TurboFloat with Java

Java This article will give step-by-step instructions on how to add floating-licensing to your Java app. There's also a full example app that you can download and play with without needing to add licensing to your app.

By the end of this article you'll have working floating-licensing integrated with your application, and thus the ability to sell individual copies of your software.

This article shows you how to add floating-licensing to your Java app using TurboFloat. To add hardware-locked licensing to your Java app see the "Using TurboActivate with Java" article.

Sign up or login and download the native TurboFloat library

Before you can do anything, you need to login to your LimeLM account (or sign up). Then download TurboFloat for Windows, macOS, Linux, or BSD. It contains the native library and source code examples needed to integrate floating-licensing in your Java app:

Adding floating licensing to your app

After you've created a new product, go to the version page of the product you will be adding licensing to. You will need to do 2 things:

Download the TurboActivate.dat file for the product version.
Make a note of the Version GUID.

You'll be including the TurboActivate.dat file in a "TurboFloat" folder we'll talk about later and you'll use the Version GUID in your code as part of integrating TurboFloat within your app.

Example project

Included in TurboFloat Library package is a simple Java example project. There are projects for NetBeans, IntelliJ IDEA, and Eclipse. If you're using another IDE you should be able to import one of those projects.

The folder API/Java/src/com/wyday/turbofloat contains all the classes you'll need to add the floating licenses functionality to your app. Copy all those *.java files and add them to your own app.

JNA (Java Native Access)

The TurboFloat Java classes make use of JNA (Java Native Access). Simply put, JNA is a free library that allows easy access to native libraries (*.dll on Windows, *.dylib on macOS, *.so on Unix) without writing anything but Java code. The best part is we've written native libraries for all major Operating Systems and the accompanying Java code to use it. All you need to do is add the files to your product.

TurboFloat binaries for Windows, macOS, Linux, and FreeBSD

TurboFloat is compiled as a native binary. This means you will need to include the native TurboFloat binaries for every platform you want to support.

The Java TurboFloat package looks for the native platform libraries in the folder "TurboFloat" relative to your .jar file. For instance:

YourApp.jar
TurboFloat/
     TurboActivate.dat
     win-x86/
          TurboFloat.dll
     win-x64/
          TurboFloat.dll
     win-arm64/
          TurboFloat.dll
     mac/
          libTurboFloat.dylib
     linux-i386/
          libTurboFloat.so
     linux-amd64/
          libTurboFloat.so
     linux-arm/
          libTurboFloat.so
     linux-arm64/
          libTurboFloat.so
     freebsd-i386/
          libTurboFloat.so
     freebsd-amd64/
          libTurboFloat.so
     ...

If you're creating platform specific installers then you don't need to include the versions of TurboFloat not applicable to that platform. In other words, if you're releasing your Java app to Windows and to Mac you will likely create a separate installer for each platform.

If you only include the platform specific TurboFloat binaries you will reduce the size of your initial distribution.

Step-by-step walkthrough

We're going to walk you through adding floating licensing to your app by using our Java example application. If you haven't downloaded it already you can get the example app inside the TurboFloat Library package.

Step 1. Start the TurboFloat Server

Before you can continue, you need to start a TurboFloat Server instance. We recommend spinning-up a TurboFloat Server instance on our infrastructure using LicenseChest. Alternatively, your customers can host the TurboFloat Server on their own infrastructure by activating and installing the TurboFloat Server locally.

We recommend using our hosted TurboFloat Server option because it's fast, stable, up-to-date, and incredibly easy to deploy.

Step 2. Request "license lease"

In the example text editor Java application the "frmMain.java" file is the main UI for the app. That is, it's the entry point for the application. And because it's the entry point of the application it's where we'll be requesting the "license lease" from the TurboFloat Server.

First, create the TurboFloat instance as a private member in the class:

public class frmMain extends JFrame {

    // ...

    private TurboFloat tf;
    private LeaseExpired frmLeaseExp = null;

Then, in the constructor for the main class, you'll actually create the new instance of the TurboFloat class. Paste the Version GUID you copied from earlier:

public frmMain()
{
    try
    {
        tf = new TurboFloat("PASTE-VERSION-GUID-HERE");
    }
    catch (Exception e)
    {
        JOptionPane.showMessageDialog(null, "Failed to get a lease from the floating license server: " + e.getMessage());
        System.exit(1);
        return;
    }

Next, we'll actually request the lease from the TurboFloat Server:

try
{
    tf = new TurboFloat("PASTE-VERSION-GUID-HERE");

    // request the lease
    tf.RequestLease();
}

Step 3. Add "implements LeaseChangeEvent" to your main class

The native TurboFloat library handles all the details about renewing leases, retrying, etc. All you have to do is handle the cases where TurboFloat talks to your app and tells it something has changed (license lease failing to be renewed or new license field data). First add the "implements LeaseChangeEvent" to your main class:

public class frmMain extends JFrame implements LeaseChangeEvent {

    // ...

    private TurboFloat tf;

Then, add a "LeaseChange()" function to handle notifications from the TurboFloat library:

public void LeaseChange(int status)
{
    if (status == TurboFloat.TF_CB_FEATURES_CHANGED)
    {
        //TODO: if you're using feature values in your app you might want
        //      to reload them now.
    }
    else if (status == TurboFloat.TF_CB_LEASE_REGAINED)
    {
        // we got the lease back, close the lease expired dialog
        // and resume the application
        if (frmLeaseExp != null)
            frmLeaseExp.dispose();
    }
    else // TF_CB_EXPIRED, TF_CB_EXPIRED_INET, and everything else
    {
        // Immediately disable the app and/or show a modal form that
        // gives the user the option to Save / Save As the data
        // (if applicable) and let the user re-try connecting
        // to the server.

        //Note: Don't just close your app. Your users will be
        //      rightfully ticked-off if you do something like that.

        // Instead, we're showing a modal dialog that lets
        // the user try to get a new lease from the server.
        // Or, if they can't, then save their data.
        frmLeaseExp = new LeaseExpired(this, false, tf);
        frmLeaseExp.setVisible(true);

        frmLeaseExp.addWindowListener(new java.awt.event.WindowAdapter() {
            @Override
            public void windowClosed(java.awt.event.WindowEvent evt) {
                frmLeaseExp_Closed(evt);
            }
        });

        this.setEnabled(false);
    }
}

private void frmLeaseExp_Closed(java.awt.event.WindowEvent evt)
{
    frmLeaseExp = null;
		
    // We've gotten a new lease, so re-enable the app.
    this.setEnabled(true);
}

Now you need to tell the TurboFloat instance that your main class will be handling the lease change callback:

try
{
    tf = new TurboFloat("PASTE-VERSION-GUID-HERE");

    // we're telling TurboFloat that this class
    // will listen for the Lease callback
    // see the LeaseCallback function.
    tf.addLeaseChangeListener(this);

    // request the lease
    tf.RequestLease();
}

Step 4. Finishing touches

Included in the example Java app are 3 forms that you might want to copy to your own application:

LeaseExpired.java: a form to show if the license lease has expired.
frmInternetError.java: a form to show if there's an internet error (that is, a server is specified, but your app couldn't connect to the server).
ServerConfig.java: a form to allow the end-user to enter details about where their TurboFloat Server is located.

This simple dialog gives your customers easy entry of the details needed to connect to their TurboFloat Server instance, whether they host it on our infrastructure using LicenseChest or they host it locally.

You've already seen example usage of the LeaseExpired form in the LeaseChange() function. Here's an example usage of the ServerConfig and frmInternetError forms. Its logic is fairly simple. First it tries to get a lease, and if that fails then it prompts the user for action:

try
{
    tf = new TurboFloat("PASTE-VERSION-GUID-HERE");

    // we're telling TurboFloat that this class will listen for the Lease callback
    // see the LeaseCallback function.
    tf.addLeaseChangeListener(this);

    // request the lease
    tf.RequestLease();
}
catch (ServerException se)
{
    ServerConfig srv = new ServerConfig(this, true, tf);
    srv.setVisible(true);

    if (!srv.OKClicked)
    {
        JOptionPane.showMessageDialog(null, "You must specify the location of the floating license server to run YourApp.");
        System.exit(1);
        return;
    }
}
catch (Exception e)
{
    // Give the user an option to try another server if they
    // couldn't connect to the first one, or if the first one
    // is for a different product.
    if (e instanceof com.wyday.turbofloat.InternetException
        || e instanceof WrongServerProductException
        || e instanceof ServerUUIDMismatchException
        || e instanceof UsernameNotAllowedException)
    {
        frmInternetError srv = new frmInternetError(this, true, tf);
        srv.setVisible(true);

        if (!srv.OKClicked)
        {
            // exit the app on failure
            System.exit(1);
            return;
        }
    }
    else
    {
        JOptionPane.showMessageDialog(null, "Failed to get a lease from the floating license server: " + e.getMessage());
        System.exit(1);
        return;
    }
}

Step 5. Dropping the lease when your app closes

After you've successfully requested a lease from the TurboFloat Server, the TurboFloat library integrated in your app takes care of renewing the leases automatically and silently. You'll only ever get a notification of something going wrong in the LeaseChange callback function that we covered in Step 3.

When your app is closing you should "drop" the lease using the DropLease() method, and cleanup the memory using the Cleanup() method:

private void exitForm(java.awt.event.WindowEvent evt) {
    try
    {
        // Drop the lease
        if (tf.HasLease())
            tf.DropLease();

        // Cleanup memory used by TurboFloat library
        TurboFloat.Cleanup();
    }
    catch (Exception e)
    {
        // we're exiting anyway, just let the lease be zombie.
    }

    System.exit(0);
}

What this does is tell the TurboFloat Server that you're through using the lease in this instance of your app, and another instance of your app on another computer or another session can now use that "free slot".

If you can't drop the lease (because your app can't connect to the internet, or for any other reason), and you choose to exit your app anyway, then the "lease" on the TurboFloat Server will be a "zombie". The lease will expire eventually on the TurboFloat Server, and thus the free slot will open back up.

Step 6: Testing the lease change event

Testing requesting leases, dropping them, and everything else in the TurboFloat Library is intuitive: just call the function and it does the thing you want it to do. Testing the lease change event is, however, slightly less intuitive. Here's how you can test the lease change event:

If your app is open and has a lease, close your app and make sure it drops the license lease from the TurboFloat Server.
Stop the TurboFloat Server instance.
Open the TurboFloat Server config file, and edit <lease .../> element and set it to "30". This will set the lease length to 30 seconds.
Save the changes you made to the configuration file.
Start your TurboFloat Server instance again.
Start your app again, and make sure it successfully gets a license lease from the TurboFloat Server.
Now, stop the TurboFloat Server instance, but leave your app running.
Within the next 30 seconds the lease change event will be called because the TurboFloat Library was not able to renew the license lease automatically.

You should also test the "TF_CB_LEASE_DROPPED_SLEEP" and "TF_CB_LEASE_REGAINED" callback types. These callbacks are raised when your app has a lease and the device your app is running on goes to sleep and then eventually wakes up. To test these scenarios:

Run a TurboFloat Server on a separate computer than the one you're running the test from (or spin up a TurboFloat Server instance on our infrastructure).
Start your app and acquire a lease from that TFS instance.
Put the computer which your app is running on to sleep.
After the computer has gone to sleep, wake it up.
Your app should handle both of those events seamlessly. Namely, prompting the user to reconnect when the computer goes to sleep, and if the lease is regained automatically, hiding that prompt from the user.

LimeLM
Overview Pricing & Sign up Why LimeLM? Tour Log in Help
wyBuild
Overview Pricing & Buy Features What's new Help
Support forum
wyDay blog
wyDay Home
Downloads Buy Contact us Careers