SDK Installation and Configuration

Installation

Prerequisites

Before installing the TextChart SDK, ensure you have:

  • Java 21 JDK installed and configured

  • Maven 3.6 or higher (for building from source)

  • At least 500MB of free disk space

  • Administrative access to install software and create directories

  • A valid TextChart license

Download and Installation

  1. Obtain the SDK Package

    • Download the TextChart SDK distribution package

    • Extract the archive to your desired installation directory

    • Example: /opt/textchart-sdk or C:\Program Files\TextChart SDK

  2. Verify Installation

    • Navigate to the SDK installation directory

    • Verify that the following directories exist:

      • lib/ - JAR files and dependencies

      • conf/ - Configuration files

      • examples/ - Sample code and documentation

Configuration

Setting ROSOKA_HOME Environment Variable

The TextChart SDK requires the ROSOKA_HOME environment variable to locate configuration files and license keys.

Linux/macOS

Add the following to your .bashrc, .bash_profile, or .zshrc:

export ROSOKA_HOME=/path/to/textchart-sdk

Then reload your shell configuration:

source ~/.bashrc
# or for macOS:
source ~/.zshrc

Windows

Set the environment variable through the System Properties dialog:

  1. Open System Properties (Win+Pause or Settings → System → Advanced system settings)

  2. Click "Environment Variables"

  3. Click "New" under User variables

  4. Variable name: ROSOKA_HOME

  5. Variable value: C:\Program Files\TextChart SDK (or your installation path)

  6. Click OK and restart any open terminals

Alternatively, set it via Command Prompt:

setx ROSOKA_HOME "C:\Program Files\TextChart SDK"

License Configuration

  1. Obtain License Key

    • Contact i2 for your license key file

    • You will receive a file named licensekeys.xml

  2. Install License Key

    • Copy licensekeys.xml to ${ROSOKA_HOME}/conf/

    • Ensure the file has read permissions

  3. Verify License

    • Run the license verification tool:

      java -jar ${ROSOKA_HOME}/lib/LicenseCheck.jar

    • You should see output confirming your license is valid

Configuration Files

The TextChart SDK reads configuration from several XML files in ${ROSOKA_HOME}/conf/.

RosokaProperties.xml

This is the main configuration file controlling SDK behavior. The SDK uses flat, top-level elements:

<?xml version="1.0" encoding="UTF-8"?>
<RosokaProperties>
    <!-- Output configuration -->
    <fileOutputMode>FULL</fileOutputMode>
    <fileOutputType>XML</fileOutputType>

    <!-- Input/output directories -->
    <inputDir>./inputdir/</inputDir>
    <outputDir>./outdir/</outputDir>

    <!-- LxBase (lexicon) directory -->
    <lxbasedir>./LxBase/</lxbasedir>

    <!-- Optional user data directories -->
    <userDataDir>./userData</userDataDir>
</RosokaProperties>

Embedding in Applications

When embedding the TextChart SDK in another application, you can set the ROSOKA_HOME path programmatically:

import com.rosoka.RosokaAPI.Rosoka;

// Set the Rosoka home directory
Rosoka.setRosokaHome("/path/to/rosoka/home");

// Then get an instance
Rosoka rosoka = Rosoka.getRosokaInstance();

The SDK will also check for ROSOKA_HOME in the following order:

  1. Programmatically set via setRosokaHome()

  2. Environment variable ROSOKA_HOME

  3. Environment variable ROSOKA_BASE

  4. Current working directory

  5. Directory from which the SDK is running

Memory Configuration

For applications that process large documents or high volumes, configure JVM memory settings.

Linux/macOS

export JAVA_OPTS="-Xms2G -Xmx4G"
java $JAVA_OPTS -jar your-application.jar

Windows

set JAVA_OPTS=-Xms2G -Xmx4G
java %JAVA_OPTS% -jar your-application.jar

Or in your Java code before initializing Rosoka:

// Note: This is illustrative; JVM memory must be set before JVM starts
System.setProperty("java.awt.headless", "true");

Performance Tuning

RosokaProperties does not expose thread pool or document cache settings in the current SDK codebase. For performance tuning, adjust JVM options and deployment settings (heap size, CPU allocation, and I/O throughput) and test with representative workloads.

Troubleshooting Installation

License Errors

Problem: "License not found" or license validation fails

Solution:

  1. Verify licensekeys.xml is in ${ROSOKA_HOME}/conf/

  2. Check file permissions (should be readable)

  3. Verify the license hasn't expired

  4. Run: java -jar lib/LicenseCheck.jar to see detailed error

Configuration Not Found

Problem: "RosokaProperties.xml not found"

Solution:

  1. Ensure ROSOKA_HOME environment variable is set correctly

  2. Verify ${ROSOKA_HOME}/conf/ directory exists

  3. Check that configuration files are readable

  4. On Linux/macOS: echo $ROSOKA_HOME to verify the path

  5. On Windows: echo %ROSOKA_HOME% to verify the path

Memory Issues

Problem: "OutOfMemoryError" when processing large documents

Solution:

  1. Increase JVM heap size (see Memory Configuration section above)

  2. Process documents in smaller batches

  3. Enable document streaming for very large files

  4. Check available system memory

Java Version Issues

Problem: "Unsupported class version" or version mismatch errors

Solution:

  1. Verify Java version: java -version

  2. Must be Java 21

  3. Update Java if necessary

  4. Verify JAVA_HOME environment variable points to correct installation

Next Steps

After successful installation and configuration:

  1. Review SDK Usage Guide for development examples

  2. Examine sample code in ${ROSOKA_HOME}/examples/

  3. Read Entity Types Reference

  4. Explore Properties Reference