Package io.karatelabs.common

Interface Resource

All Known Implementing Classes:
MemoryResource, PathResource, UrlResource
public interface Resource

  • Field Details

  • Method Details

    • isFile

      boolean isFile()
      Returns true if this resource is backed by the file system. PathResource returns true, MemoryResource returns false.

    • isInMemory

      default boolean isInMemory()
      Returns true if this resource is in-memory only (not backed by file system). Inverse of isFile() - useful for error messages and debugging.

    • isLocalFile

      default boolean isLocalFile()
      Returns true if this is a regular file on the local filesystem. This excludes JAR resources and in-memory resources. Use this when you need to know if the resource can be modified on disk.
      Returns:
      true if this is a local file (file:// scheme)

    • isJarResource

      default boolean isJarResource()
      Returns true if this resource is inside a JAR or ZIP file. JAR resources are read-only and cannot be modified.
      Returns:
      true if this is a JAR resource (jar: scheme)

    • isClassPath

      boolean isClassPath()
      Returns true if this resource was loaded from the classpath.

    • exists

      boolean exists()
      Returns true if this resource exists and can be read. For PathResource, checks if the file exists on disk. For UrlResource and MemoryResource, always returns true since content is already loaded.

    • getUri

      URI getUri()

    • getPath

      Path getPath()
      Returns the Path representation of this resource if it's file-based. Returns null for in-memory resources.
      Returns:
      Path object or null

    • getRoot

      Path getRoot()
      Returns the root path used for relative path computation. For PathResource, this is the configured root (or working directory). For MemoryResource, this is where the resource would be materialized (or system temp).
      Returns:
      root Path, never null (falls back to system temp)

    • getClasspathRoot

      default Path getClasspathRoot()
      The directory a classpath: reference falls back to when the classloader misses — declared by boot.classpath(dir) for a project whose resources live under a build layout (src/test/resources). Defaults to getRoot(), so a bare-folder project needs no declaration: classpath:x and /x land on the same file.

    • getRelativePathFrom

      default String getRelativePathFrom(Path root)
      Computes the relative path from a given root to this resource. Only works for file-based resources. Falls back to absolute path if relativization fails (e.g., cross-drive on Windows).
      Parameters:
      root - the root path to compute relative path from
      Returns:
      relative path string with forward slashes, or absolute path if relativization fails, or null for in-memory resources

    • resolve

      Resource resolve(String path)

    • getParent

      default Resource getParent()
      Returns the parent of this resource, or null if no parent exists. For PathResource, preserves root and classpath context. For MemoryResource, returns null.
      Returns:
      parent Resource or null

    • getStream

      InputStream getStream()

    • getRelativePath

      String getRelativePath()

    • getText

      String getText()

    • getLine

      String getLine(int index)

    • getLineOffset

      default int getLineOffset()
      Returns the line offset for embedded code (e.g., JS inside a feature file). The lexer uses this as the starting line number so tokens get absolute line numbers. Default is 0 (no offset).

    • getLastModified

      default long getLastModified()

    • getPackageQualifiedName

      default String getPackageQualifiedName()

    • getExtension

      default String getExtension()

    • getSimpleName

      default String getSimpleName()
      Returns just the file name (last path segment) of this resource. Works for both file-based and URL-based resources.
      Returns:
      the simple file name, or empty string if unavailable

    • getFileNameWithoutExtension

      default String getFileNameWithoutExtension()

    • getPrefixedPath

      default String getPrefixedPath()

    • getRelativePathTo

      default String getRelativePathTo(Resource other)
      Computes the relative path from this resource to another resource. Only works for file-based resources. Falls back to absolute path if relativization fails (e.g., cross-drive on Windows).

      Path separators are normalized to forward slashes (/) for cross-platform consistency.

      Parameters:
      other - the target resource
      Returns:
      relative path string with forward slashes, or absolute path if relativization fails, or null for in-memory resources

    • normalizePath

      static String normalizePath(String path)
      Normalize redundant slashes in a path (e.g., "foo//bar" becomes "foo/bar").

    • removePrefix

      static String removePrefix(String text)

    • getParentPath

      static String getParentPath(String relativePath)

    • urlToPath

      static Path urlToPath(URL url, Path root) throws Exception
      Helper method to convert a URL to a Path, handling JAR URLs specially. Falls back to MemoryResource if JAR file system provider is not available.
      Parameters:
      url - the URL to convert
      root - optional root path for the resource
      Returns:
      Path object, or null if fallback to MemoryResource is needed
      Throws:
      Exception - if streaming fallback is required (caller should catch and create MemoryResource)

    • stripLeadingSlashes

      static String stripLeadingSlashes(String s)
      Strips every leading / from a reference. A leading / anchors THE root (webapp context-path style), so it is removed before the ref is resolved against a root — Path.resolve of an absolute argument would otherwise discard the root entirely.

    • path

      static Resource path(String path)

    • optional

      static Resource optional(String path)
      path(String) for a caller that is probing — looking for an optional file and expecting to be told "no". Returns null instead of throwing ResourceNotFoundException, whose construction (message, stack trace) is real cost on a path where the miss is the normal answer: every run looks for a karate-base.js and a karate-config-<env>.js that most projects do not have.

    • path

      static Resource path(String path, Path root)
      Resolves a path reference against a project root — the one rule, from any door: classpath: is classloader-first then root-fallback, file: is the host machine, a leading / anchors root, and a bare ref is root-relative. A Windows drive-letter absolute (C:\x) passes through — it cannot collide with the /-form. With a null root this collapses to the classloader/CWD behaviour of path(String).
      Parameters:
      path - the reference
      root - THE project root

    • path

      static Resource path(String path, Path root, Path classpathRoot)
      path(String, Path) with a separate classpath:-fallback dir, as declared by boot.classpath(dir) — for a project whose resources sit under a build layout (src/test/resources) while THE root stays the project dir.

    • classpathWithRootFallback

      static Resource classpathWithRootFallback(String path, Path root)
      Resolves a classpath: reference with a project-root fallback: the classloader lookup wins when it hits (the Java-project case, unchanged), but on a miss the stripped path is retried against the given root before failing. In "project mode" (a bare folder run — serve / MCP / a packaged runtime) there is no Java classpath carrying the project's files, so a classpath: ref copied from Java-project docs would otherwise hard-fail on first use; the fallback anchors it to the same root a leading-"/" ref resolves against, so one mental model holds across both modes.
      Parameters:
      path - a classpath:-prefixed reference
      root - the project/working root to fall back to (null = no fallback)
      Returns:
      the resolved Resource
      Throws:
      ResourceNotFoundException - when neither the classloader nor the root has it

    • classpathWithRootFallback

      static Resource classpathWithRootFallback(String path, Path root, Path classpathRoot)
      classpathWithRootFallback(String, Path) where the fallback dir is separate from THE root — the boot.classpath(dir) case. The resolved Resource still carries root, so a nested leading-/ ref inside it anchors the project, not the mapped dir.

    • path

      static Resource path(String path, ClassLoader classLoader)
      Creates a Resource from a path string, with optional ClassLoader for classpath resources.
      Parameters:
      path - the resource path (supports "classpath:" prefix)
      classLoader - optional ClassLoader for classpath resources (null = use default)
      Returns:
      Resource instance

    • scanClasspath

      static List<Resource> scanClasspath(String classpathDir, String extension)
      Scans classpath directories for resources with the given extension. Handles both file system classpath entries and JARs.
      Parameters:
      classpathDir - the classpath directory (without "classpath:" prefix)
      extension - file extension to filter (e.g., "feature")
      Returns:
      list of matching Resources

    • scanClasspath

      static List<Resource> scanClasspath(String classpathDir, String extension, ClassLoader classLoader)
      Scans classpath directories for resources with the given extension. Handles both file system classpath entries and JARs.
      Parameters:
      classpathDir - the classpath directory (without "classpath:" prefix)
      extension - file extension to filter (e.g., "feature")
      classLoader - optional ClassLoader (null = use default)
      Returns:
      list of matching Resources

    • scanClasspath

      static List<Resource> scanClasspath(String classpathDir, String extension, ClassLoader classLoader, Path root)
      Scans classpath directories for resources with the given extension. Handles both file system classpath entries and JARs.
      Parameters:
      classpathDir - the classpath directory (without "classpath:" prefix)
      extension - file extension to filter (e.g., "feature")
      classLoader - optional ClassLoader (null = use default)
      root - optional root Path for relative path computation (null = use working dir)
      Returns:
      list of matching Resources

    • text

      static Resource text(String text)

    • bytes

      static Resource bytes(byte[] bytes)
      Creates an in-memory Resource from raw bytes (e.g. a captured image / binary blob). The bytes are returned verbatim by getStream(); getText() decodes them.
      Parameters:
      bytes - the binary content
      Returns:
      MemoryResource instance

    • text

      static Resource text(String text, Path root)
      Creates an in-memory Resource with a custom root. Useful for planning where the resource would be materialized to disk.
      Parameters:
      text - the text content
      root - the root path (where this would live if saved)
      Returns:
      MemoryResource instance

    • embedded

      static Resource embedded(String text, Resource parent, int lineOffset)
      Creates an in-memory Resource for code embedded within another source file. The lineOffset shifts the lexer's starting line so tokens get absolute line numbers relative to the host file. Use lineOffset=0 when the content starts at the beginning of the parent file (e.g., wrapping karate-config.js in parentheses).

      The parent's getRoot() / getClasspathRoot() are carried over: a reference made from inside the embedded code (a read('/x') during config-eval) must anchor the same project the host file belongs to. Without the carry the embedded resource fell back to the system temp dir and every root-anchored ref inside it resolved outside the project.

      Parameters:
      text - the embedded code text
      parent - the host file Resource (for source path)
      lineOffset - 0-indexed line number where the embedded code starts in the host file

    • from

      static Resource from(Path path)
      Creates a modern NIO Path-based Resource. Recommended for new code - better performance and FileSystem support.
      Parameters:
      path - the path
      Returns:
      PathResource instance

    • from

      static Resource from(Path path, Path root)
      Creates a modern NIO Path-based Resource with custom root.
      Parameters:
      path - the path
      root - the root path for relative path computation
      Returns:
      PathResource instance

    • from

      static Resource from(Path path, Path root, Path classpathRoot)
      Creates a Path-based Resource carrying both THE root and the classpath:-fallback dir declared by boot.classpath(dir), so every reference resolved through this resource (feature reads, config-eval) sees the same two anchors.
      Parameters:
      path - the path
      root - THE project root
      classpathRoot - the classpath:-miss fallback dir (null = root)

    • from

      static Resource from(URL url)
      Creates a Resource from a URL. Supports file://, jar://, http://, and https:// schemes.
      Parameters:
      url - the URL to convert
      Returns:
      Resource instance (PathResource for file/jar, UrlResource for http/https)

    • from

      static Resource from(URL url, Path root)
      Creates a Resource from a URL with custom root. Supports file://, jar://, http://, and https:// schemes.
      Parameters:
      url - the URL to convert
      root - the root path for relative path computation
      Returns:
      Resource instance (PathResource for file/jar, UrlResource for http/https)