or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-scripting-host.mdindex.mdjsr223-integration.mdrepl-support.mdscript-caching.mdscript-compilation.mdscript-persistence.md
tile.json

tessl/maven-org-jetbrains-kotlin--kotlin-scripting-jvm-host

Kotlin Scripting JVM host for executing and compiling Kotlin scripts in JVM environments with JSR-223 integration and comprehensive caching mechanisms

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.jetbrains.kotlin/kotlin-scripting-jvm-host@2.2.x

To install, run

npx @tessl/cli install tessl/maven-org-jetbrains-kotlin--kotlin-scripting-jvm-host@2.2.0

index.mddocs/

Kotlin Scripting JVM Host

Kotlin Scripting JVM Host provides comprehensive JVM host capabilities for Kotlin's experimental scripting API, enabling execution and compilation of Kotlin scripts in JVM environments. It includes the BasicJvmScriptingHost class for script evaluation, JvmScriptCompiler for script compilation, JSR-223 script engine implementations for Java scripting API integration, and comprehensive caching mechanisms for compiled script artifacts.

The library serves as a bridge between Kotlin's scripting infrastructure and JVM runtime environments, offering both direct API access for programmatic script execution and standardized JSR-223 integration for compatibility with existing Java scripting frameworks. It supports template-based script configuration, custom evaluation contexts, and embeddable deployment scenarios where the full Kotlin compiler distribution is embedded within host applications.

Package Information

  • Package Name: kotlin-scripting-jvm-host
  • Group ID: org.jetbrains.kotlin
  • Package Type: maven
  • Language: Kotlin
  • Installation: Add dependency: org.jetbrains.kotlin:kotlin-scripting-jvm-host:2.2.0

Core Imports

import kotlin.script.experimental.jvmhost.BasicJvmScriptingHost
import kotlin.script.experimental.jvmhost.JvmScriptCompiler
import kotlin.script.experimental.jvmhost.CompiledScriptJarsCache
import kotlin.script.experimental.api.*

Basic Usage

import kotlin.script.experimental.jvmhost.BasicJvmScriptingHost
import kotlin.script.experimental.jvmhost.createJvmScriptDefinitionFromTemplate
import kotlin.script.experimental.api.*

// Create a basic scripting host
val host = BasicJvmScriptingHost()

// Define a simple script template
@KotlinScript(fileExtension = "kts")
class SimpleScript

// Evaluate a script with template
val script = "println(\"Hello from script!\")"
val result = host.evalWithTemplate<SimpleScript>(script.toScriptSource())

when (result) {
    is ResultWithDiagnostics.Success -> {
        println("Script executed successfully")
    }
    is ResultWithDiagnostics.Failure -> {
        result.reports.forEach { println("Error: ${it.message}") }
    }
}

Architecture

Kotlin Scripting JVM Host is built around several key components:

  • Host Layer: BasicJvmScriptingHost provides the main entry point for script execution with template-based configuration
  • Compilation Layer: JvmScriptCompiler handles script compilation using the Kotlin compiler infrastructure
  • Caching Layer: CompiledScriptJarsCache provides persistent caching of compiled scripts to JAR files
  • JSR-223 Integration: Complete JSR-223 (Java Scripting API) compatible script engines for seamless Java integration
  • REPL Support: Legacy REPL API compatibility layer for interactive script evaluation
  • Script Persistence: Utilities for saving compiled scripts as executable JARs or class files

Capabilities

Core Scripting Host

Main scripting host implementation providing script compilation and evaluation with template-based configuration.

open class BasicJvmScriptingHost(
    val baseHostConfiguration: ScriptingHostConfiguration? = null,
    compiler: JvmScriptCompiler = JvmScriptCompiler(baseHostConfiguration.withDefaultsFrom(defaultJvmScriptingHostConfiguration)),
    evaluator: ScriptEvaluator = BasicJvmScriptEvaluator()
) : BasicScriptingHost(compiler, evaluator) {
    
    inline fun <reified T : Any> evalWithTemplate(
        script: SourceCode,
        noinline compilation: ScriptCompilationConfiguration.Builder.() -> Unit = {},
        noinline evaluation: ScriptEvaluationConfiguration.Builder.() -> Unit = {}
    ): ResultWithDiagnostics<EvaluationResult>
}

Core Scripting Host

Script Compilation

JVM script compiler implementation for compiling Kotlin scripts with comprehensive configuration support.

open class JvmScriptCompiler(
    baseHostConfiguration: ScriptingHostConfiguration = defaultJvmScriptingHostConfiguration,
    compilerProxy: ScriptCompilerProxy? = null
) : ScriptCompiler {
    
    val hostConfiguration: ScriptingHostConfiguration
    val compilerProxy: ScriptCompilerProxy
    
    override suspend operator fun invoke(
        script: SourceCode,
        scriptCompilationConfiguration: ScriptCompilationConfiguration
    ): ResultWithDiagnostics<CompiledScript>
}

Script Compilation

Script Caching

Caching mechanisms for compiled scripts to improve performance through persistent storage of compiled artifacts.

open class CompiledScriptJarsCache(
    val scriptToFile: (SourceCode, ScriptCompilationConfiguration) -> File?
) : CompiledJvmScriptsCache {
    
    override fun get(script: SourceCode, scriptCompilationConfiguration: ScriptCompilationConfiguration): CompiledScript?
    override fun store(compiledScript: CompiledScript, script: SourceCode, scriptCompilationConfiguration: ScriptCompilationConfiguration)
}

Script Caching

Script Persistence

Utilities for saving compiled scripts as executable JARs or individual class files for deployment and distribution.

open class BasicJvmScriptJarGenerator(val outputJar: File) : ScriptEvaluator {
    override suspend operator fun invoke(
        compiledScript: CompiledScript,
        scriptEvaluationConfiguration: ScriptEvaluationConfiguration
    ): ResultWithDiagnostics<EvaluationResult>
}

open class BasicJvmScriptClassFilesGenerator(val outputDir: File) : ScriptEvaluator {
    override suspend operator fun invoke(
        compiledScript: CompiledScript,
        scriptEvaluationConfiguration: ScriptEvaluationConfiguration
    ): ResultWithDiagnostics<EvaluationResult>
}

Script Persistence

JSR-223 Integration

Complete JSR-223 (Java Scripting API) compatible implementation for seamless integration with existing Java scripting frameworks.

interface KotlinJsr223InvocableScriptEngine : Invocable {
    val invokeWrapper: InvokeWrapper?
    val backwardInstancesHistory: Sequence<Any>
    val baseClassLoader: ClassLoader
    
    override fun invokeFunction(name: String?, vararg args: Any?): Any?
    override fun invokeMethod(thiz: Any?, name: String?, vararg args: Any?): Any?
    override fun <T : Any> getInterface(clasz: Class<T>?): T?
    override fun <T : Any> getInterface(thiz: Any?, clasz: Class<T>?): T?
}

class KotlinJsr223ScriptEngineImpl(
    factory: ScriptEngineFactory,
    baseCompilationConfiguration: ScriptCompilationConfiguration,
    baseEvaluationConfiguration: ScriptEvaluationConfiguration,
    val getScriptArgs: (context: ScriptContext) -> ScriptArgsWithTypes?
) : KotlinJsr223JvmScriptEngineBase(factory), KotlinJsr223InvocableScriptEngine

JSR-223 Integration

REPL Support

Legacy REPL API compatibility layer for interactive script evaluation and compilation.

class JvmReplCompiler(
    val scriptCompilationConfiguration: ScriptCompilationConfiguration,
    val hostConfiguration: ScriptingHostConfiguration = defaultJvmScriptingHostConfiguration
) : ReplCompilerWithoutCheck {
    
    override fun createState(lock: ReentrantReadWriteLock): IReplStageState<*>
    override fun compile(state: IReplStageState<*>, codeLine: ReplCodeLine): ReplCompileResult
}

class JvmReplEvaluator(
    val baseScriptEvaluationConfiguration: ScriptEvaluationConfiguration,
    val scriptEvaluator: ScriptEvaluator = BasicJvmScriptEvaluator()
) : ReplEvaluator {
    
    override fun createState(lock: ReentrantReadWriteLock): IReplStageState<*>
    override fun eval(
        state: IReplStageState<*>,
        compileResult: ReplCompileResult.CompiledClasses,
        scriptArgs: ScriptArgsWithTypes?,
        invokeWrapper: InvokeWrapper?
    ): ReplEvalResult
}

REPL Support

Template Configuration

Template-based configuration utilities for creating script definitions with type-safe configuration builders.

inline fun <reified T : Any> createJvmCompilationConfigurationFromTemplate(
    baseHostConfiguration: ScriptingHostConfiguration? = null,
    noinline body: ScriptCompilationConfiguration.Builder.() -> Unit = {}
): ScriptCompilationConfiguration

inline fun <reified T : Any> createJvmEvaluationConfigurationFromTemplate(
    baseHostConfiguration: ScriptingHostConfiguration? = null,
    noinline body: ScriptEvaluationConfiguration.Builder.() -> Unit = {}
): ScriptEvaluationConfiguration

inline fun <reified T : Any> createJvmScriptDefinitionFromTemplate(
    baseHostConfiguration: ScriptingHostConfiguration? = null,
    noinline compilation: ScriptCompilationConfiguration.Builder.() -> Unit = {},
    noinline evaluation: ScriptEvaluationConfiguration.Builder.() -> Unit = {}
): ScriptDefinition

Types

Core Result Types

// Imported from kotlin.script.experimental.api
sealed class ResultWithDiagnostics<out T> {
    data class Success<T>(val value: T, val reports: List<ScriptDiagnostic> = emptyList()) : ResultWithDiagnostics<T>()
    data class Failure(val reports: List<ScriptDiagnostic>) : ResultWithDiagnostics<Nothing>()
}

data class EvaluationResult(
    val returnValue: ResultValue,
    val configuration: ScriptEvaluationConfiguration
)

sealed class ResultValue {
    object Unit : ResultValue()
    data class Value(val name: String?, val value: Any?, val type: String?, val scriptClass: KClass<*>?, val scriptInstance: Any?) : ResultValue()
    data class Error(val error: Throwable, val wrappingException: Throwable? = null, val scriptClass: KClass<*>? = null, val scriptInstance: Any? = null) : ResultValue()
    object NotEvaluated : ResultValue()
}

Script Source Types

// Imported from kotlin.script.experimental.api
interface SourceCode {
    val text: String
    val name: String?
    val locationId: String?
}

interface CompiledScript {
    val compilationConfiguration: ScriptCompilationConfiguration
    val sourceLocationId: String?
    val otherScripts: List<CompiledScript>
    val resultField: Pair<String, KotlinType>?
    suspend fun getClass(scriptEvaluationConfiguration: ScriptEvaluationConfiguration? = null): ResultWithDiagnostics<KClass<*>>
}

Configuration Types

// Imported from kotlin.script.experimental.api
class ScriptCompilationConfiguration(
    baseConfiguration: ScriptCompilationConfiguration? = null,
    body: Builder.() -> Unit = {}
) : PropertiesCollection(Builder().apply(body).build())

class ScriptEvaluationConfiguration(
    baseConfiguration: ScriptEvaluationConfiguration? = null,
    body: Builder.() -> Unit = {}
) : PropertiesCollection(Builder().apply(body).build())

class ScriptingHostConfiguration(
    baseConfiguration: ScriptingHostConfiguration? = null,
    body: Builder.() -> Unit = {}
) : PropertiesCollection(Builder().apply(body).build())

Migration from Deprecated APIs

Several APIs in this package have been deprecated and moved to the kotlin.script.experimental.jvm package. The deprecated APIs provide redirection to the new implementations:

Deprecated Classes and Interfaces

// Deprecated in kotlin.script.experimental.jvmhost.obsoleteJvmScriptEvaluation

@Deprecated("Use JvmScriptEvaluationConfigurationKeys from kotlin.script.experimental.jvm", level = DeprecationLevel.WARNING)
interface JvmScriptEvaluationConfigurationKeys

@Deprecated("Use JvmScriptEvaluationConfigurationBuilder from kotlin.script.experimental.jvm", level = DeprecationLevel.WARNING)  
class JvmScriptEvaluationConfigurationBuilder

@Deprecated("Use BasicJvmScriptEvaluator from kotlin.script.experimental.jvm", level = DeprecationLevel.ERROR)
class BasicJvmScriptEvaluator

Deprecated Extension Properties

@Deprecated("Use baseClassLoader from kotlin.script.experimental.jvm", level = DeprecationLevel.ERROR)
val ScriptEvaluationConfigurationKeys.baseClassLoader: ScriptEvaluationConfigurationKeys.Key<ClassLoader?>

@Deprecated("Use jvm from kotlin.script.experimental.jvm", level = DeprecationLevel.ERROR)
val ScriptEvaluationConfigurationKeys.jvm: JvmScriptEvaluationConfigurationBuilder

Migration Examples

// Old (deprecated)
import kotlin.script.experimental.jvmhost.BasicJvmScriptEvaluator
import kotlin.script.experimental.jvmhost.jvm

// New (recommended)
import kotlin.script.experimental.jvm.BasicJvmScriptEvaluator
import kotlin.script.experimental.jvm.jvm

// Migration pattern
val oldConfig = ScriptEvaluationConfiguration {
    // Old way (deprecated)
    jvm {
        baseClassLoader(MyClass::class.java.classLoader)
    }
}

val newConfig = ScriptEvaluationConfiguration {
    // New way (recommended)
    jvm {
        baseClassLoader(MyClass::class.java.classLoader)
    }
}
// Configuration is identical, just import from kotlin.script.experimental.jvm instead

For detailed migration information, see the Kotlin Scripting Migration Guide.