PreEmptive Protection - DashO v8.1 User Guide

Shelf Life

PreEmptive Protection - DashO can inject Shelf Life into applications. Shelf Life is an application inventory management function that allows you to add expiration and notification logic to your application. This logic enforces an expiration policy by exiting the application and/or sending an analytics message. For example, a beta application can be made to expire on a particular date. You can schedule an application’s expiration for a specific date or a number of days from a starting date and optionally specify a warning period prior to expiration. The expiration information may be placed within your application or can be read from an encrypted external token file. The latter allows you to extend the expiration of the application by issuing a new token file rather than rebuilding your application. Shelf Life checks can be added to one or more locations in your application.

Activation Key

To start using Shelf Life you must obtain a Shelf Life Activation Key from PreEmptive Solutions. This key is used to generate the tokens that contain the expiration information. PreEmptive will issue you a data file containing the key that generates the tokens and identifies your application. This key is read by DashO either when the code is instrumented, or or when tokens are generated if managed externally from the compiled binary. The location of the key file can be specified in the user interface or in the project configuration file.

Shelf Life Tokens

A Shelf Life Token is an encrypted set of data containing application and expiration information. It can be inserted into your application or stored outside of the application. You can use the DashO user interface, the tokengenerator command-line utility, or an Ant task to create an externally stored token.

The expiration and warning information for the token is entered via the user interface or via Shelf Life annotations. The annotations can either be added to your source or added with DashO’s virtual annotations. Expiration and warning dates can be specified in two different ways:

Absolute Dates – A fixed date for the expiration date or the beginning of the warning period can be specified.

Relative Dates – The expiration period is the number of days from a start date. The warning period is the number of days prior to the expiration date.

You can combine absolute and relative dates - e.g. expire on 1/1/2021 and warn 30 days before expiration. Expiration information is required to create the token, but warning information is optional.

Shelf Life Check

The ShelfLifeCheck annotation is used to define the location in your application where a Shelf Life check will take place. The @ShelfLifeCheck annotation can be added to your sources, or a ShelfLifeCheck can be added from the Injection – Shelf Life Check screen. If you added the annotation to your source you will need to compile with dasho-annotations.jar which is located in the lib folder where you installed DashO. By default, DashO removes references to these annotations; therefore, the jar is not required at application runtime and does not need to be distributed with your application.

If the expiration information is set on the Injection – Shelf Life Check screen, at the minimum a key file and expiration date, only a single annotation is required to add the Shelf Life check:

@ShelfLifeCheck
public static void main(final String[] args){
    if(args.length == 0){
        System.out.println("Hello no name");
    } else {
        System.out.println("Hello " + args[0]);
    }
}

This adds a Shelf Life check to the application at the start of main(). You can also specify all the information as annotation attributes:

@ShelfLifeCheck(expirationDate = "01/01/2021", warningPeriod = "30")
public static void main(final String[] args){
    // ...
}

The values for the attributes, dates, periods, and field/method references, are all strings. This allows you to use DashO’s properties or environment values to parameterize them:

@ShelfLifeCheck(expirationDate = "01/01/${exp_year}", warningPeriod = "${warn_period}")
public static void main(final String[] args){
    // ...
}

Relative Expiration Date

Expiration can be specified as a number of days from a dynamic start date. The start date could be something like the install date or the date on which the application is first run. The start date is provided at run-time by your application:

@ShelfLifeCheck(startDateSource = "@getInstallDate()", expirationPeriod = "90")
public static void main(final String[] args){
    // ...
}

private static Date getInstallDate(){
    return new Date(Preferences.userRoot().node("MyApp").getInt("installDate", 0));
}

You can use static or instance methods or fields as a source for the start date. See Specifying Sources and Actions for details.

Externally Stored Tokens

In the previous example DashO has embedded the Shelf Life token into the application. The token can also be stored and managed externally as a file or resource and read in at run-time:

@ShelfLifeCheck(tokenSource = "@getToken()")
public static void main(final String[] args){
    // ...
}

private static Reader getToken(){
    return new InputStreamReader(HelloWorld.class.getClassLoader().
        getResourceAsStream("expiry.dat"));
}

The source for the token is a field of type or a zero-argument method returning a java.io.Reader that provides the token data (as read from a file, for example). See Specifying Sources and Actions for details.

Shelf Life Action

When ShelfLifeCheck is executed, if the application has expired, the default action is to print a message to System.out and exit with a non-zero return code:

This application expired on January 1, 2016

If the application is in the warning period a message is printed to System.out and execution continues:

This application will expire on December 31, 2016

For a more sophisticated application a custom application action can be specified:

@ShelfLifeCheck(action = "@check()")
public static void main(final String[] args){
// ...
}

private static void check(Token token) {
    if(token.isExpired()){
        JOptionPane.showMessageDialog(null,
            "The application expired on " + token.getExpirationDate(),
            "Expired",
            JOptionPane.ERROR_MESSAGE);
        System.exit(1);
    }
    if(token.isInWarning()){
        JOptionPane.showMessageDialog(null,
            "The application will expire in " +
            token.getDaysTillExpiration() + " days",
            "Expiration Warning",
            JOptionPane.WARNING_MESSAGE);
    }
}

The action is passed the Shelf Life token that is then used to determine the action to be taken.

Shelf Life Analytics Messages

Shelf Life can send Analytics messages so you can track applications that have expired or are about to expire. The ShelfLifeCheck has a sendMessage property:

@ShelfLifeCheck(sendMessage = true)
public static void main(final String[] args){
    // ...
}

If your application already contains an ApplicationStart you do not need to add any additional annotations. If you are going to use PreEmptive Analytics for tracking expiration you must add annotations that will identify your application:

@ShelfLifeCheck(sendMessage = true)
@CompanyId("DF29A894-C1AB-5947-E0A2-0D9779CFFB63")
@ApplicationId("F0000FDA-9500-1B92-9564-A9DA3D8C3CF0")
public static void main(final String[] args){
    // ...
}

The ShelfLifeCheck will then automatically handle the ApplicationStart and ApplicationStop to send your expiration messages. See PreEmptive Analytics Overview for additional information if injecting instrumentation into an Android application.

Note:

You can also add any of the following annotations with the ShelfLifeCheck to identify your application: Company, CompanyId, CompanyName, Application, ApplicationId, ApplicationName, ApplicationType, ApplicationVersion, ApplicationVersionSource, ApplicationInstanceIdSource, and UseSsl.

PreEmptive Protection - DashO Version 8.1.0. Copyright © 2017 PreEmptive Solutions, LLC