0
# Jimfs
1

2
Jimfs is an in-memory file system implementation for Java 8+ that provides complete compatibility with the `java.nio.file` abstract file system APIs. It enables developers to create virtual file systems in memory for testing, sandboxing, and temporary file operations without touching the actual filesystem.
3

4
## Package Information
5

6
- **Package Name**: com.google.jimfs:jimfs
7
- **Package Type**: Maven
8
- **Language**: Java 8+
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>com.google.jimfs</groupId>
13
    <artifactId>jimfs</artifactId>
14
    <version>1.3.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import com.google.common.jimfs.Configuration;
22
import com.google.common.jimfs.Jimfs;
23
import java.nio.file.FileSystem;
24
import java.nio.file.Files;
25
import java.nio.file.Path;
26
```
27

28
## Basic Usage
29

30
```java
31
import com.google.common.jimfs.Configuration;
32
import com.google.common.jimfs.Jimfs;
33
import java.nio.file.FileSystem;
34
import java.nio.file.Files;
35
import java.nio.file.Path;
36
import java.nio.charset.StandardCharsets;
37
import java.util.Arrays;
38

39
// Create a new in-memory file system with Unix-style configuration
40
FileSystem fs = Jimfs.newFileSystem(Configuration.unix());
41

42
// Create directories and files
43
Path workDir = fs.getPath("/work");
44
Files.createDirectory(workDir);
45

46
Path configFile = workDir.resolve("config.txt");
47
Files.write(configFile, Arrays.asList("key=value", "debug=true"), StandardCharsets.UTF_8);
48

49
// Read and manipulate files
50
List<String> lines = Files.readAllLines(configFile, StandardCharsets.UTF_8);
51
System.out.println("Config loaded: " + lines.size() + " lines");
52
```
53

54
## Architecture
55

56
Jimfs is built around several key components:
57

58
- **File System Factory**: `Jimfs` class provides static factory methods for creating configured file systems
59
- **Configuration System**: Immutable `Configuration` objects define file system behavior, path types, and feature support
60
- **Path Type System**: Abstract path handling supporting Unix, Windows, and Mac OS X style paths with appropriate behaviors
61
- **Feature System**: Modular feature support for links, symbolic links, secure directory streams, and file channels
62
- **Attribute System**: Extensible file attribute system supporting basic, POSIX, DOS, ACL, and custom attributes
63
- **Watch Service**: Configurable directory watching with polling-based change detection
64

65
## Capabilities
66

67
### File System Creation
68

69
Factory methods for creating in-memory file systems with platform-specific or custom configurations.
70

71
```java { .api }
72
public static FileSystem newFileSystem();
73
public static FileSystem newFileSystem(String name);
74
public static FileSystem newFileSystem(Configuration configuration);
75
public static FileSystem newFileSystem(String name, Configuration configuration);
76
```
77

78
[File System Creation](./filesystem-creation.md)
79

80
### Configuration
81

82
Comprehensive configuration system for customizing file system behavior, from path handling to storage limits.
83

84
```java { .api }
85
public static Configuration unix();
86
public static Configuration osX();
87
public static Configuration windows();
88
public static Configuration forCurrentPlatform();
89
public static Builder builder(PathType pathType);
90
public Builder toBuilder();
91
```
92

93
[Configuration](./configuration.md)
94

95
### Path Types and Normalization
96

97
Path type system supporting different operating system conventions with Unicode normalization options.
98

99
```java { .api }
100
public static PathType unix();
101
public static PathType windows();
102

103
public enum PathNormalization {
104
    NONE, NFC, NFD, CASE_FOLD_UNICODE, CASE_FOLD_ASCII
105
}
106
```
107

108
[Path Types](./path-types.md)
109

110
### Features and Watch Services
111

112
Optional feature system and configurable directory watching capabilities.
113

114
```java { .api }
115
public enum Feature {
116
    LINKS, SYMBOLIC_LINKS, SECURE_DIRECTORY_STREAM, FILE_CHANNEL
117
}
118

119
public static WatchServiceConfiguration polling(long interval, TimeUnit timeUnit);
120
```
121

122
[Features and Monitoring](./features-monitoring.md)
123

124
## Standard java.nio.file Integration
125

126
Jimfs file systems return standard `FileSystem` instances that work seamlessly with all `java.nio.file` APIs:
127

128
- `Files.createDirectory()`, `Files.createFile()`, `Files.delete()`
129
- `Files.copy()`, `Files.move()`, `Files.walk()` 
130
- `Files.newInputStream()`, `Files.newOutputStream()`
131
- `Files.newByteChannel()`, `FileChannel.open()`
132
- `Files.newDirectoryStream()`, `WatchService` support
133
- All standard file attribute views: basic, owner, POSIX, DOS, ACL, user-defined
134

135
## Thread Safety
136

137
- `Configuration` objects are immutable and thread-safe
138
- `FileSystem` instances support concurrent access from multiple threads
139
- `Configuration.Builder` objects are not thread-safe and should not be shared between threads
140

141
## Performance Characteristics
142

143
- In-memory storage with configurable block size (default: 8KB)
144
- Configurable maximum size (default: 4GB) 
145
- Configurable cache for freed blocks to reduce garbage collection
146
- Watch service uses polling with configurable intervals (default: 5 seconds)