Index Copy Section

Rhino: JavaScript in Java

<a title="Rodrigo J De Marco, CC0, via Wikimedia Commons" href="https://commons.wikimedia.org/wiki/File:Rhino_(234581759).jpeg"><img width="384" alt="Rhino (234581759)" src="https://upload.wikimedia.org/wikipedia/commons/thumb/4/4f/Rhino_%28234581759%29.jpeg/512px-Rhino_%28234581759%29.jpeg"></a>

Rhino is an implementation of JavaScript in Java.

Links Copy Chapter

Readme

Release Notes

Compatibility Table

JavaDoc

---

Source Maps Copy Section

Source Map Support

Rhino can remap stack-trace line numbers, parser error positions, and debugger source
handoffs back to the original source when a transpiler or minifier has generated the
script being compiled. The feature is opt-in: attach a SourceMapper to a compile spec
and Rhino uses it automatically.

Quick start Copy Chapter

SourceMapV3 mapper = SourceMapV3.parse(mapJsonString);
Script script = cx.compileScript(
    ScriptCompileSpec.fromSource(transpiledSource)
        .sourceName("bundle.js")
        .sourceMapper(mapper)
        .build());

From that point on, RhinoException.lineNumber() reports the original source line,
parser error messages quote the original source text, and the debugger receives the
primary original source content at compilation time.

Architecture Copy Chapter

The classes in org.mozilla.javascript.sourcemap:

| Class | Visibility | Role |
|---|---|---|
| SourceMapper | public interface | Contract consumed by Rhino's parser and runtime |
| SourceMapV3 | public final class | ECMA-426 plain source map; implements SourceMapper |
| SourceMapJsonParser | package-private | Strict JSON parser; no external dependencies |
| MappingsDecoder | package-private | Base64-VLQ mappings decoder |
| Segment | package-private record | One decoded mappings segment |
| SourceMapException | public class | Unchecked parse/decode error |
| Position | public record | (sourcePath, line, column) in original source |

SourceMapper interface Copy Section

Three methods:

- Position mapPosition(int targetLine, int targetColumn) — maps a 1-indexed
transpiled position to the original source. Returns null when no mapping exists
(gap segment, out-of-range line, column before the first segment on a line).
- String getSourceLineText(String sourcePath, int lineNumber) — returns a line of
original source text by path and 1-indexed line number. Used for parser error messages.
- String getPrimarySourceContent() — returns the full text of the first original
source. Used for the debugger compilation handoff.

SourceMapV3 Copy Section

Parses an ECMA-426 v3 source map and implements SourceMapper. Additional accessors:

- List<String> sources() — resolved source paths (after sourceRoot is prepended)
- List<String> ignoreList() — resolved paths of sources listed in ignoreList
- String file() — the file field, or null
- String getMappedName(int targetLine, int targetColumn) — the original symbol name
from the 5th VLQ field (names array), or null if the segment carries no name

Three factory methods: parse(String), parse(Reader), parseFile(Path).

The XSSI prefix )]}' is stripped automatically per ECMA-426 §3.2.

Not supported: indexed (sectioned) source maps (sections field) — parsing throws
SourceMapException. Transitive (chained) source maps are also out of scope.

JSON parser Copy Section

SourceMapJsonParser is a self-contained recursive-descent parser with no dependency on
any JSON library. It produces:

- objects → LinkedHashMap<String, Object> (insertion order preserved)
- arrays → ArrayList<Object>
- strings → String (full escape handling including \uXXXX)
- integers → Long; floats/exponents → Double
- booleans → Boolean; null → null

All errors throw SourceMapException with the byte offset.

Mappings decoder Copy Section

MappingsDecoder decodes the Base64-VLQ mappings string into
List<List<Segment>> grouped by 0-indexed generated line.

Key behaviours:
- Segments within each line are sorted by generated column after decoding.
ECMA-426 allows out-of-order segments (negative genCol deltas); the sort makes the
binary search in mapPosition correct regardless.
- Zero-field segments (consecutive commas, leading commas) are rejected.
- Negative generated column after applying a delta is rejected.
- VLQ overflow: accumulation uses long; decoded magnitude > Integer.MAX_VALUE
throws. This enforces the ECMA-426 requirement to reject fields exceeding 32 bits.
VLQs with many continuation-bit digits but a small final value (e.g. the
validMappingLargeVLQ spec case) are accepted correctly.

Segment field counts: 1 (gap, no source info), 4 (source mapped), or 5 (source + name).
Other counts throw.

Spec compliance Copy Chapter

The implementation is validated against the
tc39/source-map-tests suite
(submoduled at tests/source-map-tests). 93 of 99 cases pass. The 6 excluded cases
are:

| Case | Reason |
|---|---|
| basicMappingWithIndexMap | Indexed map (sections) — not supported |
| indexMapEmptySections | Indexed map |
| indexMapWithMissingFile | Indexed map |
| indexMapWithTwoConcatenatedSources | Indexed map |
| transitiveMapping | checkMappingTransitive action — chained maps not supported |
| transitiveMappingWithThreeSteps | checkMappingTransitive action |

The excludelist lives at tests/testsrc/source-map-tests-excludelist.txt. Cases on
the list that start passing will fail the build (keeps the list honest). To regenerate
after fixing bugs:

./gradlew :tests:test --tests SourceMapSpecSuiteTest -DupdateSourceMapTestsExcludelist=true

Rhino integration points Copy Chapter

| Where | What |
|---|---|
| Parser.mapLocation | Remaps error position and fetches original source line text |
| Context debugger handoff | Passes getPrimarySourceContent() to the debugger at compile time |
| CodeGenerator / BodyCodegen | Consume only position.line(); unaffected by the sourcePath addition |

---

SECURITY Copy Section

Security Policy

Supported Versions Copy Chapter

Reporting a Vulnerability Copy Chapter

Please disclose it at our security advisory.

This project is maintained by a team of volunteers on a reasonable-effort basis. As such, vulnerabilities will be disclosed in a best effort base.

---

USAGE Copy Section

Projects Using Rhino JavaScript Engine

Many projects leverage the Rhino library to add JavaScript support to their Java applications. Here is a comprehensive list of notable implementations.

Know of other projects using Rhino? 🚀
We'd love to hear about them! If you know of any other applications, platforms, or projects that use the Rhino JavaScript engine,
please share them in our community discussion: Report Rhino Usage Examples

Enterprise & Cloud Platforms Copy Chapter

- VMware Aria Automation 8.18.1 - Data center automation platform
Source

- ThingWorx 9.7 - Industrial IoT platform for connecting and managing industrial assets
Source

- Apigee - Google Cloud's native API management platform for building, managing, and securing APIs. Uses Trireme (see Development Tools & Platforms section below) for running Node.js scripts inside the JVM with Rhino.
Source

- ServiceNow - Intelligent platform for digital transformation and enterprise workflow automation
Source

- Salesforce B2C Commerce - Enterprise e-commerce platform using Rhino for server-side JavaScript scripting
Source

Healthcare & Integration Copy Chapter

- Mirth Connect 4.5 - Healthcare integration engine supporting HL7, EDI, and other healthcare standards
Source

- Open Integration Engine (OIE) - Open-source healthcare integration engine for HL7 message processing and healthcare data exchange
Source

IBM Enterprise Solutions Copy Chapter

- IBM MobileFirst Platform Foundation 7.1.0 - Integrated platform for extending business applications to mobile devices (until release 7.1.0 on IBM Containers)
Source

- IBM Rational Software Architect 9.7.0 - Model-driven development environment for software architects
Source

- IBM Tivoli Netcool/Impact 7.1.0 - Event management and integration platform with runnable server components
Source

Development Tools & Platforms Copy Chapter

- RingoJS 4.0.0 - JavaScript platform built on the JVM and optimized for server-side applications
Source

- Trireme - Library for running Node.js scripts inside the Java Virtual Machine, enabling Node.js applications to be embedded within existing Java applications. Used by Apigee (see Enterprise & Cloud Platforms section above).
Source

- ClojureScript - Robust functional programming language that compiles to JavaScript
Source

- Adobe Experience Manager (AEM) 6.5 - Comprehensive content management solution for marketing content and digital assets
Source

- MagicDraw 2024 - Visual UML, SysML, BPMN, and UPDM modeling tool with team collaboration support
Source

- IntelliJ IDEA - IDE for Professional Development in Java and Kotlin
Source

- Pentaho Data Integration (Kettle) - ETL (Extract, Transform, Load) tool that uses Rhino for JavaScript steps and transformations in data processing workflows
Source

- Servoy Developer - Application development platform for professional developers
Source

- OpenSCDP - The Open Smart Card Development Platform (OpenSCDP) is a collection of tools for the development, test and deployment of smart card and public key infrastructure applications.
Source

Data & Analytics Copy Chapter

- Apache Druid 31.0.1 - Real-time analytics database designed for fast slice-and-dice analytics on large datasets
Source

Template Engines & XML Processing Copy Chapter

- Apache FreeMarker - Template engine for generating text output (HTML, emails, configuration files) from templates and data
Source

- Apache Xalan - XSLT processor for transforming XML documents using XSLT stylesheets
Source

Business Intelligence & Reporting Copy Chapter

- Eclipse BIRT (Business Intelligence Reporting Tool) 4.18.0 - Platform for creating data visualizations, dashboards and reports for web applications
Source (Download birt-runtime and search for org.mozilla.rhino)*

Office & Productivity Software Copy Chapter

- LibreOffice - Free and open-source office suite, successor to OpenOffice
Source

Testing & Automation Tools Copy Chapter

- Sahi Pro 11.0.1 - Test automation tool for browser, desktop, mobile & SAP applications
Source

- HtmlUnit - "GUI-Less browser for Java programs" that supports JavaScript via the Mozilla Rhino engine
Source

Educational & Mathematical Tools Copy Chapter

- GeoGebra - Interactive mathematics software for learning and teaching geometry, algebra, statistics, and calculus
Source

- BPjs -- Java library creating and working with formal models of system behavior, based on the Behavioral Programming paradigm.

Database Copy Chapter

- Memento Database 3.4.0 - Customizable database application for tracking and organizing data
Source

Security & Smart Card Development Copy Chapter

- OpenSCDP - Open Smart Card Development Platform for smart card application development
Source

Mobile Applications Copy Chapter

- EBTCalc - Reverse Polish Notation (RPN) calculator with JavaScript programming capabilities
Source

Additional Resources Copy Chapter

For a more comprehensive list of projects and libraries using Rhino, visit:
Maven Repository - Rhino Usage Statistics

---