Class VirtualFileSystem.Builder

java.lang.Object
org.graalvm.python.embedding.VirtualFileSystem.Builder
Enclosing class:
VirtualFileSystem
public static final class VirtualFileSystem.Builder extends Object
Builder class to create VirtualFileSystem instances.
Since:
24.2.0

  • Method Details

    • resourceDirectory

      public VirtualFileSystem.Builder resourceDirectory(String directory)
      Sets the root directory of the virtual filesystem within Java resources. The default value is "org.graalvm.python.vfs". This Java resources directory will be accessible as unixMountPoint(String) or windowsMountPoint(String) from Python code. The recommended convention is to use GRAALPY-VFS/{groupId}/{artifactId}.

      User scripts, data files, and other resources that should be accessible in Python should be put into this resource directory, e.g., src/main/resources/org.graalvm.python.vfs/src where:

      • assuming the usual layout of a Maven or Gradle project then the src/main/resources/org.graalvm.python.vfs prefix is the default value of the resourceDirectory option
      • and the following src directory is the folder used by convention for Python application files and is configured as the default search path for Python module files.

      When Maven or Gradle GraalPy plugin is used to build the virtual environment, it should be configured to generate the virtual environment into the same directory using the <resourceDirectory> tag in Maven or the resourceDirectory field in Gradle.

      Note regarding Java module system: resources in named modules are subject to the encapsulation rules. This is also the case of the default virtual filesystem location. When a resources directory is not a valid Java package name, such as the recommended "GRAALPY-VFS", the resources are not subject to the encapsulation rules and do not require additional module system configuration.

      The value must be relative resources path, i.e., not starting with `/`, and must use '/' as path separator regardless of the host OS.

      Parameters:
      directory - The directory within Java resources
      Returns:
      the builder
      Since:
      24.2.0

    • caseInsensitive

      public VirtualFileSystem.Builder caseInsensitive(boolean value)
      Sets the file system to be case-insensitive. Defaults to true on Windows and false elsewhere.
      Parameters:
      value - the value to be set
      Returns:
      the builder
      Since:
      24.2.0

    • allowHostIO

      public VirtualFileSystem.Builder allowHostIO(VirtualFileSystem.HostIO hostIO)
      Determines if and how much host IO is allowed outside the VirtualFileSystem.
      Parameters:
      hostIO - the host IO access level
      Returns:
      the builder
      Since:
      24.2.0

    • windowsMountPoint

      public VirtualFileSystem.Builder windowsMountPoint(String windowsMountPoint)
      The mount point for the virtual filesystem on Windows. This mount point shadows any real filesystem, so should be chosen to avoid clashes with the users machine, e.g. if set to "X:\graalpy_vfs", then a resource with path /org.graalvm.python.vfs/xyz/abc is visible as "X:\graalpy_vfs\xyz\abc". This needs to be an absolute path with platform-specific separators without any trailing separator. If that file or directory actually exists, it will not be accessible.
      Parameters:
      windowsMountPoint - the mount point path
      Returns:
      the builder
      Throws:
      IllegalArgumentException - if the provided mount point isn't absolute or ends with a trailing separator
      Since:
      24.2.0

    • unixMountPoint

      public VirtualFileSystem.Builder unixMountPoint(String unixMountPoint)
      The mount point for the virtual filesystem on Unices. This mount point shadows any real filesystem, so should be chosen to avoid clashes with the users machine, e.g. if set to "/graalpy_vfs", then a resource with path /org.graalvm.python.vfs/xyz/abc is visible as "/graalpy_vfs/xyz/abc". This needs to be an absolute path with platform-specific separators without any trailing separator. If that file or directory actually exists, it will not be accessible.
      Parameters:
      unixMountPoint - the mount point path
      Returns:
      the builder
      Throws:
      IllegalArgumentException - if the provided mount point isn't absolute or ends with a trailing separator
      Since:
      24.2.0

    • resourceLoadingClass

      public VirtualFileSystem.Builder resourceLoadingClass(Class<?> c)
      By default, virtual filesystem resources are loaded by delegating to VirtualFileSystem.class.getResource(name). Use resourceLoadingClass to determine where to locate resources in cases when for example VirtualFileSystem is on module path and the jar containing the resources is on class path.
      Parameters:
      c - the class for loading the resources
      Returns:
      the builder
      Since:
      24.2.0

    • extractFilter

      public VirtualFileSystem.Builder extractFilter(Predicate<Path> filter)
      This filter applied to files in the virtual filesystem treats them as symlinks to real files in the host filesystem. This is useful, for example, if files in the virtual filesystem need to be accessed outside the Truffle IO virtualization. They will be extracted to the Java temporary directory when first accessed. Matching files belonging to the same wheel are extracted together. The default filter matches any DLLs, dynamic libraries, shared objects, and Python C extension files, because these need to be accessed by the operating system loader. Setting this filter to null denies any extraction. Any other filter is combined with the default filter.
      Parameters:
      filter - the extraction filter, where the provided path is an absolute path from the VirtualFileSystem.
      Returns:
      the builder
      Since:
      24.2.0

    • build

      public VirtualFileSystem build()
      Build a new VirtualFileSystem instance from the configuration provided in the builder.
      Returns:
      new VirtualFileSystem instance
      Since:
      24.2.0