CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-google-jimfs--jimfs

In-memory file system implementation for Java that provides complete java.nio.file API compatibility

—

Pending
Overview
Eval results
Files

configuration.mddocs/

Configuration

The Configuration class provides immutable configuration objects that define file system behavior, path handling, storage limits, and feature support.

Core Imports

import com.google.common.jimfs.Configuration;
import com.google.common.jimfs.PathType;
import com.google.common.jimfs.Feature;
import com.google.common.jimfs.PathNormalization;
import com.google.common.jimfs.WatchServiceConfiguration;
import com.google.common.jimfs.FileTimeSource;
import com.google.common.jimfs.AttributeProvider;

Predefined Configurations

Unix Configuration

Creates a Unix-like file system configuration.

public static Configuration unix();

Characteristics:

  • Uses / as path separator
  • Root: /, working directory: /work
  • Case-sensitive file lookup
  • Supports basic file attributes only
  • Features: hard links, symbolic links, secure directory streams, file channels

Usage Example:

Configuration config = Configuration.unix();
FileSystem fs = Jimfs.newFileSystem(config);

Mac OS X Configuration

Creates a Mac OS X-like file system configuration.

public static Configuration osX();

Characteristics:

  • Uses / as path separator (Unix-style paths)
  • Root: /, working directory: /work
  • Unicode normalization (NFC display, NFD canonical)
  • Case-insensitive (ASCII) file lookup
  • Supports basic file attributes only
  • Features: hard links, symbolic links, file channels (no secure directory streams)

Usage Example:

Configuration config = Configuration.osX();
FileSystem fs = Jimfs.newFileSystem(config);

Windows Configuration

Creates a Windows-like file system configuration.

public static Configuration windows();

Characteristics:

  • Uses \ as canonical separator, recognizes / when parsing
  • Root: C:\, working directory: C:\work
  • Case-insensitive (ASCII) file lookup
  • Path equality uses canonical form
  • Supports basic file attributes only
  • Features: hard links, symbolic links, file channels

Usage Example:

Configuration config = Configuration.windows();
FileSystem fs = Jimfs.newFileSystem(config);

Current Platform Configuration

Creates a configuration appropriate for the current operating system.

public static Configuration forCurrentPlatform();

Automatically selects Windows, Mac OS X, or Unix configuration based on the os.name system property.

Configuration Builder

Creating a Builder

Create a new configuration builder with a specific path type.

public static Builder builder(PathType pathType);

Parameters:

  • pathType - The path type to use (from PathType.unix() or PathType.windows())

Converting to Builder

Create a builder from an existing configuration.

public Builder toBuilder();

Returns a new mutable builder with the same settings as the current configuration.

Configuration.Builder

The nested Builder class provides methods for customizing file system configuration.

Default Constants

public static final int DEFAULT_BLOCK_SIZE = 8192;      // 8 KB
public static final long DEFAULT_MAX_SIZE = 4L * 1024 * 1024 * 1024;  // 4 GB
public static final long DEFAULT_MAX_CACHE_SIZE = -1;   // Equal to max size

Path Normalization

Configure how path names are normalized for display and canonical forms.

public Builder setNameDisplayNormalization(PathNormalization first, PathNormalization... more);
public Builder setNameCanonicalNormalization(PathNormalization first, PathNormalization... more);
public Builder setPathEqualityUsesCanonicalForm(boolean useCanonicalForm);

Parameters:

  • first, more - Path normalization options (NONE, NFC, NFD, CASE_FOLD_UNICODE, CASE_FOLD_ASCII)
  • useCanonicalForm - Whether Path objects use canonical form for equality (default: false)

Usage Example:

Configuration config = Configuration.unix()
    .toBuilder()
    .setNameCanonicalNormalization(PathNormalization.NFD, PathNormalization.CASE_FOLD_ASCII)
    .setPathEqualityUsesCanonicalForm(true)
    .build();

Storage Configuration

Configure file system storage limits and block allocation.

public Builder setBlockSize(int blockSize);
public Builder setMaxSize(long maxSize);
public Builder setMaxCacheSize(long maxCacheSize);

Parameters:

  • blockSize - Block size in bytes (must be positive, default: 8192)
  • maxSize - Maximum storage size in bytes (must be positive, default: 4GB)
  • maxCacheSize - Maximum cached unused space in bytes (≥0, default: equal to maxSize, 0 disables caching)

Usage Example:

Configuration config = Configuration.unix()
    .toBuilder()
    .setBlockSize(4096)                    // 4KB blocks
    .setMaxSize(512 * 1024 * 1024)         // 512MB limit
    .setMaxCacheSize(64 * 1024 * 1024)     // 64MB cache
    .build();

Attribute Configuration

Configure supported file attribute views and default values.

public Builder setAttributeViews(String first, String... more);
public Builder addAttributeProvider(AttributeProvider provider);
public Builder setDefaultAttributeValue(String attribute, Object value);

Supported Attribute Views:

  • "basic" - BasicFileAttributeView/BasicFileAttributes
  • "owner" - FileOwnerAttributeView
  • "posix" - PosixFileAttributeView/PosixFileAttributes
  • "unix" - Unix-specific attributes
  • "dos" - DosFileAttributeView/DosFileAttributes
  • "acl" - AclFileAttributeView
  • "user" - UserDefinedFileAttributeView

Usage Example:

Configuration config = Configuration.unix()
    .toBuilder()
    .setAttributeViews("basic", "owner", "posix", "unix")
    .setDefaultAttributeValue("posix:permissions", "rwxr-xr-x")
    .setDefaultAttributeValue("owner:owner", "testuser")
    .build();

File System Structure

Configure roots and working directory.

public Builder setRoots(String first, String... more);
public Builder setWorkingDirectory(String workingDirectory);

Parameters:

  • first, more - Root paths (must be valid root paths for the path type)
  • workingDirectory - Working directory path (must be absolute)

Usage Example:

Configuration config = Configuration.builder(PathType.windows())
    .setRoots("C:\\", "D:\\", "E:\\")
    .setWorkingDirectory("C:\\Users\\testuser")
    .build();

Features and Services

Configure optional features and services.

public Builder setSupportedFeatures(Feature... features);
public Builder setWatchServiceConfiguration(WatchServiceConfiguration config);
public Builder setFileTimeSource(FileTimeSource source);

Parameters:

  • features - Supported features (LINKS, SYMBOLIC_LINKS, SECURE_DIRECTORY_STREAM, FILE_CHANNEL)
  • config - Watch service configuration (default: 5-second polling)
  • source - Custom time source for file timestamps

Usage Example:

Configuration config = Configuration.unix()
    .toBuilder()
    .setSupportedFeatures(Feature.LINKS, Feature.SYMBOLIC_LINKS, Feature.FILE_CHANNEL)
    .setWatchServiceConfiguration(WatchServiceConfiguration.polling(1, TimeUnit.SECONDS))
    .build();

Building Configuration

Create the immutable configuration.

public Configuration build();

Returns a new immutable Configuration object with the specified settings.

Thread Safety

  • Configuration objects are immutable and thread-safe
  • Configuration.Builder objects are mutable and not thread-safe
  • Multiple builders can be created from the same configuration safely

Validation

The builder validates configuration parameters:

  • Block sizes must be positive
  • Max sizes must be positive
  • Max cache sizes must be non-negative
  • Roots must be valid root paths for the path type
  • Working directories must be absolute paths
  • Attribute strings must follow "view:attribute" format
  • Path normalizations cannot conflict (e.g., can't set both NFC and NFD)

AttributeProvider

The AttributeProvider abstract class enables custom file attribute views and providers.

Abstract Class Definition

public abstract class AttributeProvider {
    public abstract String name();
    public ImmutableSet<String> inherits();
    public abstract Class<? extends FileAttributeView> viewType();
    public abstract FileAttributeView view(FileLookup lookup, ImmutableMap<String, FileAttributeView> inheritedViews);
    public ImmutableMap<String, ?> defaultValues(Map<String, ?> userDefaults);
    public abstract ImmutableSet<String> fixedAttributes();
    public boolean supports(String attribute);
    public ImmutableSet<String> attributes(File file);
    public abstract Object get(File file, String attribute);
    public abstract void set(File file, String view, String attribute, Object value, boolean create);
    public Class<? extends BasicFileAttributes> attributesType();
    public BasicFileAttributes readAttributes(File file);
}

Key Methods

Core Abstract Methods

Provider Identity:

  • name() - Returns the view name for this provider (e.g., "posix", "dos")
  • viewType() - Returns the FileAttributeView interface class this provider supports

Attribute Handling:

  • fixedAttributes() - Returns attributes always supported by this provider
  • get(File, String) - Gets attribute value from file
  • set(File, String, String, Object, boolean) - Sets attribute value in file
  • view(FileLookup, Map) - Creates FileAttributeView instance for file operations

Optional Override Methods

Inheritance:

  • inherits() - Names of other providers this provider inherits from (default: empty)

Default Values:

  • defaultValues(Map) - Default attribute values for new files (default: empty)

Dynamic Attributes:

  • attributes(File) - Attributes present in specific file (default: fixedAttributes())
  • supports(String) - Whether provider directly supports attribute (default: uses fixedAttributes())

Attributes Object Support:

  • attributesType() - BasicFileAttributes subclass if supported (default: null)
  • readAttributes(File) - Read attributes as object (default: throws UnsupportedOperationException)

Usage Example

Custom Attribute Provider:

public class CustomMetadataProvider extends AttributeProvider {
    @Override
    public String name() {
        return "custom";
    }
    
    @Override
    public Class<? extends FileAttributeView> viewType() {
        return CustomAttributeView.class;
    }
    
    @Override
    public ImmutableSet<String> fixedAttributes() {
        return ImmutableSet.of("author", "description", "tags");
    }
    
    @Override
    public Object get(File file, String attribute) {
        switch (attribute) {
            case "author": return file.getAttribute("custom:author");
            case "description": return file.getAttribute("custom:description");
            case "tags": return file.getAttribute("custom:tags");
            default: return null;
        }
    }
    
    @Override
    public void set(File file, String view, String attribute, Object value, boolean create) {
        checkNotNull(value);
        switch (attribute) {
            case "author":
                file.setAttribute("custom:author", checkType(view, attribute, value, String.class));
                break;
            case "description":
                file.setAttribute("custom:description", checkType(view, attribute, value, String.class));
                break;
            case "tags":
                file.setAttribute("custom:tags", checkType(view, attribute, value, List.class));
                break;
            default:
                throw new IllegalArgumentException("unsupported attribute: " + view + ":" + attribute);
        }
    }
    
    @Override
    public FileAttributeView view(FileLookup lookup, ImmutableMap<String, FileAttributeView> inheritedViews) {
        return new CustomAttributeView(lookup);
    }
}

// Use custom provider
Configuration config = Configuration.unix()
    .toBuilder()
    .addAttributeProvider(new CustomMetadataProvider())
    .setAttributeViews("basic", "custom")
    .build();

Helper Methods

The class provides static helper methods for implementations:

Validation Helpers:

  • checkType(String, String, Object, Class) - Type-safe value casting
  • invalidType(String, String, Object, Class...) - Exception for invalid types
  • unsettable(String, String, boolean) - Exception for unsettable attributes
  • checkNotCreate(String, String, boolean) - Validation for creation-time restrictions

Install with Tessl CLI

npx tessl i tessl/maven-com-google-jimfs--jimfs

docs

configuration.md

features-monitoring.md

filesystem-creation.md

index.md

path-types.md

tile.json