### Index

# 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

[Readme](https://github.com/mozilla/rhino)

[Release Notes](https://github.com/mozilla/rhino/blob/master/RELEASE-NOTES.md)

[Compatibility Table](./compat/engines.html)

[JavaDoc](https://javadoc.io/doc/org.mozilla/rhino)

---

### Source Maps

# 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

```java
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

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

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

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

`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

`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

The implementation is validated against the
[tc39/source-map-tests](https://github.com/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

| 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

# Security Policy

## Supported Versions
Security updates are applied only to the latest release.

## Reporting a Vulnerability
If you have discovered a security vulnerability in this project, please report it privately. **Do not disclose it as a public issue.** This gives us time to work with you to fix the issue before public exposure, reducing the chance that the exploit will be used before a patch is released.

Please disclose it at our [security advisory](https://github.com/mozilla/rhino/security/advisories/new).

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

# 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](https://github.com/mozilla/rhino/discussions/1425)**


## Enterprise & Cloud Platforms

- **VMware Aria Automation 8.18.1** - Data center automation platform
  [Source](https://techdocs.broadcom.com/us/en/vmware-cis/aria/aria-automation/8-18/vco-installing-and-configuring-8-18/key-features-of-the-orchestrator-platform.html)

- **[ThingWorx](https://www.ptc.com/de/products/thingworx) 9.7** - Industrial IoT platform for connecting and managing industrial assets
  [Source](https://support.ptc.com/help/thingworx/platform/r9.7/en/index.html#page/ThingWorx/Help/Composer/Things/ThingServices/RhinoJavaScriptEngine.html)

- **[Apigee](https://cloud.google.com/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](https://cloud.google.com/apigee/docs/api-platform/reference/policies/javascript-policy)

- **[ServiceNow](https://www.servicenow.com/)** - Intelligent platform for digital transformation and enterprise workflow automation
  [Source](https://support.servicenow.com/kb?id=kb_article_view&sysparm_article=KB0721865)

- **[Salesforce B2C Commerce](https://www.salesforce.com/products/commerce-cloud/ecommerce/)** - Enterprise e-commerce platform using Rhino for server-side JavaScript scripting
  [Source](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/demandwarejavascript.html)

## Healthcare & Integration

- **Mirth Connect 4.5** - Healthcare integration engine supporting HL7, EDI, and other healthcare standards
  [Source](https://docs.nextgen.com/bundle/Mirth_User_Guide_4_5_0/page/connect/connect/topics/c_The_mirth_properties_File_connect_ug.html)

- **[Open Integration Engine (OIE)](https://openintegrationengine.org/)** - Open-source healthcare integration engine for HL7 message processing and healthcare data exchange
  [Source](https://openintegrationengine.org/)

## IBM Enterprise Solutions

- **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](https://www.ibm.com/docs/en/mpf/7.1.0?topic=code-rhino-container)

- **IBM Rational Software Architect 9.7.0** - Model-driven development environment for software architects
  [Source](https://www.ibm.com/docs/en/rational-soft-arch/9.7.0?topic=launching-rhino-launch-shortcut)

- **IBM Tivoli Netcool/Impact 7.1.0** - Event management and integration platform with runnable server components
  [Source](https://www.ibm.com/docs/en/tivoli-netcoolimpact/7.1?topic=fundamentals-setting-javascript-version-use)

## Development Tools & Platforms

- **[RingoJS](https://ringojs.org/) 4.0.0** - JavaScript platform built on the JVM and optimized for server-side applications
  [Source](https://ringojs.org/)

- **[Trireme](https://github.com/apigee/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](https://github.com/apigee/trireme)

- **[ClojureScript](https://clojurescript.org/)** - Robust functional programming language that compiles to JavaScript
  [Source](https://lambdaisland.com/guides/clojure-repls/clojurescript-repls)

- **[Adobe Experience Manager (AEM) 6.5](https://business.adobe.com/products/experience-manager/adobe-experience-manager.html)** - Comprehensive content management solution for marketing content and digital assets
  [Source](https://developer.adobe.com/experience-manager/reference-materials/6-5/javadoc/overview-summary.html)

- **[MagicDraw 2024](https://www.3ds.com/products/catia/no-magic/magicdraw)** - Visual UML, SysML, BPMN, and UPDM modeling tool with team collaboration support
  [Source](https://docs.nomagic.com/spaces/MD2024x/pages/136727575/Deprecated+JavaScript+Nashorn)

- **[IntelliJ IDEA](https://www.jetbrains.com/idea/)** - IDE for Professional Development in Java and Kotlin
  [Source](https://www.jetbrains.com/legal/third-party-software/?product=IIU)

- **[Pentaho Data Integration (Kettle)](https://www.hitachivantara.com/en-us/products/pentaho-plus-platform/data-integration-analytics.html)** - ETL (Extract, Transform, Load) tool that uses Rhino for JavaScript steps and transformations in data processing workflows
  [Source](https://forums.pentaho.com/threads/64376-Can-we-upgrade-the-Rhino-Javascript-engine-to-1-7R1/)

- **[Servoy Developer](https://docs.servoy.com/)** - Application development platform for professional developers
  [Source](https://docs.servoy.com/release-notes/release-notes/2024.06#lib-upgrades)

- **[OpenSCDP](https://www.openscdp.org/index.html)** - 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](https://github.com/mozilla/rhino/issues/2258#issuecomment-3763695331)

## Data & Analytics

- **[Apache Druid 31.0.1](https://druid.apache.org/)** - Real-time analytics database designed for fast slice-and-dice analytics on large datasets
  [Source](https://druid.apache.org/docs/latest/development/javascript/)

## Template Engines & XML Processing

- **[Apache FreeMarker](https://freemarker.apache.org/index.html)** - Template engine for generating text output (HTML, emails, configuration files) from templates and data
  [Source](https://github.com/apache/freemarker/blob/2.3-gae/build.gradle.kts)

- **[Apache Xalan](https://xalan.apache.org/index.html)** - XSLT processor for transforming XML documents using XSLT stylesheets
  [Source](https://xalan.apache.org/xalan-j/getstarted.html)

## Business Intelligence & Reporting

- **[Eclipse BIRT (Business Intelligence Reporting Tool) 4.18.0](https://eclipse-birt.github.io/birt-website/)** - Platform for creating data visualizations, dashboards and reports for web applications
  [Source](https://download.eclipse.org/birt/updates/release/latest/) *(Download birt-runtime and search for org.mozilla.rhino*)*

## Office & Productivity Software

- **[LibreOffice](https://www.libreoffice.org/)** - Free and open-source office suite, successor to OpenOffice
  [Source](https://wiki.documentfoundation.org/Documentation/DevGuide/Scripting_Framework)

## Testing & Automation Tools

- **[Sahi Pro 11.0.1](https://www.sahipro.com/)** - Test automation tool for browser, desktop, mobile & SAP applications
  [Source](https://resources.sahipro.com/docs/scripting/calling-java.html)

- **[HtmlUnit](https://www.htmlunit.org/)** - "GUI-Less browser for Java programs" that supports JavaScript via the Mozilla Rhino engine
  [Source](https://www.htmlunit.org/)

## Educational & Mathematical Tools

- **[GeoGebra](https://www.geogebra.org/)** - Interactive mathematics software for learning and teaching geometry, algebra, statistics, and calculus
  [Source](https://github.com/geogebra/geogebra/blob/main/doc/Libraries.md)

- **[BPjs](https://github.com/bThink-BGU/BPjs)** -- Java library creating and working with formal models of system behavior, based on the [Behavioral Programming](https://cacm.acm.org/research/behavioral-programming/) paradigm.

## Database

- **[Memento Database 3.4.0](https://mementodatabase.com/)** - Customizable database application for tracking and organizing data
  [Source](https://wiki.mementodatabase.com/index.php/JavaScript_field)

## Security & Smart Card Development

- **[OpenSCDP](https://www.openscdp.org/)** - Open Smart Card Development Platform for smart card application development
  [Source](https://www.openscdp.org/scsh3/)

## Mobile Applications

- **[EBTCalc](https://play.google.com/store/apps/details?id=com.ericbt.rpncalcpaid)** - Reverse Polish Notation (RPN) calculator with JavaScript programming capabilities
  [Source](https://github.com/EricTerrell/EBTCalc.Android)

## Additional Resources

For a more comprehensive list of projects and libraries using Rhino, visit:  
**[Maven Repository - Rhino Usage Statistics](https://mvnrepository.com/artifact/org.mozilla/rhino/usages)**

---