0
# Configuration
1

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

4
## Core Imports
5

6
```java
7
import com.google.common.jimfs.Configuration;
8
import com.google.common.jimfs.PathType;
9
import com.google.common.jimfs.Feature;
10
import com.google.common.jimfs.PathNormalization;
11
import com.google.common.jimfs.WatchServiceConfiguration;
12
import com.google.common.jimfs.FileTimeSource;
13
import com.google.common.jimfs.AttributeProvider;
14
```
15

16
## Predefined Configurations
17

18
### Unix Configuration
19

20
Creates a Unix-like file system configuration.
21

22
```java { .api }
23
public static Configuration unix();
24
```
25

26
**Characteristics:**
27
- Uses `/` as path separator
28
- Root: `/`, working directory: `/work`
29
- Case-sensitive file lookup
30
- Supports basic file attributes only
31
- Features: hard links, symbolic links, secure directory streams, file channels
32

33
**Usage Example:**
34
```java
35
Configuration config = Configuration.unix();
36
FileSystem fs = Jimfs.newFileSystem(config);
37
```
38

39
### Mac OS X Configuration
40

41
Creates a Mac OS X-like file system configuration.
42

43
```java { .api }
44
public static Configuration osX();
45
```
46

47
**Characteristics:**
48
- Uses `/` as path separator (Unix-style paths)
49
- Root: `/`, working directory: `/work`
50
- Unicode normalization (NFC display, NFD canonical)
51
- Case-insensitive (ASCII) file lookup
52
- Supports basic file attributes only
53
- Features: hard links, symbolic links, file channels (no secure directory streams)
54

55
**Usage Example:**
56
```java
57
Configuration config = Configuration.osX();
58
FileSystem fs = Jimfs.newFileSystem(config);
59
```
60

61
### Windows Configuration
62

63
Creates a Windows-like file system configuration.
64

65
```java { .api }
66
public static Configuration windows();
67
```
68

69
**Characteristics:**
70
- Uses `\` as canonical separator, recognizes `/` when parsing
71
- Root: `C:\`, working directory: `C:\work`
72
- Case-insensitive (ASCII) file lookup
73
- Path equality uses canonical form
74
- Supports basic file attributes only
75
- Features: hard links, symbolic links, file channels
76

77
**Usage Example:**
78
```java
79
Configuration config = Configuration.windows();
80
FileSystem fs = Jimfs.newFileSystem(config);
81
```
82

83
### Current Platform Configuration
84

85
Creates a configuration appropriate for the current operating system.
86

87
```java { .api }
88
public static Configuration forCurrentPlatform();
89
```
90

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

93
## Configuration Builder
94

95
### Creating a Builder
96

97
Create a new configuration builder with a specific path type.
98

99
```java { .api }
100
public static Builder builder(PathType pathType);
101
```
102

103
**Parameters:**
104
- `pathType` - The path type to use (from `PathType.unix()` or `PathType.windows()`)
105

106
### Converting to Builder
107

108
Create a builder from an existing configuration.
109

110
```java { .api }
111
public Builder toBuilder();
112
```
113

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

116
## Configuration.Builder
117

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

120
### Default Constants
121

122
```java { .api }
123
public static final int DEFAULT_BLOCK_SIZE = 8192;      // 8 KB
124
public static final long DEFAULT_MAX_SIZE = 4L * 1024 * 1024 * 1024;  // 4 GB
125
public static final long DEFAULT_MAX_CACHE_SIZE = -1;   // Equal to max size
126
```
127

128
### Path Normalization
129

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

132
```java { .api }
133
public Builder setNameDisplayNormalization(PathNormalization first, PathNormalization... more);
134
public Builder setNameCanonicalNormalization(PathNormalization first, PathNormalization... more);
135
public Builder setPathEqualityUsesCanonicalForm(boolean useCanonicalForm);
136
```
137

138
**Parameters:**
139
- `first`, `more` - Path normalization options (NONE, NFC, NFD, CASE_FOLD_UNICODE, CASE_FOLD_ASCII)
140
- `useCanonicalForm` - Whether Path objects use canonical form for equality (default: false)
141

142
**Usage Example:**
143
```java
144
Configuration config = Configuration.unix()
145
    .toBuilder()
146
    .setNameCanonicalNormalization(PathNormalization.NFD, PathNormalization.CASE_FOLD_ASCII)
147
    .setPathEqualityUsesCanonicalForm(true)
148
    .build();
149
```
150

151
### Storage Configuration
152

153
Configure file system storage limits and block allocation.
154

155
```java { .api }
156
public Builder setBlockSize(int blockSize);
157
public Builder setMaxSize(long maxSize);
158
public Builder setMaxCacheSize(long maxCacheSize);
159
```
160

161
**Parameters:**
162
- `blockSize` - Block size in bytes (must be positive, default: 8192)
163
- `maxSize` - Maximum storage size in bytes (must be positive, default: 4GB)
164
- `maxCacheSize` - Maximum cached unused space in bytes (≥0, default: equal to maxSize, 0 disables caching)
165

166
**Usage Example:**
167
```java
168
Configuration config = Configuration.unix()
169
    .toBuilder()
170
    .setBlockSize(4096)                    // 4KB blocks
171
    .setMaxSize(512 * 1024 * 1024)         // 512MB limit
172
    .setMaxCacheSize(64 * 1024 * 1024)     // 64MB cache
173
    .build();
174
```
175

176
### Attribute Configuration
177

178
Configure supported file attribute views and default values.
179

180
```java { .api }
181
public Builder setAttributeViews(String first, String... more);
182
public Builder addAttributeProvider(AttributeProvider provider);
183
public Builder setDefaultAttributeValue(String attribute, Object value);
184
```
185

186
**Supported Attribute Views:**
187
- `"basic"` - BasicFileAttributeView/BasicFileAttributes
188
- `"owner"` - FileOwnerAttributeView
189
- `"posix"` - PosixFileAttributeView/PosixFileAttributes
190
- `"unix"` - Unix-specific attributes
191
- `"dos"` - DosFileAttributeView/DosFileAttributes
192
- `"acl"` - AclFileAttributeView
193
- `"user"` - UserDefinedFileAttributeView
194

195
**Usage Example:**
196
```java
197
Configuration config = Configuration.unix()
198
    .toBuilder()
199
    .setAttributeViews("basic", "owner", "posix", "unix")
200
    .setDefaultAttributeValue("posix:permissions", "rwxr-xr-x")
201
    .setDefaultAttributeValue("owner:owner", "testuser")
202
    .build();
203
```
204

205
### File System Structure
206

207
Configure roots and working directory.
208

209
```java { .api }
210
public Builder setRoots(String first, String... more);
211
public Builder setWorkingDirectory(String workingDirectory);
212
```
213

214
**Parameters:**
215
- `first`, `more` - Root paths (must be valid root paths for the path type)
216
- `workingDirectory` - Working directory path (must be absolute)
217

218
**Usage Example:**
219
```java
220
Configuration config = Configuration.builder(PathType.windows())
221
    .setRoots("C:\\", "D:\\", "E:\\")
222
    .setWorkingDirectory("C:\\Users\\testuser")
223
    .build();
224
```
225

226
### Features and Services
227

228
Configure optional features and services.
229

230
```java { .api }
231
public Builder setSupportedFeatures(Feature... features);
232
public Builder setWatchServiceConfiguration(WatchServiceConfiguration config);
233
public Builder setFileTimeSource(FileTimeSource source);
234
```
235

236
**Parameters:**
237
- `features` - Supported features (LINKS, SYMBOLIC_LINKS, SECURE_DIRECTORY_STREAM, FILE_CHANNEL)
238
- `config` - Watch service configuration (default: 5-second polling)
239
- `source` - Custom time source for file timestamps
240

241
**Usage Example:**
242
```java
243
Configuration config = Configuration.unix()
244
    .toBuilder()
245
    .setSupportedFeatures(Feature.LINKS, Feature.SYMBOLIC_LINKS, Feature.FILE_CHANNEL)
246
    .setWatchServiceConfiguration(WatchServiceConfiguration.polling(1, TimeUnit.SECONDS))
247
    .build();
248
```
249

250
### Building Configuration
251

252
Create the immutable configuration.
253

254
```java { .api }
255
public Configuration build();
256
```
257

258
Returns a new immutable `Configuration` object with the specified settings.
259

260
## Thread Safety
261

262
- `Configuration` objects are immutable and thread-safe
263
- `Configuration.Builder` objects are mutable and not thread-safe
264
- Multiple builders can be created from the same configuration safely
265

266
## Validation
267

268
The builder validates configuration parameters:
269
- Block sizes must be positive
270
- Max sizes must be positive  
271
- Max cache sizes must be non-negative
272
- Roots must be valid root paths for the path type
273
- Working directories must be absolute paths
274
- Attribute strings must follow "view:attribute" format
275
- Path normalizations cannot conflict (e.g., can't set both NFC and NFD)
276

277
## AttributeProvider
278

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

281
### Abstract Class Definition
282

283
```java { .api }
284
public abstract class AttributeProvider {
285
    public abstract String name();
286
    public ImmutableSet<String> inherits();
287
    public abstract Class<? extends FileAttributeView> viewType();
288
    public abstract FileAttributeView view(FileLookup lookup, ImmutableMap<String, FileAttributeView> inheritedViews);
289
    public ImmutableMap<String, ?> defaultValues(Map<String, ?> userDefaults);
290
    public abstract ImmutableSet<String> fixedAttributes();
291
    public boolean supports(String attribute);
292
    public ImmutableSet<String> attributes(File file);
293
    public abstract Object get(File file, String attribute);
294
    public abstract void set(File file, String view, String attribute, Object value, boolean create);
295
    public Class<? extends BasicFileAttributes> attributesType();
296
    public BasicFileAttributes readAttributes(File file);
297
}
298
```
299

300
### Key Methods
301

302
#### Core Abstract Methods
303

304
**Provider Identity:**
305
- `name()` - Returns the view name for this provider (e.g., "posix", "dos")
306
- `viewType()` - Returns the FileAttributeView interface class this provider supports
307

308
**Attribute Handling:**
309
- `fixedAttributes()` - Returns attributes always supported by this provider
310
- `get(File, String)` - Gets attribute value from file
311
- `set(File, String, String, Object, boolean)` - Sets attribute value in file
312
- `view(FileLookup, Map)` - Creates FileAttributeView instance for file operations
313

314
#### Optional Override Methods
315

316
**Inheritance:**
317
- `inherits()` - Names of other providers this provider inherits from (default: empty)
318

319
**Default Values:**
320
- `defaultValues(Map)` - Default attribute values for new files (default: empty)
321

322
**Dynamic Attributes:**
323
- `attributes(File)` - Attributes present in specific file (default: fixedAttributes())
324
- `supports(String)` - Whether provider directly supports attribute (default: uses fixedAttributes())
325

326
**Attributes Object Support:**
327
- `attributesType()` - BasicFileAttributes subclass if supported (default: null)
328
- `readAttributes(File)` - Read attributes as object (default: throws UnsupportedOperationException)
329

330
### Usage Example
331

332
**Custom Attribute Provider:**
333
```java
334
public class CustomMetadataProvider extends AttributeProvider {
335
    @Override
336
    public String name() {
337
        return "custom";
338
    }
339
    
340
    @Override
341
    public Class<? extends FileAttributeView> viewType() {
342
        return CustomAttributeView.class;
343
    }
344
    
345
    @Override
346
    public ImmutableSet<String> fixedAttributes() {
347
        return ImmutableSet.of("author", "description", "tags");
348
    }
349
    
350
    @Override
351
    public Object get(File file, String attribute) {
352
        switch (attribute) {
353
            case "author": return file.getAttribute("custom:author");
354
            case "description": return file.getAttribute("custom:description");
355
            case "tags": return file.getAttribute("custom:tags");
356
            default: return null;
357
        }
358
    }
359
    
360
    @Override
361
    public void set(File file, String view, String attribute, Object value, boolean create) {
362
        checkNotNull(value);
363
        switch (attribute) {
364
            case "author":
365
                file.setAttribute("custom:author", checkType(view, attribute, value, String.class));
366
                break;
367
            case "description":
368
                file.setAttribute("custom:description", checkType(view, attribute, value, String.class));
369
                break;
370
            case "tags":
371
                file.setAttribute("custom:tags", checkType(view, attribute, value, List.class));
372
                break;
373
            default:
374
                throw new IllegalArgumentException("unsupported attribute: " + view + ":" + attribute);
375
        }
376
    }
377
    
378
    @Override
379
    public FileAttributeView view(FileLookup lookup, ImmutableMap<String, FileAttributeView> inheritedViews) {
380
        return new CustomAttributeView(lookup);
381
    }
382
}
383

384
// Use custom provider
385
Configuration config = Configuration.unix()
386
    .toBuilder()
387
    .addAttributeProvider(new CustomMetadataProvider())
388
    .setAttributeViews("basic", "custom")
389
    .build();
390
```
391

392
### Helper Methods
393

394
The class provides static helper methods for implementations:
395

396
**Validation Helpers:**
397
- `checkType(String, String, Object, Class)` - Type-safe value casting
398
- `invalidType(String, String, Object, Class...)` - Exception for invalid types
399
- `unsettable(String, String, boolean)` - Exception for unsettable attributes
400
- `checkNotCreate(String, String, boolean)` - Validation for creation-time restrictions