الحزم والمجلدات

Written Explanation

What a package is

A package is a named group of related classes and interfaces. It does two jobs:

1. Organization. Related classes are kept together, like papers in one drawer.
2. A separate name space. The Java Language Specification explains that each package has its own namespace, so two packages can each contain a class with the same simple name. Its own example is java.util.Vector next to a different class also called Vector in another package.

A class's fully qualified name is its package name, a dot, and its simple name. For a class Account in package com.example.bank, the full name is com.example.bank.Account. Account alone is the simple name.

The package statement

The first line of a source file (ignoring comments and blank lines) declares which package the class belongs to:

package com.example.bank;

public class Account { }

Rules:

• The package line comes before any import lines and before the class. The JLS says a package declaration, when present, comes first in the compilation unit.
• There is at most one package line per file, and it ends with a semicolon.
• Every class in a file belongs to the package named in that file.

Package name to folder path

Java source layout follows a simple rule: each dot in the package name is a folder separator. The Java Language Specification describes this for file-system based storage: a package jag.scrabble.board is held in the directories jag/scrabble/board/.

The folder where the package tree begins is called the source root. A package line always describes the path from the source root, never the full path on your disk. If your project is in C:\work\bank-demo\src, then src is the source root and the file Account.java for package com.example.bank belongs in src\com\example\bank\.

Naming conventions

The Oracle Java tutorial gives these conventions:

• Package names are all lowercase, so they never look like class names.
• Companies start with their reversed internet domain: a programmer at example.com names a package com.example.something. This keeps two organizations' packages from clashing.
• Within one company or project, add a further part after the domain, such as com.example.bank.
• Names beginning with java. or javax. belong to the Java platform itself. Do not use them.

If a domain is not a legal Java name (for example it contains a hyphen), the tutorial suggests replacing the hyphen with an underscore, so hyphenated-name.example.org becomes org.example.hyphenated_name.

For the lessons in this module we use the invented domain example.com, so our packages begin with com.example. In your own projects use a domain you control, or a clearly personal name.

The folder tree does not create packages by itself

A folder is not a package until a file inside it says so. Both must agree: the package line and the folder. If they disagree, tools stop finding your classes. That mismatch is the number-one beginner error with packages, and Example 3 shows it.

The default (unnamed) package

If a file has no package line, its classes belong to the unnamed package, usually called the default package. The JLS says the unnamed package is meant for small or temporary programs. It has a serious limit: types in the unnamed package cannot be imported by code that is in a named package. So the moment your project grows, classes in the default package cannot be used from properly organized code.

That is why "one giant default package" is the common mistake listed for this module. You may keep using it for a five-line experiment, but a project you intend to keep should have named packages from its first day.

Compiling and running with packages

You compile from the source root and tell the compiler where to put the .class files with -d. According to Oracle's javac documentation, -d sets the output directory, and the compiler places each class in a sub-folder that matches its package, creating folders as needed.

javac -d out src/com/example/bank/Account.java src/com/example/app/Main.java
java -cp out com.example.app.Main

Two things to notice:

• You run a class by its fully qualified name (com.example.app.Main), not by its file name. -cp out tells the JVM where the compiled package folders start.
• Oracle's documentation also describes -sourcepath, which tells javac where to look for other source files it needs. With javac -d out -sourcepath src src/com/example/app/Main.java you name only Main, and the compiler finds Account by itself.

(The commands above use forward slashes, which work in most Windows terminals as well. Exact terminal behavior can vary, so adjust to your shell. An IDE does all of this for you, but its menus and wording differ between products and versions, so follow your IDE's own help for "new package".)