Skip to main content

I/O Package

The org.apache.juneau.commons.io package provides file and stream utilities, console support, MIME type detection, and path builders for working with files and I/O operations.

Key Classes​

LocalFile​

Represents a file that can be located either on the classpath or in the file system.

// Classpath file
LocalFile classpathFile = new LocalFile(MyClass.class, "config.properties");
InputStream is = classpathFile.read();

// File system file
LocalFile fsFile = new LocalFile(Paths.get("/path/to/file.txt"));
InputStream is2 = fsFile.read();

// With caching for repeated access
LocalFile cachedFile = new LocalFile(MyClass.class, "template.html");
cachedFile.cache();  // Cache contents in memory
InputStream is3 = cachedFile.read();  // Fast - uses cache

// Check existence without triggering an exception
if (fsFile.exists()) {
    InputStream is4 = fsFile.read();
}

LocalDir​

Represents a directory that can be located either on the classpath or in the file system.

// Classpath directory
LocalDir classpathDir = new LocalDir(MyClass.class, "templates");
LocalFile file = classpathDir.resolve("index.html");

// File system directory
LocalDir fsDir = new LocalDir(Paths.get("/var/config"));
LocalFile file2 = fsDir.resolve("app.properties");

// Package directory (null or empty path)
LocalDir packageDir = new LocalDir(MyClass.class, null);
LocalFile file3 = packageDir.resolve("resource.txt");

FileReaderBuilder​

Fluent builder for creating Reader instances from files.

FileReaderBuilder builder = FileReaderBuilder.create()
    .file(Paths.get("file.txt"))
    .charset(StandardCharsets.UTF_8)
    .allowNoFile(true);  // Don't throw if the file doesn't exist

Reader reader = builder.build();

FileWriterBuilder​

Fluent builder for creating Writer instances for files.

FileWriterBuilder builder = FileWriterBuilder.create()
    .file(Paths.get("output.txt"))
    .charset(StandardCharsets.UTF_8)
    .append(true)
    .buffered(true);

Writer writer = builder.build();

PathReaderBuilder​

Fluent builder for creating Reader instances from Path objects.

PathReaderBuilder builder = PathReaderBuilder.create()
    .path(Paths.get("file.txt"))
    .charset(StandardCharsets.UTF_8)
    .allowNoFile(true);  // Don't throw if the file doesn't exist

Reader reader = builder.build();

Console​

Utility for printing formatted (printf-style) messages to the console.

Console.out("Hello %s, you have %s items", "John", 5);
Console.err("Something went wrong: %s", errorMessage);

MimeTypeDetector​

Utility for detecting MIME types from file extensions.

// Use the default, pre-populated instance
String mimeType = MimeTypeDetector.DEFAULT.getContentType("file.pdf");  // "application/pdf"

// Or build a customized instance
MimeTypeDetector detector = MimeTypeDetector.builder()
    .addDefaultMappings()
    .build();
String mimeType2 = detector.getContentType("image.jpg");  // "image/jpeg"

CharSequenceReader​

A Reader implementation that reads from a CharSequence.

CharSequenceReader reader = new CharSequenceReader("Hello World");
int ch = reader.read();  // 'H'

ReaderInputStream​

An InputStream implementation that reads from a Reader.

Reader reader = new StringReader("Hello World");
ReaderInputStream inputStream = new ReaderInputStream(reader, StandardCharsets.UTF_8);
byte[] bytes = inputStream.readAllBytes();

StringBuilderWriter​

A Writer implementation that writes to a StringBuilder.

StringBuilderWriter writer = new StringBuilderWriter();
writer.write("Hello");
writer.write(" World");
String result = writer.toString();  // "Hello World"

NoCloseOutputStream​

An OutputStream wrapper that prevents the underlying stream from being closed.

OutputStream original = new FileOutputStream("file.txt");
NoCloseOutputStream wrapped = new NoCloseOutputStream(original);
wrapped.close();  // Does not close the original stream

NoCloseWriter​

A Writer wrapper that prevents the underlying writer from being closed.

Writer original = new FileWriter("file.txt");
NoCloseWriter wrapped = new NoCloseWriter(original);
wrapped.close();  // Does not close the original writer

Common Patterns​

Reading Files from Classpath or File System​

// Try classpath first, then file system - use exists() to check without
// relying on exception handling for control flow.
LocalFile file = new LocalFile(MyClass.class, "config.properties");
LocalFile fsFile = new LocalFile(Paths.get("/etc/myapp/config.properties"));
LocalFile resolved = file.exists() ? file : fsFile;

try (InputStream is = resolved.read()) {
    // Read file contents
}

Caching File Contents​

// Cache file for repeated access
LocalFile template = new LocalFile(MyClass.class, "template.html");
template.cache();  // Load into memory

// Multiple reads use cached content
for (int i = 0; i < 100; i++) {
    try (InputStream is = template.read()) {
        // Fast - uses cached content
    }
}

Working with Directories​

// Resolve files within a directory
LocalDir templates = new LocalDir(MyClass.class, "templates");
LocalFile index = templates.resolve("index.html");
LocalFile about = templates.resolve("about.html");

File I/O with Builders​

// Read file with specific charset, using a Path
try (Reader reader = FileReaderBuilder.create()
        .file(Paths.get("file.txt"))
        .charset(StandardCharsets.UTF_8)
        .build()) {
    // Read from file
}

// Write file with append mode
try (Writer writer = FileWriterBuilder.create()
        .file(Paths.get("output.txt"))
        .charset(StandardCharsets.UTF_8)
        .append(true)
        .buffered(true)
        .build()) {
    writer.write("New content");
}

See Also​