Installation and Configuration

/**
 * Abstract base class for finding GraalVM installation paths and metadata
 */
public abstract class HomeFinder {
    /** Get singleton instance for current environment */
    public static HomeFinder getInstance();
    
    /** Get GraalVM home directory path */
    public abstract String getHomeFolder();
    
    /** Get GraalVM version information */
    public abstract Version getVersion();
    
    /** Get map of language ID to installation path */
    public abstract Map<String, String> getLanguageHomes();
    
    /** Get map of tool ID to installation path */
    public abstract Map<String, String> getToolHomes();
    
    /** Check if running in GraalVM distribution */
    public boolean isGraalVMDistribution();
    
    /** Get relative path within GraalVM installation */
    public String getRelativePath(String path);
}

import org.graalvm.home.*;

public class InstallationDiscovery {
    public void discoverGraalVM() {
        HomeFinder finder = HomeFinder.getInstance();
        
        // Get installation details
        String graalHome = finder.getHomeFolder();
        Version version = finder.getVersion();
        
        System.out.println("GraalVM Home: " + graalHome);
        System.out.println("Version: " + version.toString());
        
        // Check available languages
        Map<String, String> languages = finder.getLanguageHomes();
        for (Map.Entry<String, String> entry : languages.entrySet()) {
            System.out.println("Language " + entry.getKey() + 
                             " at: " + entry.getValue());
        }
        
        // Check available tools
        Map<String, String> tools = finder.getToolHomes();
        for (Map.Entry<String, String> entry : tools.entrySet()) {
            System.out.println("Tool " + entry.getKey() + 
                             " at: " + entry.getValue());
        }
        
        // Conditional behavior based on distribution
        if (finder.isGraalVMDistribution()) {
            // Use GraalVM-specific features
            String libPath = finder.getRelativePath("lib/graalvm");
        }
    }
}

/**
 * Version information with parsing and comparison support
 */
public final class Version implements Comparable<Version> {
    /** Get current GraalVM version */
    public static Version getCurrent();
    
    /** Create version from version numbers */
    public static Version create(int... versions);
    
    /** Parse version from string */
    public static Version parse(String versionString);
    
    /** Get major version number */
    public int getMajor();
    
    /** Get minor version number */
    public int getMinor();
    
    /** Get patch version number */
    public int getPatch();
    
    /** Get build number if available */
    public int getBuild();
    
    /** Get version qualifier (alpha, beta, rc, etc.) */
    public String getQualifier();
    
    /** Check if this is a snapshot version */
    public boolean isSnapshot();
    
    /** Check if this is a release version */
    public boolean isRelease();
    
    /** Check if this is a development version */
    public boolean isDevelopment();
    
    /** Compare with another version */
    public int compareTo(Version other);
    
    /** Check if version is at least given version */
    public boolean isAtLeast(Version minimum);
    
    /** Check if version is older than given version */
    public boolean isOlderThan(Version maximum);
    
    /** Get string representation */
    public String toString();
    
    /** Get full version string with build info */
    public String getFullVersion();
}

public class VersionHandling {
    public void handleVersions() {
        // Get current version
        Version current = Version.getCurrent();
        System.out.println("Running on: " + current.toString());
        
        // Create and compare versions
        Version required = Version.create(21, 0, 0);
        Version latest = Version.parse("21.3.1-dev");
        
        if (current.isAtLeast(required)) {
            System.out.println("Version requirement satisfied");
        }
        
        if (latest.isSnapshot()) {
            System.out.println("Using development version");
        }
        
        // Version comparison
        if (current.compareTo(latest) < 0) {
            System.out.println("Newer version available: " + latest);
        }
        
        // Access version components
        System.out.println("Major: " + current.getMajor());
        System.out.println("Minor: " + current.getMinor());
        System.out.println("Patch: " + current.getPatch());
        
        if (current.getQualifier() != null) {
            System.out.println("Qualifier: " + current.getQualifier());
        }
    }
}

/**
 * Type-safe key for configuration options
 */
public final class OptionKey<T> {
    /** Get option value from option values */
    public T getValue(OptionValues values);
    
    /** Check if option has been explicitly set */
    public boolean hasBeenSet(OptionValues values);
    
    /** Get default value for this option */
    public T getDefaultValue();
    
    /** Get option type information */
    public OptionType<T> getType();
}

/**
 * Metadata describing a configuration option
 */
public final class OptionDescriptor {
    /** Create new option descriptor builder */
    public static OptionDescriptor.Builder newBuilder(OptionKey<?> key, String name);
    
    /** Get option name */
    public String getName();
    
    /** Get option key */
    public OptionKey<?> getKey();
    
    /** Get help text */
    public String getHelp();
    
    /** Get option category */
    public OptionCategory getCategory();
    
    /** Get option stability level */
    public OptionStability getStability();
    
    /** Check if option is deprecated */
    public boolean isDeprecated();
    
    /** Get deprecation message */
    public String getDeprecationMessage();
    
    /** Get allowed values if constrained */
    public Set<String> getAllowedValues();
}

/**
 * Builder for creating option descriptors
 */
public static final class OptionDescriptor.Builder {
    /** Set help text */
    public OptionDescriptor.Builder help(String help);
    
    /** Set option category */
    public OptionDescriptor.Builder category(OptionCategory category);
    
    /** Set stability level */
    public OptionDescriptor.Builder stability(OptionStability stability);
    
    /** Mark as deprecated with message */
    public OptionDescriptor.Builder deprecated(String message);
    
    /** Set allowed values */
    public OptionDescriptor.Builder allowedValues(String... values);
    
    /** Build option descriptor */
    public OptionDescriptor build();
}

import org.graalvm.options.*;

public class OptionManagement {
    // Define option keys
    public static final OptionKey<Integer> MAX_ITERATIONS = 
        new OptionKey<>(100);
    
    public static final OptionKey<String> OUTPUT_FORMAT = 
        new OptionKey<>("json");
    
    public static final OptionKey<Boolean> ENABLE_PROFILING = 
        new OptionKey<>(false);
    
    public void demonstrateOptions() {
        // Create option descriptors
        OptionDescriptor maxIterDesc = OptionDescriptor
            .newBuilder(MAX_ITERATIONS, "max-iterations")
            .help("Maximum number of optimization iterations")
            .category(OptionCategory.USER)
            .stability(OptionStability.STABLE)
            .build();
        
        OptionDescriptor formatDesc = OptionDescriptor
            .newBuilder(OUTPUT_FORMAT, "output-format")
            .help("Output format for results")
            .category(OptionCategory.USER)
            .allowedValues("json", "xml", "text")
            .build();
        
        // Use with option values (context-dependent)
        OptionValues values = getOptionValues(); // Implementation-specific
        
        int maxIter = MAX_ITERATIONS.getValue(values);
        String format = OUTPUT_FORMAT.getValue(values);
        boolean profiling = ENABLE_PROFILING.getValue(values);
        
        // Check if explicitly set
        if (MAX_ITERATIONS.hasBeenSet(values)) {
            System.out.println("Max iterations explicitly set to: " + maxIter);
        } else {
            System.out.println("Using default max iterations: " + maxIter);
        }
    }
    
    // Placeholder for getting option values
    private OptionValues getOptionValues() {
        return null; // Implementation depends on context
    }
}

/**
 * Read-only access to option values
 */
public interface OptionValues {
    /** Get value for option key */
    <T> T get(OptionKey<T> optionKey);
    
    /** Check if option has been explicitly set */
    boolean hasBeenSet(OptionKey<?> optionKey);
    
    /** Get all option descriptors */
    OptionDescriptors getDescriptors();
}

/**
 * Collection of option descriptors with fast lookup
 */
public interface OptionDescriptors extends Iterable<OptionDescriptor> {
    /** Get descriptor by option name */
    OptionDescriptor get(String optionName);
    
    /** Check if option exists */
    boolean contains(String optionName);
    
    /** Get number of options */
    int size();
    
    /** Get iterator over all descriptors */
    Iterator<OptionDescriptor> iterator();
    
    /** Create empty option descriptors */
    static OptionDescriptors empty();
    
    /** Create from array of descriptors */
    static OptionDescriptors create(OptionDescriptor... descriptors);
    
    /** Create from list of descriptors */
    static OptionDescriptors create(List<OptionDescriptor> descriptors);
}

/**
 * Mutable map of option values
 */
public final class OptionMap {
    /** Create empty option map */
    public static OptionMap create();
    
    /** Put option value */
    public <T> void put(OptionKey<T> key, T value);
    
    /** Get option value */
    public <T> T get(OptionKey<T> key);
    
    /** Check if option is set */
    public boolean hasBeenSet(OptionKey<?> key);
    
    /** Remove option */
    public <T> T remove(OptionKey<T> key);
    
    /** Check if map is empty */
    public boolean isEmpty();
    
    /** Get number of options */
    public int size();
    
    /** Clear all options */
    public void clear();
    
    /** Convert to option values */
    public OptionValues asOptionValues();
}

public class OptionCollections {
    public void manageOptionCollections() {
        // Create option map
        OptionMap options = OptionMap.create();
        options.put(MAX_ITERATIONS, 200);
        options.put(OUTPUT_FORMAT, "xml");
        options.put(ENABLE_PROFILING, true);
        
        // Check values
        if (options.hasBeenSet(MAX_ITERATIONS)) {
            int iterations = options.get(MAX_ITERATIONS);
            System.out.println("Iterations: " + iterations);
        }
        
        // Create descriptors collection
        List<OptionDescriptor> descriptorList = Arrays.asList(
            OptionDescriptor.newBuilder(MAX_ITERATIONS, "max-iterations")
                .help("Maximum iterations")
                .category(OptionCategory.USER)
                .build(),
            OptionDescriptor.newBuilder(OUTPUT_FORMAT, "output-format")
                .help("Output format")
                .category(OptionCategory.USER)
                .build()
        );
        
        OptionDescriptors descriptors = OptionDescriptors.create(descriptorList);
        
        // Iterate over descriptors
        for (OptionDescriptor desc : descriptors) {
            System.out.println("Option: " + desc.getName() + 
                             " - " + desc.getHelp());
        }
        
        // Lookup specific descriptor
        OptionDescriptor formatDesc = descriptors.get("output-format");
        if (formatDesc != null) {
            System.out.println("Found format option: " + formatDesc.getHelp());
        }
    }
}

/**
 * Type specification for option values with validation
 */
public final class OptionType<T> {
    /** Create default type for given class */
    public static <T> OptionType<T> defaultType(Class<T> clazz);
    
    /** Create user-defined type with validation */
    public static <T> OptionType<T> user(Class<T> clazz, Function<String, T> converter);
    
    /** Create user type with validation and constraints */
    public static <T> OptionType<T> user(Class<T> clazz, 
                                        Function<String, T> converter,
                                        Predicate<T> validator);
    
    /** Get the option value type class */
    public Class<T> getType();
    
    /** Convert string to typed value */
    public T convert(String value);
    
    /** Validate typed value */
    public boolean isValid(T value);
    
    /** Get validation error message */
    public String getValidationError(T value);
}

public class OptionTypes {
    public void defineCustomTypes() {
        // Custom integer type with range validation
        OptionType<Integer> positiveInt = OptionType.user(
            Integer.class,
            Integer::parseInt,
            value -> value > 0
        );
        
        // Custom enum type
        OptionType<LogLevel> logLevelType = OptionType.user(
            LogLevel.class,
            LogLevel::valueOf,
            value -> true
        );
        
        // File path type with existence validation
        OptionType<String> existingFile = OptionType.user(
            String.class,
            Function.identity(),
            path -> new File(path).exists()
        );
        
        // Use custom types in option keys
        OptionKey<Integer> threadCount = new OptionKey<>(
            1, // default value
            positiveInt
        );
        
        OptionKey<LogLevel> logLevel = new OptionKey<>(
            LogLevel.INFO,
            logLevelType
        );
    }
    
    enum LogLevel {
        ERROR, WARNING, INFO, DEBUG
    }
}

// Option categorization
public enum OptionCategory {
    /** User-facing options visible in help */
    USER,
    
    /** Expert-level options for advanced users */
    EXPERT,
    
    /** Debug options for development */
    DEBUG
}

// API stability levels
public enum OptionStability {
    /** Stable API, safe for production use */
    STABLE,
    
    /** Experimental API, may change */
    EXPERIMENTAL
}

// Exception types
public class OptionException extends RuntimeException {
    public OptionException(String message);
    public OptionException(String message, Throwable cause);
}

public class OptionValidationException extends OptionException {
    public OptionValidationException(String optionName, String message);
    public String getOptionName();
}