Javascript Plugin

Custom functionality can be added with Javascript to APIs with this plugin. Small scripts can be very powerful, e.g. you can:

• Transform messages
• Set header fields
• Change the message routing

As an alternative to the Javascript Plugin you can use the Groovy plugin.

See the examples/javascript folder for some samples.

Switch to the GraalVM Engine

The plugin comes with the Rhino Javascript engine. To use the newest Javascript features the engine can be replaced with the GraalVM Javascript engine. Membrane is tested with GraalVM 24.1.2. Other versions may work but are untested.

The GraalVM Javascript engine consists of several JAR files. The easiest way to get all of them is to let Maven download them:

1. Save the following file as pom.xml in an empty folder:
   Copy

   <project xmlns="http://maven.apache.org/POM/4.0.0">
       <modelVersion>4.0.0</modelVersion>
       <groupId>local</groupId>
       <artifactId>graaljs-for-membrane</artifactId>
       <version>1</version>
       <packaging>pom</packaging>
   
       <properties>
           <graalvm.version>24.1.2</graalvm.version>
       </properties>
   
       <dependencies>
           <dependency>
               <groupId>org.graalvm.polyglot</groupId>
               <artifactId>polyglot</artifactId>
               <version>${graalvm.version}</version>
           </dependency>
           <dependency>
               <groupId>org.graalvm.polyglot</groupId>
               <artifactId>js-community</artifactId>
               <version>${graalvm.version}</version>
               <type>pom</type>
           </dependency>
       </dependencies>
   </project>

   <project xmlns="http://maven.apache.org/POM/4.0.0">
       <modelVersion>4.0.0</modelVersion>
       <groupId>local</groupId>
       <artifactId>graaljs-for-membrane</artifactId>
       <version>1</version>
       <packaging>pom</packaging>
   
       <properties>
           <graalvm.version>24.1.2</graalvm.version>
       </properties>
   
       <dependencies>
           <dependency>
               <groupId>org.graalvm.polyglot</groupId>
               <artifactId>polyglot</artifactId>
               <version>${graalvm.version}</version>
           </dependency>
           <dependency>
               <groupId>org.graalvm.polyglot</groupId>
               <artifactId>js-community</artifactId>
               <version>${graalvm.version}</version>
               <type>pom</type>
           </dependency>
       </dependencies>
   </project>
   

2. Run Maven in that folder. It copies the JAR files into the graaljs subfolder:
   Copy

   mvn dependency:copy-dependencies -DoutputDirectory=graaljs -DexcludeTypes=pom

   mvn dependency:copy-dependencies -DoutputDirectory=graaljs -DexcludeTypes=pom
   

3. Copy the JAR files from graaljs into the MEMBRANE_HOME/lib folder.
4. Stop and start Membrane.

Use the js-community artifact as shown above. The org.graalvm.js:js artifact also pulls in truffle-enterprise, which is licensed under Oracle's GraalVM Free Terms and Conditions (GFTC).

At startup Membrane logs Found GraalVM Javascript engine. if the GraalVM engine is used. If the log says Found Rhino Javascript engine. instead, the GraalVM JARs are not on the classpath.

On a JDK without JVMCI enabled, GraalVM runs scripts in interpreter mode and logs a warning about the fallback runtime. Scripts still work, only slower. To turn the warning off, start Membrane with the Java option -Dpolyglot.engine.WarnInterpreterOnly=false, e.g. by setting the JAVA_OPTS environment variable.

Differences to Rhino

• Every script execution runs in its own GraalVM context, which is closed afterwards.
• Objects created by a script, such as {a: 1} or the result of JSON.parse(), can't be stored on the exchange and used later. Store them as strings with JSON.stringify() instead.
• The json variable is a Java map. With Rhino it is a Javascript object.