A modern, lightweight command-line tool for working with JasperReports, providing functionality to compile JRXML templates and execute reports with database connectivity.

Note: This project is based on cenote/jasperstarter. It was created because the original repository hasn't been updated since 2016 and there was a need for a command-line compiler/executor that supports modern versions of JasperReports with updated dependencies and Java compatibility.

JasperReports CLI, JasperReports Command Line, JRXML Compiler, JasperReports 7, JasperReports Java 24, JasperStarter Alternative, JasperReports Automation, JasperReports Laravel, JasperReports PHP, Jasper Report Generator, Command Line Reporting Tool, JRXML to PDF, JasperReports MySQL, JasperReports PostgreSQL

• Compile JRXML templates to JASPER format
• Execute reports with database connectivity (MySQL and PostgreSQL)
• Multiple export formats: PDF, Excel (XLS/XLSX), CSV, HTML, XML, and JRPRINT
• JSON output mode for easy integration with other applications (PHP/Laravel, Node.js, Python, etc.)
• Pass parameters to reports at runtime
• Barcode support (Code128, Code39, EAN, UPC, etc.)
• Standalone JAR with all dependencies included

• Java 24 or higher (compiled with Java 24)
• Maven 3.6+ (for building from source)

This tool is built with updated dependencies to support modern Java environments:

• JasperReports: 7.0.3 (all modules)
• Java Compiler Target: Java 24
• MySQL Connector/J: 8.2.0
• PostgreSQL JDBC Driver: 42.7.1
• Apache POI: 5.2.5 (Excel export)
• Log4j2: 2.23.1
• Barcode4J: 2.1

These versions ensure compatibility with the latest Java releases and provide improved performance and security over older implementations.

This modernized version differs from the original cenote/jasperstarter in several key ways:

Why This Version Exists:

• The original JasperStarter hasn't been updated since 2016
• Modern Java versions (17+) require updated dependencies
• Security vulnerabilities in older Log4j and database drivers
• Need for programmatic integration via JSON output
• Better support for modern web frameworks (Laravel, Node.js, Python)

• Laravel/PHP Applications: Generate PDF invoices, reports, and documents from web applications
• Automated Reporting: Schedule report generation via cron jobs or CI/CD pipelines
• Microservices: Integrate JasperReports into containerized environments
• Legacy System Modernization: Replace outdated JasperReports implementations with modern tooling
• Database Reporting: Direct database-to-PDF/Excel conversion without application servers
• Batch Processing: Generate multiple reports programmatically with JSON output parsing

# Clone the repository
git clone https://github.com/ssamoy/jasperstarter.git
cd jasperstarter

# Build with Maven
mvn clean package

# The build creates two JAR files in the target directory:
# - jasperstarter.jar (requires lib/ directory with dependencies)
# - jasperstarter-standalone.jar (single JAR with all dependencies)

Download the latest release from the Releases page and extract the archive.

JasperStarter provides two main commands: compile and execute.

# Windows
jasperstarter.bat <command> <args>

# Unix/Linux/macOS
./jasperstarter.sh <command> <args>

# Using the main JAR (requires lib/ directory)
java -jar target/jasperstarter.jar <command> <args>

# Using the standalone JAR
java -jar target/jasperstarter-standalone.jar <command> <args>

Compile JRXML templates to JASPER format:

jasperstarter compile <jrxml_file> [-json]

Examples:

# Basic compilation
jasperstarter compile report.jrxml

# Compilation with JSON output
jasperstarter compile report.jrxml -json

Execute compiled reports with database connectivity:

jasperstarter execute <jasper_file> -H <host> -u <user> -p <password> -db <database> [OPTIONS]

Required Parameters:

• <jasper_file> - Path to compiled JASPER file
• -H <host> - Database host (e.g., localhost or localhost:5432)
• -u <user> - Database username
• -p <password> - Database password
• -db <database> - Database name
• -output_file <output> - Output file path (without extension)

Optional Parameters:

• --db-driver <driver> - Database driver: mysql (default) or postgresql/postgres
• -format <format> - Export format: pdf (default), csv, xls, xlsx, xml, html, or jrprint
• -P <name>=<value> - Pass parameters to the report (can be used multiple times)
• -json - Output results in JSON format

Examples:

# MySQL (default driver)
jasperstarter execute report.jasper -H localhost -u root -p password -db mydb -output_file invoice

# PostgreSQL
jasperstarter execute report.jasper -H localhost:5432 -u postgres -p password -db mydb --db-driver postgresql -output_file report

# Excel export with parameters
jasperstarter execute report.jasper -H localhost -u root -p password -db mydb -format xlsx -output_file sales -P YEAR=2024 -P MONTH=12

# JSON output mode (for programmatic integration)
jasperstarter execute report.jasper -H localhost -u root -p password -db mydb -output_file report -json

You can pass parameters to your reports using the -P flag:

jasperstarter execute report.jasper -H localhost -u root -p password -db mydb -output_file report \
  -P CUSTOMER_ID=12345 \
  -P START_DATE=2024-01-01 \
  -P END_DATE=2024-12-31 \
  -P LOCALE=en_US \
  -P COMPANY_LOGO=/path/to/logo.png

Parameter Types:

• String parameters: -P NAME=value
• Date parameters: -P DATE=2024-01-01 (use YYYY-MM-DD format)
• Locale parameters: -P LOCALE=en_US (use locale format)
• File/Image parameters: -P IMAGE=/path/to/image.png (absolute file path)

When using the -json flag, all output is formatted as a structured JSON object for easy parsing by external applications.

{
  "status": "success|error",
  "exitCode": 0,
  "command": "compile|execute",
  "messages": ["Array of status/log messages"],
  "data": {
    "inputFile": "path/to/input",
    "outputFile": "path/to/output",
    "database": "database_name",
    "driver": "mysql|postgresql",
    "format": "pdf|csv|xls|etc"
  },
  "error": "Error message if status is error",
  "stackTrace": "Full stack trace (only in error cases)"
}

Successful Compilation:

{
  "status": "success",
  "exitCode": 0,
  "command": "compile",
  "messages": [
    "Compiling: report.jrxml",
    "Output: report.jasper",
    "Compilation successful!"
  ],
  "data": {
    "inputFile": "report.jrxml",
    "outputFile": "report.jasper"
  },
  "error": null,
  "stackTrace": null
}

Failed Execution (Database Error):

{
  "status": "error",
  "exitCode": 8,
  "command": "execute",
  "messages": [
    "Connecting to mysql database...",
    "JDBC URL: jdbc:mysql://localhost:3306/mydb",
    "ERROR: Database connection error: Access denied for user 'wrong'@'localhost'"
  ],
  "data": {},
  "error": "Database connection error: Access denied for user 'wrong'@'localhost'",
  "stackTrace": "java.sql.SQLException: Access denied..."
}

JasperStarter uses specific exit codes to indicate different error conditions:

<?php
class JasperReportService
{
    public function executeReport($jasperPath, $dbConfig, $outputFile, $format = 'pdf', $parameters = [])
    {
        $command = sprintf(
            'jasperstarter execute %s -H %s -u %s -p %s -db %s --db-driver %s -format %s -output_file %s',
            escapeshellarg($jasperPath),
            escapeshellarg($dbConfig['host']),
            escapeshellarg($dbConfig['username']),
            escapeshellarg($dbConfig['password']),
            escapeshellarg($dbConfig['database']),
            escapeshellarg($dbConfig['driver'] ?? 'mysql'),
            escapeshellarg($format),
            escapeshellarg($outputFile)
        );

        // Add parameters
        foreach ($parameters as $name => $value) {
            $command .= sprintf(' -P %s', escapeshellarg("{$name}={$value}"));
        }

        // Add JSON flag
        $command .= ' -json';

        $output = shell_exec($command);
        $result = json_decode($output, true);

        if ($result['exitCode'] !== 0) {
            throw new \Exception($result['error'] ?? 'Report execution failed');
        }

        return $result['data']['outputFile'];
    }
}

// Usage
$service = new JasperReportService();
$outputFile = $service->executeReport(
    'reports/invoice.jasper',
    [
        'host' => 'localhost',
        'username' => 'root',
        'password' => 'password',
        'database' => 'myapp',
        'driver' => 'mysql'
    ],
    'invoice_output',
    'pdf',
    [
        'INVOICE_ID' => 12345,
        'REPORT_DATE' => date('Y-m-d')
    ]
);

const { exec } = require('child_process');
const util = require('util');
const execPromise = util.promisify(exec);

async function executeReport(jasperPath, dbConfig, outputFile, format = 'pdf', parameters = {}) {
    const params = Object.entries(parameters)
        .map(([key, value]) => `-P ${key}=${value}`)
        .join(' ');

    const command = `jasperstarter execute ${jasperPath} ` +
        `-H ${dbConfig.host} -u ${dbConfig.username} -p ${dbConfig.password} ` +
        `-db ${dbConfig.database} --db-driver ${dbConfig.driver || 'mysql'} ` +
        `-format ${format} -output_file ${outputFile} ${params} -json`;

    const { stdout } = await execPromise(command);
    const result = JSON.parse(stdout);

    if (result.exitCode !== 0) {
        throw new Error(result.error || 'Report execution failed');
    }

    return result.data.outputFile;
}

// Usage
executeReport(
    'reports/invoice.jasper',
    {
        host: 'localhost',
        username: 'root',
        password: 'password',
        database: 'myapp',
        driver: 'mysql'
    },
    'invoice_output',
    'pdf',
    {
        INVOICE_ID: 12345,
        REPORT_DATE: new Date().toISOString().split('T')[0]
    }
).then(output => console.log('Report generated:', output))
  .catch(error => console.error('Error:', error));

import subprocess
import json

def execute_report(jasper_path, db_config, output_file, format='pdf', parameters=None):
    parameters = parameters or {}

    command = [
        'jasperstarter', 'execute', jasper_path,
        '-H', db_config['host'],
        '-u', db_config['username'],
        '-p', db_config['password'],
        '-db', db_config['database'],
        '--db-driver', db_config.get('driver', 'mysql'),
        '-format', format,
        '-output_file', output_file
    ]

    # Add parameters
    for key, value in parameters.items():
        command.extend(['-P', f'{key}={value}'])

    # Add JSON flag
    command.append('-json')

    result = subprocess.run(command, capture_output=True, text=True)
    output = json.loads(result.stdout)

    if output['exitCode'] != 0:
        raise Exception(output.get('error', 'Report execution failed'))

    return output['data']['outputFile']

# Usage
output_file = execute_report(
    'reports/invoice.jasper',
    {
        'host': 'localhost',
        'username': 'root',
        'password': 'password',
        'database': 'myapp',
        'driver': 'mysql'
    },
    'invoice_output',
    'pdf',
    {
        'INVOICE_ID': '12345',
        'REPORT_DATE': '2024-01-01'
    }
)
print(f'Report generated: {output_file}')

• JasperReports 7.0.3 - Core reporting engine
• JasperReports Barcode4J 7.0.3 - Barcode component integration
• Barcode4J 2.1 - Barcode generation library
• MySQL Connector/J 8.2.0 - MySQL database connectivity
• PostgreSQL Driver 42.7.1 - PostgreSQL database connectivity
• Apache POI 5.2.5 - Excel export functionality
• Log4j2 2.23.1 - Logging framework

# Clean and build
mvn clean package

# Run tests
mvn test

# Run the application
mvn exec:java -Dexec.args="compile report.jrxml"

jasperstarter/
├── src/
│   └── main/
│       └── java/
│           └── be/stesa/jasperstarter/
│               └── Jasperstarter.java
├── target/
│   ├── jasperstarter.jar (main JAR)
│   ├── jasperstarter-standalone.jar (fat JAR)
│   └── lib/ (dependencies)
├── jasperstarter.bat (Windows launcher)
├── jasperstarter.sh (Unix/Linux launcher)
├── pom.xml
└── README.md

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License allows:

• ✅ Commercial use
• ✅ Modification
• ✅ Distribution
• ✅ Private use

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

For issues, questions, or contributions, please open an issue on the GitHub repository.

• Issues: Report bugs or request features via GitHub Issues
• Discussions: Ask questions in GitHub Discussions
• Documentation: Check the README and CHANGELOG
• JasperReports: Official JasperReports Community

Problem: "Unsupported class file major version"

• Solution: Make sure you're using Java 24 or higher

Problem: "Database connection error"

• Solution: Verify host, credentials, and database name; check if database server is running

Problem: "JRXML compilation error"

• Solution: Validate your JRXML file in JasperSoft Studio or check for syntax errors

• Built with JasperReports, the leading open-source reporting engine
• Based on the original JasperStarter project by Cenote GmbH