---

Packages en Java

Un package est un mécanisme d’organisation qui permet de :

• Regrouper des classes et interfaces liées logiquement.
• Éviter les conflits de noms (2 classes Client dans des packages différents).
• Contrôler l’accès aux classes (via les modificateurs public, protected, private, et package-private).
• Faciliter la réutilisation du code (ex. : java.util pour les collections).

Avantages des Packages

Avantage	Explication
Éviter les conflits de noms	Deux classes peuvent avoir le même nom si elles sont dans des packages différents (ex. : com.company.Client et org.other.Client).
Meilleure organisation	Les classes sont regroupées par fonctionnalité (ex. : java.io pour les E/S, java.net pour le réseau).
Contrôle d’accès	Les modificateurs d’accès (public, protected, package-private) limitent la visibilité des classes/méthodes.
Réutilisabilité	Les packages permettent d’importer et réutiliser des classes dans différents projets (ex. : java.util.ArrayList).
Sécurité	Les classes internes à un package ne sont pas accessibles depuis l’extérieur (sauf si public).

Syntaxe de Déclaration

Un package est déclaré en premier dans un fichier .java :

package nom.du.package;  // doit être la première instruction (hors commentaires)

public class MaClasse {
    // ...
}

Exemple :

package com.monprojet.model;

public class Client {
    // ...
}

Règles de Nommage

• Convention : Utiliser des noms en minuscules et séparés par des points (com.monprojet.utils).
• Structure : Les packages suivent souvent la hiérarchie des dossiers (com/monprojet/utils/ sur le disque).
• Unicité : Utiliser un domaine inversé pour éviter les conflits (com.google, org.apache),fr.formation.mer).

Types de Packages

Type	Description	Exemple
Packages intégrés	Fournis par Java (JDK).	java.lang (classes de base comme String), java.util (collections), java.io (E/S).
Packages utilisateur	Créés par les développeurs pour organiser leur code.	com.monprojet.model, org.monentreprise.utils.

Importation de Packages

Pour utiliser une classe d’un autre package, on utilise le mot-clé import :

import java.util.ArrayList;  // on importe une classe spécifique
import java.util.*;          // on importe toutes les classes du package (déconseillé pour la lisibilité)

import com.monprojet.model.Client;

public class Main {
    public static void main(String[] args) {
        Client client = new Client();  // Utilisation de la classe Client
    }
}

Accès aux Classes sans import

On peut utiliser le nom qualifié (avec le package) pour accéder à une classe sans import (mais c’est moins pratique):

com.monprojet.model.Client client = new com.monprojet.model.Client();

Cas d’usage : Éviter les conflits de noms (choisir entre java.util.Date et java.sql.Date) ou utiliser une classe ponctuellement.

Modificateurs d’Accès et Packages

Modificateur	Visibilité dans le même package	Visibilité hors du package	Exemple
public	✅ Oui	✅ Oui	public class MaClasse { ... }
protected	✅ Oui	✅ Oui (via héritage)	protected int monAttribut;
package-private (aucun modificateur)	✅ Oui	❌ Non	class MaClasse { ... } (visible uniquement dans le package).
private	❌ Non	❌ Non	private String secret; (visible uniquement dans la classe).

Création d’un Package

Déclarer le package dans le fichier .java :

package com.monprojet.model;
public class Client { ... }

• Organiser les fichiers dans une structure de dossiers correspondante :

src/
└── com/
    └── monprojet/
        └── model/
            └── Client.java

Compiler en incluant le chemin du package : javac -d . com/monprojet/model/Client.java

Bonnes Pratiques

Pratique	Explication
Utiliser des noms de packages uniques	Éviter les conflits avec des noms de domaine inversés (ex. : com.monentreprise).
Éviter import.*	Importer uniquement les classes nécessaires pour améliorer la lisibilité.
Organiser par fonctionnalité	Regrouper les classes liées (ex. : model, controller, utils).
Documenter les packages	Utiliser des commentaires package-info.java pour décrire le rôle du package.
Limiter la visibilité	Utiliser package-private (aucun modificateur) pour les classes/méthodes internes au package.

Exemple Complet

Structure du projet :

src/
└── com/
    └── monprojet/
        ├── model/
        │   ├── Client.java
        │   └── package-info.java
        └── utils/
            └── StringUtils.java

Fichier Client.java :

package com.monprojet.model;

public class Client {
    private String nom;
    private String email;

    public Client(String nom, String email) {
        this.nom = nom;
        this.email = email;
    }

    public String getNom() { return nom; }
    public String getEmail() { return email; }
}

Fichier Main.java (dans un autre package) :

import com.monprojet.model.Client;

public class Main {
    public static void main(String[] args) {
        Client client = new Client("Clara Lucciani", "clara@Lucciani.fr");
        System.out.println("Client: " + client.getNom());
    }
}

Résumé en 5 Points Clés

• Organisation : Les packages regroupent des classes par fonctionnalité.
• Éviter les conflits : Utiliser des noms uniques (ex. : com.monentreprise).
• Contrôle d’accès : Les modificateurs (public, protected, etc.) définissent la visibilité.
• Importation : import permet d’utiliser des classes d’autres packages.
• Structure physique : Les packages correspondent à des dossiers dans le système de fichiers.

Utilisation de package-info.java

Le fichier package-info.java est un fichier spécial en Java qui permet de documenter un package et de définir des annotations au niveau du package.

Il est utilisé pour :

• Ajouter une description du package (via des commentaires Javadoc).
• Appliquer des annotations à l’ensemble du package (@Deprecated, annotations personnalisées).

À quoi sert package-info.java ?

Fonctionnalité	Description	Exemple
Documentation du package	Ajouter une description du rôle du package via des commentaires Javadoc (/** ... */).	/** Ce package contient les modèles de données. */
Annotations au niveau du package	Appliquer des annotations à toutes les classes du package (ex. : @Deprecated).	@Deprecated package com.monprojet.old;

Syntaxe de package-info.java

• Pour la documentation

/**
 * Description du package.
 * Ce package contient les classes liées aux modèles de données.
 */
package com.monprojet.model;

Placement : Ce fichier doit être placé à la racine du package (com/monprojet/model/package-info.java).

Contenu : Uniquement une déclaration de package et des commentaires Javadoc.

Pour les annotations

@Deprecated
package com.monprojet.old;

import java.lang.annotation.*;  // Si des annotations personnalisées sont utilisées

Annotations courantes :

@Deprecated : Marque le package comme obsolète.
@SuppressWarnings : Ignore certains avertissements du compilateur pour tout le package.

Exemple Complet de structure

src/
└── com/
    └── monprojet/
        ├── model/
        │   ├── Client.java
        │   └── package-info.java  // fichier de documentation
        └── old/
            ├── AncienneClasse.java
            └── package-info.java  // fichier avec annotation @Deprecated

Fichier package-info.java pour la documentation :

/**
 * Package contenant les modèles de données de l'application.
 * Les classes de ce package représentent les entités métiers (ex. : Client, Produit).
 *
 * @since 1.0
 * @author PB
 */
package com.monprojet.model;

Fichier package-info.java pour les annotations :

/**
 * Ce package est obsolète et sera supprimé dans la version 2.0.
 * Utilisez plutôt `com.monprojet.newpackage`.
 */
@Deprecated(since = "1.5", forRemoval = true)
package com.monprojet.old;

Avantages de package-info.java

Fonctionnalité	Description	Exemple
Documentation du package	Ajouter une description du rôle du package via des commentaires Javadoc (/** ... */).	/** Ce package contient les modèles de données. */
Annotations au niveau du package	Appliquer des annotations à toutes les classes du package (@Deprecated).	@Deprecated package com.monprojet.old;

Quand Utiliser package-info.java ?

Avantage	Description
Documentation centralisée	Permet de documenter l’ensemble du package en un seul endroit (visible dans la Javadoc générée).
Annotations globales	Applique des annotations à toutes les classes du package (ex. : @Deprecated).
Lisibilité	Rend le code plus clair en expliquant le rôle du package.
Maintenabilité	Facilite la maintenance en regroupant les informations liées au package.

Génération de la Javadoc

Quand on génère la Javadoc avec la commande javadoc -d doc/ src/, le contenu de package-info.java apparaîtra en haut de la page du package dans la documentation générée.

Exemple de sortie Javadoc :

Package com.monprojet.model
Package contenant les modèles de données de l'application. Les classes de ce package représentent les entités métiers (ex. : Client, Produit).

Classes
Class	Description
Client	Représente un client.
Produit	Représente un produit.

Bonnes Pratiques

Pratique	Explication
Toujours documenter les packages publics	Ajoute un package-info.java pour les packages exposés en API.
Utiliser des annotations pertinentes	@Deprecated pour les packages obsolètes, @SuppressWarnings pour ignorer des avertissements.
Éviter les redondances	Ne pas répéter dans package-info.java ce qui est déjà documenté dans les classes.
Respecter les conventions	Utiliser des commentaires Javadoc clairs et concis.