Packages, Namespaces, and Class Imports in Java

The problem

Name collisions in a flat global scope

A namespace is a logical container that groups classes and interfaces to give them a unique context and prevent name collisions. Without namespaces, two Usuario classes or two Date classes compete for the same short name in a single flat global scope.

Global scope (no namespaces)

Usuario Usuario

Date Date

Collision: the compiler cannot tell which Usuario (or Date) class you mean.

Physical namespace

The folder must match the package line

Unlike other languages, Java enforces a strict rule: the namespace declared in package must match the directory path on the classpath exactly. Pick a file from the tree to see its required declaration.

Folder tree

com
- facundouferer
  - tienda
    - dominio
    - servicio

Required declaration package com.facundouferer.tienda.dominio; FQCN: com.facundouferer.tienda.dominio.Producto

Compiles: the package matches the folder tienda/dominio/ exactly.

Class identity

The FQCN is built piece by piece

To the JVM, Producto is only a local label. Its formal identity to the ClassLoader is the Fully Qualified Class Name (FQCN): reversed domain, project, layer and class, joined by dots.

com.facundouferer .tienda .dominio .Producto

Tap "Add next piece" to start building the FQCN.

Lexical alias

import does not load code: it registers an alias

The import statement is a lexical shortcut so you never have to type the FQCN each time. Java forbids importing two classes with the same short name in one file: try the three scenarios.

package com.facundouferer.tienda.servicio;

import java.util.Date;

public class AuditoriaServicio {
    private Date fechaOperacion = new Date();
}

Date→java.util.Date

Compiles: Date resolves unambiguously to the only import present.

package com.facundouferer.tienda.servicio;

import java.util.Date;
import java.sql.Date; // ← Date is already defined

java.sql.Date→collision with the previous import

Does not compile: 'Date is already defined in a single-type import'.

package com.facundouferer.tienda.servicio;

import java.util.Date; // Date sin calificar = java.util.Date

public class AuditoriaServicio {
    private Date fechaOperacion = new Date();
    private java.sql.Date fechaPersistenciaBD = new java.sql.Date(System.currentTimeMillis());
}

Date→java.util.Date

java.sql.Date→java.sql.Date (inline FQCN, no import)

Compiles: both Date classes coexist because one uses the short name and the other the explicit FQCN.

Namespace encapsulation

public vs package-private: trust boundaries

Namespaces are not just cosmetic folders: they are also visibility boundaries. The default modifier (package-private) restricts access strictly to classes in the same package. Pick a class and an access point to test it.

com.tienda.dominio

public class Producto

class ProductoValidator

com.tienda.dominio access point

Target class

Access origin

Access allowed: Producto is public, visible from any package.

Best practices

Core rules for package and namespace design

Five practical rules to keep your namespaces unique, readable and easy to navigate. Tap each rule to see a good and a bad example.