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

features-monitoring.mddocs/

Features and Monitoring

Jimfs provides optional features for enhanced file system functionality and configurable directory monitoring through watch services.

Core Imports

import com.google.common.jimfs.Feature;
import com.google.common.jimfs.WatchServiceConfiguration;
import com.google.common.jimfs.FileTimeSource;
import java.util.concurrent.TimeUnit;
import java.nio.file.attribute.FileTime;

Optional Features

The Feature enum defines optional capabilities that can be enabled or disabled for a file system.

public enum Feature {
    LINKS, SYMBOLIC_LINKS, SECURE_DIRECTORY_STREAM, FILE_CHANNEL
}

Hard Links Support

LINKS

Enables support for hard links to regular files.

Affected APIs:

  • Files.createLink(Path, Path)

Behavior:

  • When enabled: Hard links can be created between regular files
  • When disabled: Files.createLink() throws UnsupportedOperationException

Usage Example:

Configuration config = Configuration.unix()
    .toBuilder()
    .setSupportedFeatures(Feature.LINKS)
    .build();

FileSystem fs = Jimfs.newFileSystem(config);
Path original = fs.getPath("/data.txt");
Path hardLink = fs.getPath("/link-to-data.txt");

Files.write(original, "content".getBytes());
Files.createLink(hardLink, original);  // Creates hard link

Symbolic Links Support

SYMBOLIC_LINKS

Enables support for symbolic links.

Affected APIs:

  • Files.createSymbolicLink(Path, Path, FileAttribute...)
  • Files.readSymbolicLink(Path)

Behavior:

  • When enabled: Symbolic links can be created and read
  • When disabled: These methods throw UnsupportedOperationException

Usage Example:

Configuration config = Configuration.unix()
    .toBuilder()
    .setSupportedFeatures(Feature.SYMBOLIC_LINKS)
    .build();

FileSystem fs = Jimfs.newFileSystem(config);
Path target = fs.getPath("/target.txt");
Path symlink = fs.getPath("/link.txt");

Files.write(target, "content".getBytes());
Files.createSymbolicLink(symlink, target);
Path resolved = Files.readSymbolicLink(symlink);

Secure Directory Stream Support

SECURE_DIRECTORY_STREAM

Enables SecureDirectoryStream support for directory operations.

Affected APIs:

  • Files.newDirectoryStream(Path)
  • Files.newDirectoryStream(Path, DirectoryStream.Filter)
  • Files.newDirectoryStream(Path, String)

Behavior:

  • When enabled: DirectoryStream instances also implement SecureDirectoryStream
  • When disabled: Directory streams are basic implementations without secure operations

Usage Example:

Configuration config = Configuration.unix()
    .toBuilder()
    .setSupportedFeatures(Feature.SECURE_DIRECTORY_STREAM)
    .build();

FileSystem fs = Jimfs.newFileSystem(config);
Path dir = fs.getPath("/secure-dir");
Files.createDirectory(dir);

try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir)) {
    if (stream instanceof SecureDirectoryStream) {
        SecureDirectoryStream<Path> secureStream = (SecureDirectoryStream<Path>) stream;
        // Use secure operations relative to the open directory
    }
}

File Channel Support

FILE_CHANNEL

Enables FileChannel and AsynchronousFileChannel support.

Affected APIs:

  • Files.newByteChannel(Path, OpenOption...)
  • Files.newByteChannel(Path, Set, FileAttribute...)
  • FileChannel.open(Path, OpenOption...)
  • FileChannel.open(Path, Set, FileAttribute...)
  • AsynchronousFileChannel.open(Path, OpenOption...)
  • AsynchronousFileChannel.open(Path, Set, ExecutorService, FileAttribute...)

Behavior:

  • When enabled: Byte channels are FileChannel instances, and FileChannel.open() works
  • When disabled: Byte channels are basic SeekableByteChannel instances, FileChannel.open() throws UnsupportedOperationException

Usage Example:

Configuration config = Configuration.unix()
    .toBuilder()
    .setSupportedFeatures(Feature.FILE_CHANNEL)
    .build();

FileSystem fs = Jimfs.newFileSystem(config);
Path file = fs.getPath("/data.txt");

try (FileChannel channel = FileChannel.open(file, StandardOpenOption.CREATE, StandardOpenOption.WRITE)) {
    ByteBuffer buffer = ByteBuffer.wrap("Hello World".getBytes());
    channel.write(buffer);
}

Watch Service Configuration

The WatchServiceConfiguration class configures directory monitoring behavior.

Polling Configuration

Create a polling-based watch service configuration.

public static WatchServiceConfiguration polling(long interval, TimeUnit timeUnit);

Parameters:

  • interval - Polling interval (must be positive)
  • timeUnit - Time unit for the interval

Usage Example:

// Poll every 2 seconds
WatchServiceConfiguration watchConfig = WatchServiceConfiguration.polling(2, TimeUnit.SECONDS);

Configuration config = Configuration.unix()
    .toBuilder()
    .setWatchServiceConfiguration(watchConfig)
    .build();

FileSystem fs = Jimfs.newFileSystem(config);
try (WatchService watchService = fs.newWatchService()) {
    Path dir = fs.getPath("/watched-dir");
    Files.createDirectory(dir);
    
    WatchKey key = dir.register(watchService, 
        StandardWatchEventKinds.ENTRY_CREATE,
        StandardWatchEventKinds.ENTRY_DELETE,
        StandardWatchEventKinds.ENTRY_MODIFY);
    
    // Watch service will poll every 2 seconds for changes
}

Default Configuration

The default watch service configuration uses 5-second polling:

// Equivalent to WatchServiceConfiguration.polling(5, TimeUnit.SECONDS)
Configuration config = Configuration.unix();  // Uses default watch config

File Time Source

The FileTimeSource interface allows customization of file timestamp generation.

Interface Definition

public interface FileTimeSource {
    FileTime now();
}

Custom Time Source

Implement custom time sources for testing or specialized behavior.

Usage Example:

// Custom time source for testing
FileTimeSource fixedTimeSource = new FileTimeSource() {
    private final FileTime fixedTime = FileTime.fromMillis(1609459200000L); // 2021-01-01
    
    @Override
    public FileTime now() {
        return fixedTime;
    }
};

Configuration config = Configuration.unix()
    .toBuilder()
    .setFileTimeSource(fixedTimeSource)
    .build();

FileSystem fs = Jimfs.newFileSystem(config);
Path file = fs.getPath("/test.txt");
Files.write(file, "content".getBytes());

// File timestamps will use the fixed time
BasicFileAttributes attrs = Files.readAttributes(file, BasicFileAttributes.class);
System.out.println("Created: " + attrs.creationTime());

Feature Combinations

Typical Combinations

Full-featured Unix-like:

Configuration config = Configuration.unix()
    .toBuilder()
    .setSupportedFeatures(
        Feature.LINKS, 
        Feature.SYMBOLIC_LINKS, 
        Feature.SECURE_DIRECTORY_STREAM, 
        Feature.FILE_CHANNEL
    )
    .build();

Basic file system:

Configuration config = Configuration.unix()
    .toBuilder()
    .setSupportedFeatures()  // No optional features
    .build();

Testing-focused:

Configuration config = Configuration.unix()
    .toBuilder()
    .setSupportedFeatures(Feature.FILE_CHANNEL)  // File channels for testing I/O
    .setWatchServiceConfiguration(WatchServiceConfiguration.polling(100, TimeUnit.MILLISECONDS))  // Fast polling
    .build();

Performance Considerations

Watch Service Performance

  • Polling frequency affects CPU usage and responsiveness
  • More frequent polling = higher CPU usage but faster change detection
  • Less frequent polling = lower CPU usage but slower change detection

Feature Overhead

  • Each enabled feature adds minimal memory overhead
  • FILE_CHANNEL feature enables more complex I/O operations
  • SECURE_DIRECTORY_STREAM adds additional security checks
  • Features can be disabled to minimize overhead in resource-constrained environments

Thread Safety

  • WatchServiceConfiguration objects are immutable and thread-safe
  • FileTimeSource implementations should be thread-safe
  • Watch services support concurrent access from multiple threads
  • Feature configuration is immutable once the file system is created

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