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

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)
    .buffered(true);

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);

Reader reader = builder.build();

Console

Utility for logging formatted messages to the console.

Console console = new Console();
console.log("Hello {0}, you have {1} items", "John", 5);

MimeTypeDetector

Utility for detecting MIME types from file extensions or content.

MimeTypeDetector detector = new MimeTypeDetector();

// Detect from file extension
String mimeType = detector.detect("file.pdf");  // "application/pdf"

// Detect from path
String mimeType2 = detector.detect(Paths.get("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
LocalFile file = new LocalFile(MyClass.class, "config.properties");
if (!file.exists()) {
    file = new LocalFile(Paths.get("/etc/myapp/config.properties"));
}

if (file.exists()) {
    try (InputStream is = file.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
try (Reader reader = FileReaderBuilder.create()
        .file(Paths.get("file.txt"))
        .charset(StandardCharsets.UTF_8)
        .buffered(true)
        .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

• Juneau Commons Basics
• Juneau Commons Utils
• JavaDoc: I/O Package