Packages, Input-Output Streams and File Handling in Java

Formalize — package as naming and visibility control

A package is a named container for a set of functionally related classes and subpackages. It serves two linked purposes, as emphasized in the standard references:

1. Name-space partitioning. Every package forms its own name space, so a short name need be unique only inside that package. Without packages every class lives in one global space and you would eventually run out of convenient names — the classic "who gets to use Foobar?" problem.

1. Access control. Packages add a dimension beyond private/public. A class or member with default (no modifier) access is visible to every class in the same package but invisible outside it; protected adds visibility to subclasses outside the package; public opens it everywhere; private keeps it inside one class. Packages are therefore both a naming and an encapsulation mechanism.

Core language rules:

• If you omit a package statement, the class goes into the default package (the unnamed package). This is fine for tiny demos but inadequate for real applications.
• A package hierarchy is written with dots, each dot meaning "one level deeper in the directory": package pkg1.pkg2.pkg3; must be stored as pkg1/pkg2/pkg3 on Linux/macOS or pkg1\pkg2\pkg3 on Windows. Case must match exactly — MyPackage and mypackage are different.
• The Java runtime finds packages from the current working directory, from the CLASSPATH environment variable, or from -classpath on the java/javac command line. Beginning with JDK 9 a package may also be found on the module path, but for this course the class path is the relevant mechanism.
• More than one source file may declare package mypackage; — they all contribute classes to that single logical package, which is usually spread across many files.
• Renaming a package always means renaming the directory tree, because the two are mirrors of each other.

How you use a packaged class:

Either import it once at the top and use the short name, or write the fully qualified name everywhere:

// with import
import dir1.dir2.c;
c obj = new c();

// without import — fully qualified at point of use
dir1.dir2.c obj = new dir1.dir2.c();

Both compile to the same bytecode; import is pure convenience.

Namespace collision defined: A namespace collision occurs when two classes need the same short name and the compiler cannot tell which one you mean. Inside one package that is forbidden — you cannot have two files named a.java in the same folder. Across packages it is allowed, because the true identity of a class is not its short name but its fully qualified name: package path plus class name.

Two packages can each contain a.java and coexist because dir1.a and dir2.a are different types, stored in different directories, just as two houses can both be "12, Park Street" if they are in different cities. The package prefix is the city.

Formalize — declaring and placing a package

To make a class belong to a package you write a package statement as the very first non-comment line of the source file, before any import and before class:

package myPackage.myPackageA;
public class S1 {
    public S1() {
        System.out.println("This is class S1");
    }
}

Saved as S1.java, compiling with javac -d . S1.java (or simply javac S1.java from the correct root) produces S1.class inside folder myPackage/myPackageA. The -d option is the clean way to have the compiler create missing package folders automatically; without it you must already be in a directory where the relative path myPackage/myPackageA exists.

General form: package pkg1[.pkg2[.pkg3]]; — each pkg segment must be a legal identifier ([A-Za-z_][A-Za-z0-9_]*, conventionally all lowercase). The hierarchy must be reflected in the file system: package a.b.c; must be stored as a/b/c (Unix) or a\b\c (Windows). The directory name must match the package name exactly, including case.

Single-package rule: A source file written as *.java can contain at most one package statement. The reason is that one *.class file can live in only one directory at a time — a file cannot sit in dir1 and dir2 simultaneously. You cannot write:

package dir1;
package dir2;  // compile error
class A { }

Public scope: Write public class S1 when you intend the class to be reusable outside its own package — for example to be extended or instantiated from Test code in another package. A class with default (package-private) access is invisible outside its package. The file name must match the public class name: public class S1 must live in S1.java.

Creating a class at any level — the repeatable recipe

Steps to create S1 in myPackageA:

1. Ensure the folder path myPackage/myPackageA exists or will be created by javac -d ..
2. Start S1.java with package myPackage.myPackageA; as line 1.
3. Define public class S1 with its constructor.
4. Save as S1.java (matching the public class name) and compile: javac -d . myPackage/myPackageA/S1.java or equivalently javac -d . S1.java if the file already lives inside its package folder and imports are resolved.

The compiler creates S1.class in the same package folder myPackage/myPackageA. The same recipe with a different class name yields S2.class side by side:

// S2.java — same package line, different class
package myPackage.myPackageA;
public class S2 {
    public S2() { System.out.println("This is class S2"); }
}

Going one level deeper, for A in IJK you add one more dot segment because you go one more folder down:

package myPackage.myPackageB.IJK;
public class A {
    public A() { System.out.println("This is class A"); }
}

Saved as A.java inside myPackageB/IJK (or compiled with -d), this yields A.class there. Repeating the pattern fills every row:

• S3 keeps myPackage.myPackageA
• S4–S6 use myPackage.myPackageB
• D E F use myPackage.myPackageA.DEG
• X Y Z use myPackage.myPackageB.XYZ

Formalize — import placement and forms

An import statement brings a class from another package into visibility so you can refer to it by its short name. General form:

import pkg1[.pkg2].(classname | *);

• import java.util.Date; — imports one class Date from java.util.
• import java.io.*; — imports every public class directly in java.io (but not those in subpackages like java.io.nio).

Rules:

• import lines appear immediately after the package line (if present) and before any class declaration. Multiple imports are allowed and order does not matter.
• Depth is unbounded except by the file system: a.b.c.d.E is legal if the directory chain exists.
• java.lang.* is implicitly imported by the compiler — equivalent to writing import java.lang.*; at the top of every file. That is why String, Math, System work without an import.
• import is optional. Wherever you could use a short name plus an import, you may instead write the fully qualified name inline: java.util.Date d = new java.util.Date(); compiles without any import.

To use classes A and B from ABC where ABC lives under myPackage.myPackageA, you have two equivalent styles:

import myPackage.myPackageA.ABC.*;   // all classes in ABC
// or
import myPackage.myPackageA.ABC.A;
import myPackage.myPackageA.ABC.B;   // only A and B

Follow the hierarchy with dots: outermost myPackage dot myPackageA dot ABC dot *. The star is a shorthand for "all public types in that exact package".

A small test program using the star form:

import myPackage.myPackageA.ABC.*;
public class Test {
    public static void main(String[] args) {
        B b1 = new B();
        C c1 = new C();
    }
}

Once the import is in place you create objects with short names B and C directly. Without the import you would write myPackage.myPackageA.ABC.B b1 = new myPackage.myPackageA.ABC.B(); each time — correct but verbose.

Choice in practice: Large code bases use the star when many classes from one feature package are needed (for example import mypack.*; in the textbook's TestBalance demo), and single-class imports when only one type is needed and you want the dependency to be explicit and readable in code review.

The clash scenario: Suppose ABC and IJK each contain a class called A — A in ABC might be a bank account model while A in IJK might be an audit logger, but the short name coincides. If you write:

import myPackage.myPackageA.ABC.*;
import myPackage.myPackageB.IJK.*;
public class Test {
    public static void main(String[] args) {
        A a1 = new A();   // which A?
    }
}

the compiler reports a compile-time error: reference to A is ambiguous. Both star imports silently coexist until you actually try to use the colliding short name — only then must you disambiguate.

This mirrors the textbook note: "If a class with the same name exists in two different packages that you import using the star form, the compiler will remain silent, unless you try to use one of the classes. In that case, you will get a compile-time error and have to explicitly name the class specifying its package."

Formalize — Scanner's role and wiring

The Scanner class is a predefined service in java.util, designed for quick, formatted input. Its job is to tokenize an input source and convert tokens to Java types. Sources can be many: keyboard, a file stream, a String, a network channel.

To use it you must import it — unlike java.lang, java.util is not implicitly imported:

import java.util.Scanner;

For keyboard input you create a Scanner object and connect it to the keyboard by passing System.in:

Scanner a = new Scanner(System.in);

Breakdown:

• Scanner — the type of the helper.
• a — the object name (often called sc or scanner by convention).
• new Scanner(...) — calls the constructor that stores the source.
• System.in — an InputStream object (a byte stream) that the JVM ties to the keyboard by default. In the stream hierarchy, System.in is the screen linked to the keyboard, System.out the screen linked to the monitor.

After this one association, every read through a comes from the keyboard until the scanner is closed.

Architecture note: Under the hood Scanner wraps the byte stream with decoding (bytes → characters via the platform default charset) and tokenization (splitting on whitespace by default). You do not see these layers, but they explain why Scanner can offer nextInt() directly while raw System.in.read() only yields bytes.

Formalize — what java.io.File does and does not do

The File class lives in java.io (so import java.io.File; is required). Its purpose is to operate on the attributes or characteristics of a file or directory, not on the data inside. Attributes include name, parent folder, full path, length in bytes, last-modified timestamp, and permission flags such as readable, writable, hidden, absolute.

• Reading or writing the actual bytes/characters needs other stream classes (FileInputStream, FileReader, BufferedReader, Scanner, PrintWriter, covered in 19.6–19.9).
• A directory in Java is simply treated as a File with one extra property: the list of file names it contains, accessible via list() / listFiles().

Platform independence nuance: Java is platform independent because of the Java Virtual Machine — you write once and run on Linux, Windows, or macOS. However, the file naming convention itself follows the underlying operating system beneath the JVM. How a path is written (slashes versus backslashes, allowed characters, case sensitivity), what constitutes a root (/ versus C:\), and what names are legal are handled by the OS. Your Java code supplies a path string, and the JVM together with the OS resolves the association. The lean design choice is deliberate: Java does not virtualize the file system, it adapts to it.

A file named F1.txt on disk can be opened, closed, read, or written, but the File object f1 itself only gives you metadata. Once you associate a File object with a path, every query is a question to that catalogue card.

Path names — absolute versus relative

A path name tells both the file name and the folder chain required to reach it.

• Absolute (full) path starts from the root. Example: C:/Data/first.java means "start at root drive C:, go into folder Data, find first.java". Absolute paths are unambiguous but tie your code to one machine layout.
• Relative path starts from the directory where the program is running (the current working directory). Example: if your program lives in myProject and the file is at myProject/data/first.java, passing "data/first.java" is sufficient without going all the way to C:. Relative paths make a project portable across installations.

Default rule: File f1 = new File("a.java"); supplies only the name. The rule is that the file is assumed to be in the same directory as the running program. f1 is then linked to that a.java in the current folder; from f1 you can query attributes or later connect streams to read or write.

Virtual association: Creating a File object does not create a file on disk. You are creating a virtual association — a handle — that lets you manipulate an existing file or later create a new one through a stream. The file on disk stays where it is; f1 is the pointer.

The three constructors: Pick the one that matches how your path information is split:

1. File(String pathname) — one string that includes path and name together.
2. File(String parent, String child) — two strings: parent path and file name.
3. File(File parent, String child) — a File object for the parent folder plus the file name string. A fourth overload File(URI uri) exists in the library but is outside this lecture's scope.

Decision guide: If your code builds a path by concatenating strings you likely want form 1 or 2; if you already hold a File for a directory (for example after listFiles()), form 3 avoids re-parsing the parent string.

Formalize — stream as abstraction and placement in the hierarchy

A stream is a virtual pipeline that connects a program to a place where data comes from or goes to. It is an abstraction layered on top of a physical device or file by the Java I/O system. All data passing between source/sink and program travels through primary memory (RAM) via the stream, and the stream hides device specifics behind a uniform interface.

Physical picture for a file:

disk: first.txt (bytes on storage)
        ↕
   stream (pipe, hosted in RAM, managed by FileReader/FileInputStream/etc.)
        ↕
   program variables in heap

For a file, the file on disk holds the bytes, the pipe links it to the program, and through the pipe you read bytes into primary memory or write bytes from primary memory back to disk. Whether reading or writing, the data lands in RAM buffers first — you never manipulate disk bytes in place.

At the top of the class hierarchy are four abstract bases:

• InputStream / OutputStream — byte streams (binary data, any file, images, sockets). Byte I/O is the lowest common denominator; even character streams ultimately use bytes.
• Reader / Writer — character streams (Unicode text, internationalized). Added in Java 1.1; preferred when dealing with characters or strings because they handle charset decoding correctly.

Every concrete class — FileInputStream, FileOutputStream, FileReader, BufferedReader, InputStreamReader, PrintWriter, Scanner's underlying channel — is a subclass of one of these four, inheriting the single-method read()/write() contract and adding device or buffering specifics.

Two orthogonal classifications — and the same idea beyond files

By direction (the only runtime classification):

• Reader or input stream — data flows into primary memory. Used to read from keyboard, file, or network socket. Concrete examples you have met: reading from keyboard with Scanner over System.in (System.in itself is an InputStream), reading from a file with BufferedReader wrapping FileReader, reading from a network socket with socket.getInputStream() wrapped in InputStreamReader + BufferedReader.
• Writer or output stream — data flows out of primary memory to a device. Used to write to monitor, file, or network socket. Examples: printing to the screen with System.out.println (System.out is a PrintStream — a byte output stream), writing to a file with PrintWriter over FileOutputStream.

A helpful complementarity to memorize:

In file and network code you build the analogous file streams (FileReader, FileInputStream, FileOutputStream) and wrap them with higher helpers (BufferedReader, Scanner, PrintWriter) to gain buffering, line methods, or formatted printing.

By data unit (design choice for new code):

• Byte stream (InputStream/OutputStream family) — handles raw bytes. Use when working with binary data, images, serialized objects, or when you need the exact bytes.
• Character stream (Reader/Writer family) — handles Unicode characters, translating bytes ↔ chars via a Charset. Use when working with text, strings, and internationalized output; often more efficient and correct for textual data.

Visual intuition: Draw two pipes side by side. The byte pipe is narrow and carries raw balls (bytes); the character pipe is wider and carries labelled envelopes (chars) — but under the glass the envelope pipeline still moves balls and repackages them. That repackaging is InputStreamReader / OutputStreamWriter.

Why the abstraction matters: Because the same Reader/Writer methods apply irrespective of source, you can write business logic once against the Reader interface and reuse it for console input, file reading, and socket reading — swapping only the construction line. Frameworks for web servers, ETL ingestion, and file transfer exploit exactly this substitution.

Formalize — what BufferedReader is and where it lives

BufferedReader is a classic character-input class in java.io for efficient, buffered reading. It belongs to the Reader hierarchy (character stream) and wraps another Reader to add two things: (1) an in-memory buffer, and (2) convenient line and navigation methods. Although newer APIs (Scanner, java.nio.file.Files.readAllLines, BufferedReader over java.nio channels) now exist, BufferedReader remains widely used because of its simplicity and precise control over mark/reset/skip.

• Location: java.io.BufferedReader — so import java.io.BufferedReader; (and import java.io.FileReader; / import java.io.InputStreamReader; for the inner source) is required.
• Construction pattern: outer buffered wrapper + inner source reader that already knows the device.

Formalize — PrintWriter as the text-file writing screen

PrintWriter is the character-based screen class in java.io for writing human-readable text to a file (or to any OutputStream). While BufferedReader is the preferred class for traditional reading, PrintWriter is the preferred class for writing lines to files because it mirrors the familiar System.out API: print(...), println(...), printf(...)/format(...).

Relationship to System.out:

• System.out is a PrintStream (a byte stream) connected to the monitor, available globally as System.out.
• PrintWriter wrapping a FileOutputStream is the analogous screen connected to a text file: PrintWriter p1 = new PrintWriter(new FileOutputStream("a.txt")); makes p1.println("hi") write "hi" plus newline to a.txt just as System.out.println("hi") writes to the screen.

A PrintWriter gives you formatting for free: p1.println(42), p1.printf("score %d", 95), p1.print(true) all work because overloads call String.valueOf / toString internally.

All file I-O classes including BufferedReader, PrintWriter, FileInputStream, FileOutputStream live in java.io. They are not implicitly imported; you must import them:

import java.io.PrintWriter;
import java.io.FileOutputStream;
import java.io.FileNotFoundException;

The first brings the writer, the second the file-connecting bridge (explained in 19.8.2), the third the exception type thrown when the file cannot be created or found.

The two-piece bridge — because PrintWriter has no direct file-name constructor in the form taught here

Unlike some readers where you can pass a file name directly to FileReader("name.txt"), the PrintWriter construction taught in this lecture has no single-argument file-name constructor. It needs a stream object that already points to the file. FileOutputStream does exactly that job: it converts a file-name string into a byte stream object that points to that file, handling OS-level opening/creation. Then PrintWriter wraps that byte stream and adds character-mode print/println.

Canonical syntax in this course:

PrintWriter outputStream = new PrintWriter(new FileOutputStream("stuff.txt"));

Breakdown:

• new FileOutputStream("stuff.txt") — takes the String file name, asks the OS to open or create stuff.txt, returns an anonymous FileOutputStream (a byte OutputStream) aimed at that file. Can throw FileNotFoundException if the path is invalid (for example a non-existent directory with no permission to create).
• new PrintWriter(...) — takes that anonymous OutputStream and wraps it. Inside it builds an OutputStreamWriter (bytes→chars) automatically. The name outputStream (of type PrintWriter) is now connected to stuff.txt through the two-layer pipe:

"stuff.txt" (disk) ← FileOutputStream (bytes) ← PrintWriter (chars + formatting) ← your code: outputStream.println(...)

Modern convenience note: The standard library now also offers new PrintWriter(String fileName) and new PrintWriter(File file) that internally create the FileOutputStream for you. The two-step form is kept in this course because it makes the bridge explicit and matches the exam's expected answer. Either form is correct in production when you control the JDK.

What an exception is in the file context

An exception is a runtime error that causes abnormal termination if not handled. The program compiles without error, but at runtime a problem arises that interrupts normal control flow. File-specific triggers include:

• Arithmetic: int x = 5/0; → ArithmeticException.
• User data: parsing "abc" as int → InputMismatchException/NumberFormatException.
• File: new FileOutputStream("::illegal") or a missing parent directory → FileNotFoundException; trying to read a file that was deleted between exists() and open() → FileNotFoundException; I/O failure mid-stream → broader IOException.

FileNotFoundException is a subclass of IOException. Because a file is a separate entity outside the program, it may be missing or unreachable precisely when you try to open it, so the compiler requires you to either handle or declare the exception.

The required handling pattern — declare outside, open inside try:

PrintWriter outputStream = null; // ① declared outside so visible in try, catch, and after
try {
    outputStream = new PrintWriter(new FileOutputStream("stuff.txt")); // ② open attempt
} catch (FileNotFoundException e) {
    System.err.println("Error opening the file stuff.txt"); // ③ handler
    // optionally: System.exit(0); or return; or rethrow
}
// ④ only after success do you write
if (outputStream != null) {
    outputStream.println("The quick brown fox");
}

Why each piece matters:

• Declare null outside try. If you write try { PrintWriter outputStream = new PrintWriter(...); } then outputStream is scoped only inside try and cannot be used to write after it. Declaring outside keeps it visible to the write and close statements.
• Inside try initialize. This is the faulting point. On success the link is made. On failure control jumps immediately to catch without executing remaining try lines.
• catch (FileNotFoundException e). Catches the specific open-failure. A common real variant catches IOException e to also handle generic I/O problems; both are acceptable as long as FileNotFoundException is covered. Report to System.err (conventional for errors) or System.out; the lecture accepts either but System.err signals intent.
• Program continues instead of crashing. Without the try/catch, the JVM would print a stack trace and terminate. With it you choose recovery: print a message, create an alternate file, or exit gracefully with System.exit(0) as the demo does.

Modern alternative: try (PrintWriter outputStream = new PrintWriter(new FileOutputStream("stuff.txt"))) { ... } — try-with-resources (Java 7+) declares, opens, and auto-closes in one line; it implicitly requires AutoCloseable (which PrintWriter implements). The demo keeps the classic form because the single-point-of-closure discipline is an exam focus.

Formalize — swapping the source screen

The Scanner pattern for the keyboard wraps System.in:

Scanner sc = new Scanner(System.in); // keyboard line

The same Scanner can read from a text file by swapping that screen for a file byte stream built from the file name via FileInputStream:

Scanner inputStream = new Scanner(new FileInputStream("morestuff.txt"));

Breakdown:

• new FileInputStream("morestuff.txt") — byte InputStream that opens morestuff.txt for reading (throws FileNotFoundException if the file is absent or unreadable). This is the file analogue of System.in — a byte source.
• new Scanner(...) — wraps whatever InputStream you give it with decoding + tokenization. The Scanner constructor accepts any InputStream, any File, any Path, or a String source. Here the source happens to be a file stream.
• inputStream — the Scanner object name, now linked through that screen to the file rather than the keyboard. After this association, any Scanner method (next(), nextInt(), nextLine(), next().charAt(0), nextFloat()) pulls from morestuff.txt.

You still need imports, and note the packages:

import java.util.Scanner;              // java.util — the translator
import java.io.FileInputStream;        // java.io — the file byte pipe
import java.io.FileNotFoundException;  // java.io — checked exception on open

Alternative convenience form: new Scanner(new File("morestuff.txt")) or new Scanner(Paths.get("morestuff.txt")) internally opens the same file input stream. The new FileInputStream form is taught in this course because it makes the byte-stream bridge explicit, matching the PrintWriter/FileOutputStream pair in 19.8. For character-set control you might instead write new Scanner(new FileInputStream("morestuff.txt"), "UTF-8").

Unified stream picture:

keyboard:   Scanner(InputStream = System.in)               → nextInt/nextLine
file:       Scanner(InputStream = new FileInputStream(f))   → same nextInt/nextLine
socket:     Scanner(InputStream = socket.getInputStream())  → same nextInt/nextLine

One API, three cables.