Updating Your Project

This page shows you how to update your project after you have put it into production for selling license keys. If you have not put the project into production yet then this page does not apply to you! In particular, if you want to change any of the properties when generating your project then please repeat this process and generate another project.

Overview

The pom.xml file in the project directory contains an XML element named properties:

<project [...]>
    <properties>
        [...]
    </properties>
</project>

Its contents are a list of XML elements in the form <name>value</name>. Each element defines a property name and value. These properties are used for code generation, e.g. there is a property named subject whose value defines the subject of the license management - see below. Their values have been computed from the property values you have provided to the TrueLicense Maven Archetype when generating your project.

Warning

Changing the property values in the pom.xml file generally breaks the compatibility with existing license keys! Don’t do this except for the following use cases as explained below. If you have not already done so, then please set-up a VCS for your project now!


Limiting License Key Validity

Let’s assume you want to limit the validity of the license keys for your software product to a particular version number range, e.g. the same major version number. Then you should include this version number range, e.g. the major version number 1, in the value of the property named subject:

<subject>Product 1</subject>

Later, when you want to transition to a new version number range, e.g. from major version number 1 to 2, then all you have to do in order to invalidate all previously generated license keys is to update the property value accordingly:

<subject>Product 2</subject>

It does not matter how you format the version number range in the licensing subject because the validation function simply checks the equality of the complete string. So if you like, you could also set the property value to Product 1.x or Product 2.x instead of Product 1 or Product 2, respectively. If an invalid license key is found by TrueLicense, e.g. because a user hasn’t bought another license key for your new release, then a net.truelicense.api.LicenseValidationException gets thrown.


Adding an Edition

Adding the Name

Let’s assume you want to add another edition to your software product so that you can sell another type of license keys for the new edition. The value of the property named editions defines a comma separated list of edition names, ordered from supersets to subsets. Each name must be a valid Java identifier and should be camel-cased with the initial character being lower-cased. The name “ftp” is reserved for an auto-generated free trial period. If you didn’t define a value for this property when generating your project, then the default value is standard:

<editions>standard</editions>

You can simply add the name of the new edition to this list. Mind the sorting order from supersets to subsets.

For example, if you want to add an Enterprise Edition which shall be a superset of the existing Standard Edition (sold at a higher price), then you need to insert the name of the enterprise edition before the name of the standard edition:

<editions>enterprise standard</editions>

On the other hand, if you want add a Lite Edition which shall be a subset of the existing Standard Edition (sold at a lower price), then you need to append the name of the lite edition after the name of the standard edition:

<editions>standard lite</editions>

Adding Passwords

For each edition, TrueLicense needs passwords for (a) accessing the private key for signing license beans and (b) encrypting and decrypting license keys.

If you don’t configure a password for (a), then it defaults to the password used for verying the integrity of the private key store, which in turn defaults to the default password defined when generating your project. You don’t need to change this password at all, but if you want to, then you can do so by adding a property named ${edition}KeyEntryPassword, where you need to replace ${edition} with the name of the new edition. For example, you can add a password for an edition named enterprise like this:

<enterpriseKeyEntryPassword>[...]</enterpriseKeyEntryPassword>

If you don’t configure a password for (b), then it defaults to the default password defined when generating your project. Again, you don’t need to change this password, but if you want to, then you can do so by adding a property named ${edition}PbePassword, where you need to replace ${edition} with the name of the new edition. For example, you can add a password for an edition named enterprise like this:

<enterprisePbePassword>[...]</enterprisePbePassword>

Updating Key Stores

Next, the private and public key stores need to get updated so that they contain an entry for the new edition. This is done automatically when you are building your project for the very first time. However, because the new edition is added as an afterthought, this needs to be done manually. The general pattern for this step is to run the following command:

$ mvn generate-resources \
    -Pgenerate-private-key-store \
    -Pgenerate-public-key-store \
    -Deditions=${edition}
[...]

… where you need to replace ${edition} with the name of the new feature set. For example, you can update the key stores for an edition named enterprise like this:

$ mvn generate-resources \
    -Pgenerate-private-key-store \
    -Pgenerate-public-key-store \
    -Deditions=enterprise
[...]

Purchasing a TrueLicense Certificate

Mind that you need to buy another TrueLicense certificate for each feature set you want to add or otherwise you are required to open source your software product under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE, Version 3. See certifying your project.


Migrating Your Project

Let’s assume you want to update your project and benefit from the latest improvements in TrueLicense. In this case, you need to generate a new project and customize it so that it’s fully compatible with existing license keys, i.e. it must be possible to share the same license keys between the old and the new project.

Generating Your project

First, you need to generate the new project by following the instructions in the page generating your project and defining the value of the properties as explained in the following sections.

Migrating from the TrueLicense Maven Archetype before version 2.4

If the old project was generated using the TrueLicense Maven Archetype before version 2.4, then you need to define the values of the following properties as follows:

password
Enter the value produced by the obfuscated string field PBE_PASSWORD in the class **.keymgr.LicensingSchema$Lazy.
freeTrialPeriod
Enter the value of the field FTP_DAYS in the same class.
ftpKeyStoreFile
Enter ftp.ks.
ftpSecretMarkerClass
Enter the parameter value of the last call to the method .storeInUserNode([...]) in the same class, but without the .class suffix, e.g. sun.security.provider.Sun.
licenseKeyFormat
Search for the expression matching the pattern new *ManagementContext(SUBJECT) in the same class and select the value as follows:
  • For new V1LicenseManagementContext(SUBJECT), enter V1.
  • For new V2XmlLicenseManagementContext(SUBJECT), enter V2/XML.
  • For new V2JsonLicenseManagementContext(SUBJECT), enter V2/JSON (default).
subject
Enter the value of the field SUBJECT in the same class.
package
Enter the part of the package name before the keymgr element in the same class.
preferencesType
Search for the expression matching the pattern storeIn*Node(LicensingSchema.class) and select the value as follows:
  • For storeInSystemNode(LicensingSchema.class), enter system.
  • For storeInUserNode(LicensingSchema.class), enter user.

All other properties may have different values.

Migrating from the TrueLicense Maven Archetype since version 2.4

If the old project was generated using the TrueLicense Maven Archetype version 2.4 or later, then you need to make sure that the values of the following properties are equal:

  • editions
  • freeTrialPeriod
  • ftpKeyStoreFile
  • ftpSecretMarkerClass
  • keyStoreType
  • licenseKeyFormat
  • password
  • pbeAlgorithm
  • preferencesType
  • privateKeyStoreFile
  • publicKeyStoreFile
  • subject

All other properties may have different values.

Copying Key Stores

Please copy the following files from the old project to the new project:

  • ${artifactId}-keygen/src/main/resources/${privateKeyStoreFile}
  • ${artifactId}-keymgr/src/main/resources/${ftpKeyStoreFile}
  • ${artifactId}-keymgr/src/main/resources/${publicKeyStoreFile}

Of course, the path names need to remain the same.

Customizing Properties

The parent POM file pom.xml contains a set of properties with the following name patterns:

  • *Alias
  • *Password
  • *Type

… where * matches any prefix. Please check the documentation comments for each of these properties and customize their values so that they match the configuration of the old project.

If the old project was generated using the TrueLicense Maven Archetype before version 2.4, then its generally necessary to change the value of the properties named *Alias to mykey, which is the default alias name for any private key or trusted certificate entry generated by the Java keytool.

Building Your project

You are now set for building your project again.