Polyglot Language Embedding

/**
 * Creates and manages a polyglot execution context for running guest languages
 */
public final class Context implements AutoCloseable {
    /** Create context with default settings for specified languages */
    public static Context create(String... permittedLanguages);
    
    /** Create builder for advanced context configuration */
    public static Context.Builder newBuilder(String... permittedLanguages);
    
    /** Evaluate source code in specified language */
    public Value eval(String languageId, CharSequence source);
    
    /** Evaluate a Source object */
    public Value eval(Source source);
    
    /** Get global bindings for a language */
    public Value getBindings(String languageId);
    
    /** Initialize specified language without executing code */
    public void initialize(String languageId);
    
    /** Close context and release all resources */
    public void close();
    
    /** Get current execution context */
    public static Context getCurrent();
    
    /** Enter this context for current thread */
    public void enter();
    
    /** Leave this context for current thread */
    public void leave();
}

/**
 * Builder for configuring Context instances with security and resource settings
 */
public static final class Context.Builder {
    /** Allow access to host classes and objects */
    public Context.Builder allowHostAccess(HostAccess config);
    
    /** Configure cross-language access */
    public Context.Builder allowPolyglotAccess(PolyglotAccess config);
    
    /** Allow native access for languages that support it */
    public Context.Builder allowNativeAccess(boolean enabled);
    
    /** Allow creating threads */
    public Context.Builder allowCreateThread(boolean enabled);
    
    /** Allow host I/O operations */
    public Context.Builder allowIO(boolean enabled);
    
    /** Set environment access policy */
    public Context.Builder allowEnvironmentAccess(EnvironmentAccess config);
    
    /** Configure custom file system */
    public Context.Builder fileSystem(FileSystem fileSystem);
    
    /** Set resource limits */
    public Context.Builder resourceLimits(ResourceLimits limits);
    
    /** Set sandbox policy */
    public Context.Builder sandbox(SandboxPolicy policy);
    
    /** Build the configured context */
    public Context build();
}

// Basic context usage
try (Context context = Context.create("js", "python")) {
    Value result = context.eval("js", "Math.max(42, 100)");
    System.out.println(result.asInt()); // 100
}

// Advanced configuration
Context context = Context.newBuilder("js")
    .allowHostAccess(HostAccess.ALL)
    .allowPolyglotAccess(PolyglotAccess.ALL)
    .sandbox(SandboxPolicy.CONSTRAINED)
    .build();

/**
 * Represents a polyglot value that can be converted between language representations
 */
public final class Value {
    /** Convert to Java type with automatic conversion */
    public <T> T as(Class<T> targetType);
    
    /** Convert to primitive boolean */
    public boolean asBoolean();
    
    /** Convert to primitive int */
    public int asInt();
    
    /** Convert to primitive long */
    public long asLong();
    
    /** Convert to primitive float */
    public float asFloat();
    
    /** Convert to primitive double */
    public double asDouble();
    
    /** Convert to Java String */
    public String asString();
    
    /** Execute if this value is executable */
    public Value execute(Object... arguments);
    
    /** Instantiate if this value is instantiable */
    public Value newInstance(Object... arguments);
    
    /** Get member by key/index */
    public Value getMember(String key);
    
    /** Set member by key */
    public void putMember(String key, Object value);
    
    /** Check if member exists */
    public boolean hasMember(String key);
    
    /** Get all member keys */
    public Set<String> getMemberKeys();
    
    /** Get array element by index */
    public Value getArrayElement(long index);
    
    /** Set array element by index */
    public void setArrayElement(long index, Object value);
    
    /** Get array size */
    public long getArraySize();
    
    // Type checking methods
    public boolean isNull();
    public boolean isBoolean();
    public boolean isNumber();
    public boolean isString();
    public boolean canExecute();
    public boolean canInstantiate();
    public boolean hasMembers();
    public boolean hasArrayElements();
    public boolean isHostObject();
    public boolean isProxyObject();
}

try (Context context = Context.create("js")) {
    // Function execution
    Value jsFunction = context.eval("js", "(x, y) => x + y");
    Value result = jsFunction.execute(5, 10);
    System.out.println(result.asInt()); // 15
    
    // Object member access
    Value jsObject = context.eval("js", "({name: 'Alice', age: 30})");
    System.out.println(jsObject.getMember("name").asString()); // Alice
    
    // Array operations
    Value jsArray = context.eval("js", "[1, 2, 3]");
    System.out.println(jsArray.getArraySize()); // 3
    System.out.println(jsArray.getArrayElement(1).asInt()); // 2
}

/**
 * Shared polyglot execution engine managing languages and instruments
 */
public final class Engine implements AutoCloseable {
    /** Create engine with default settings */
    public static Engine create();
    
    /** Create builder for engine configuration */
    public static Engine.Builder newBuilder();
    
    /** Get all available languages */
    public Map<String, Language> getLanguages();
    
    /** Get all available instruments */
    public Map<String, Instrument> getInstruments();
    
    /** Get engine configuration options */
    public OptionDescriptors getOptions();
    
    /** Get cached sources */
    public Set<Source> getCachedSources();
    
    /** Close engine and release resources */
    public void close();
    
    /** Get engine version */
    public String getVersion();
}

/**
 * Builder for configuring Engine instances
 */
public static final class Engine.Builder {
    /** Set option value */
    public <T> Engine.Builder option(String key, String value);
    
    /** Allow experimental options */
    public Engine.Builder allowExperimentalOptions(boolean enabled);
    
    /** Set error output stream */
    public Engine.Builder err(OutputStream err);
    
    /** Set standard output stream */
    public Engine.Builder out(OutputStream out);
    
    /** Set standard input stream */
    public Engine.Builder in(InputStream in);
    
    /** Build configured engine */
    public Engine build();
}

/**
 * Represents source code with metadata and caching support
 */
public final class Source {
    /** Create source from string */
    public static Source create(String language, CharSequence characters);
    
    /** Create source from file */
    public static Source create(String language, File file) throws IOException;
    
    /** Create source from URL */
    public static Source create(String language, URL url) throws IOException;
    
    /** Create builder for advanced source configuration */
    public static Source.Builder newBuilder(String language, Reader source, String name);
    
    /** Get source language ID */
    public String getLanguage();
    
    /** Get source name for debugging */
    public String getName();
    
    /** Get source characters */
    public CharSequence getCharacters();
    
    /** Get source MIME type */
    public String getMimeType();
    
    /** Get source URI if available */
    public URI getURI();
    
    /** Check if source is interactive */
    public boolean isInteractive();
    
    /** Check if source has bytes */
    public boolean hasBytes();
    
    /** Check if source has characters */
    public boolean hasCharacters();
}

/**
 * Builder for configuring Source instances
 */
public static final class Source.Builder {
    /** Set MIME type */
    public Source.Builder mimeType(String mimeType);
    
    /** Mark as interactive source */
    public Source.Builder interactive(boolean interactive);
    
    /** Set source URI */
    public Source.Builder uri(URI uri);
    
    /** Enable caching */
    public Source.Builder cached(boolean cached);
    
    /** Build configured source */
    public Source build() throws IOException;
}

/**
 * Metadata about an available polyglot language
 */
public final class Language {
    /** Get language identifier */
    public String getId();
    
    /** Get human-readable language name */
    public String getName();
    
    /** Get language implementation name */
    public String getImplementationName();
    
    /** Get language version */
    public String getVersion();
    
    /** Get default MIME type */
    public String getDefaultMimeType();
    
    /** Get all supported MIME types */
    public Set<String> getMimeTypes();
    
    /** Get language configuration options */
    public OptionDescriptors getOptions();
    
    /** Check if language is interactive */
    public boolean isInteractive();
}

/**
 * Metadata about an available development instrument/tool
 */
public final class Instrument {
    /** Get instrument identifier */
    public String getId();
    
    /** Get human-readable instrument name */
    public String getName();
    
    /** Get instrument version */
    public String getVersion();
    
    /** Get instrument configuration options */
    public OptionDescriptors getOptions();
}

/**
 * Exception thrown during polyglot execution with guest language details
 */
public final class PolyglotException extends RuntimeException {
    /** Check if exception originated from guest language */
    public boolean isGuestException();
    
    /** Check if this is a host exception */
    public boolean isHostException();
    
    /** Get guest exception object if available */
    public Value getGuestObject();
    
    /** Get polyglot stack trace with all languages */
    public Iterable<StackFrame> getPolyglotStackTrace();
    
    /** Check if exception indicates syntax error */
    public boolean isSyntaxError();
    
    /** Check if execution was cancelled */
    public boolean isCancelled();
    
    /** Check if exception was caused by exit */
    public boolean isExit();
    
    /** Get exit status if this is an exit exception */
    public int getExitStatus();
    
    /** Check if this indicates resource exhaustion */
    public boolean isResourceExhausted();
    
    /** Check if this is an interrupt */
    public boolean isInterrupted();
}

/**
 * Stack frame from polyglot stack trace
 */
public static final class StackFrame {
    /** Get source location if available */
    public SourceSection getSourceLocation();
    
    /** Get root name (function/method name) */
    public String getRootName();
    
    /** Get language information */
    public Language getLanguage();
    
    /** Check if this is a guest language frame */
    public boolean isGuestFrame();
    
    /** Check if this is a host frame */
    public boolean isHostFrame();
}

// Access configuration enums
public enum SandboxPolicy {
    TRUSTED,        // Full system access
    CONSTRAINED,    // Limited system access
    ISOLATED,       // No system access
    UNTRUSTED       // Strictest isolation
}

// Host access configuration
public final class HostAccess {
    public static final HostAccess NONE;        // No host access
    public static final HostAccess ALL;         // Full host access
    public static final HostAccess EXPLICIT;    // Explicit annotations only
    
    public static HostAccess.Builder newBuilder();
}

// Cross-language access configuration
public final class PolyglotAccess {
    public static final PolyglotAccess NONE;    // No cross-language access
    public static final PolyglotAccess ALL;     // Full cross-language access
    
    public static PolyglotAccess.Builder newBuilder();
}

// Environment access configuration
public final class EnvironmentAccess {
    public static final EnvironmentAccess NONE;     // No environment access
    public static final EnvironmentAccess INHERIT;  // Inherit from host
}

// Resource consumption limits
public final class ResourceLimits {
    public static ResourceLimits.Builder newBuilder();
}