Volume Counter installation guide

With the introduction of version 3.0.0 of the license key library, we also released a volume based counting mechanism based on an event system. iText and its add-ons will send events through this event system. When a volume license key file is loaded, the statistics concerning usage will be sent to iText servers. This means that the machine where you run your application needs an active Internet connection.

This guide will show you how to enable the automated monitoring of volume licenses (a.k.a a Capacity Rental License).

Requirements

  • License Key Library version 3+
    • Core
      • Logging dependency
    • Volume
      • AWS SDK
  • iText 7.1.+
  • Volume License Key

Configuration of your project

To enable the volume monitoring as required by volume licensing, you'll need to set up your project to include the license key libraries and their transitive dependencies. For volume counting, you'll need the following: the license key core library, the license key volume library, and the transitive dependencies. Please make sure that you're always using the latest versions of these dependencies.

You'll need to download two license key dependencies:

  • itext-licensekey: This is the license key core library.
  • itext-licensekey-volume: This is the plugin built on top of the license key core library to manage volume licenses. 
  • Transitive dependencies: AWS SDK and its third-party dependencies and logging dependency.

Java

To use the license key libraries in Java we advise you to use Maven or Gradle. This way you don't have to deal with transitive dependencies.

Alternatively, you can download the binaries manually and add them to your classpath.

Using Maven

To add the volume license key library to your Maven project, you'll need to add our repository to your pom.xml followed by the dependencies:

<repositories>
    <repository>
        <id>itext-releases</id>
        <name>iText Repository-releases</name>
        <url>https://repo.itextsupport.com/releases</url>
    </repository>
</repositories>
<dependencies>
    <dependency>
        <groupId>com.itextpdf</groupId>
        <artifactId>itext7-core</artifactId>
        <version>7.1.4</version>
    </dependency>
    
    <dependency>
        <groupId>com.itextpdf</groupId>
        <artifactId>itext-licensekey</artifactId>
        <version>3.0.4</version>
    </dependency>
    
    <dependency>
        <groupId>com.itextpdf</groupId>
        <artifactId>itext-licensekey-volume</artifactId>
        <version>3.0.4</version>
    </dependency>
</dependencies>

 

If you want to download and manage the binaries yourself

You can download the license key library binaries from our hosted repository here:

The AWS SDK (1.11) can be downloaded from the following link. The distribution also includes the necessary third-party dependencies:

slf4j (1.7.13+) logging dependency. It can be downloaded from here:

.NET

To use the license key libraries in .NET we advise you to use NuGet. This is the recommended way since you don't have to deal with transitive dependencies.

Alternatively, you can also download the binaries manually and add them to your project.

    Using NuGet 

    To add the libraries to your project, please find them through the NuGet Package Manager. Searching for the term "itext.licensekey" will bring up the two dependencies in the search results.

    If you want to download and manage the binaries yourself

    You can download the binaries from our hosted repository here:

    The .dll can be found inside the .nupkg files. You can extract a .nupkg file in the same way as a .zip file.

    Installation instructions for transitive dependencies can be found here:

    AWS SDK (specifically the AWSSDK.Kinesis package and its dependencies):

    Common.Logging:

    Loading the license file

    Loading the license file should be done as early as possible in the flow of your application. When you load a volume license key, the license key library will set up everything for you—there is no need to set up any additional counter or logger.

    To load the license key file, you'll need to call the following lines of code:

    Java

    LicenseKey.loadLicenseFile("path/to/itextkey.xml");

    .NET

    LicenseKey.LoadLicenseFile("path/to/itextkey.xml");

    Troubleshooting

    If a logging dependency is configured (for configuration instructions please refer to the respective logging dependency documentation) to include the iText namespace ("com.itextpdf" for Java and "iText" for .NET) then you can check for the following logging messages:

    The 'itext-licensekey-volume' library is required for your license type, but it is missing or outdated. Please add or update this library. If you keep seeing this warning message, contact our support team: https://itextpdf.com/support.

    • This means the volume library has failed to initialize, please make sure that all transitive dependencies are available if you installed the dependencies via the binaries. Alternatively, use the recommended Maven/Gradle/Nuget method instead.

    iText was unable to record your usage information as required by the Capacity Rental License. Please make sure this machine is able to connect to the iText Volume Server. If you keep seeing this warning message, contact our support team: https://itextpdf.com/support.

    • This means the volume library has failed to send data to our server. Please make sure that host kinesis.us-east-1.amazonaws.com on port 443 is reachable from your environment.

    More information

    If you need further information about the volume counting in iText, such as how events are calculated, examples for custom counting implementations and other details, see the Volume Counter FAQs.

    Contact

    Still have questions? 

    We're happy to answer your questions. Reach out to us and we'll get back to you shortly.

    Contact us
    Stay updated

    Join 11,000+ subscribers and become an iText PDF expert by staying up to date with our new products, updates, tips, technical solutions and happenings.

    Subscribe Now