Java URLConnection

Une URL nomme une ressource ; une URLConnection est le lien actif que vous ouvrez pour la lire ou y écrire concrètement. Vous ne l'instanciez jamais directement — vous appelez url.openConnection(), et Java retourne un objet de connexion dont le type concret dépend du protocole (http:, https:, file:, jar:, …). URLConnection est la classe de base neutre vis-à-vis du protocole ; le chapitre HttpURLConnection couvre sa sous-classe spécifique à HTTP.

Cette page explique comment ouvrir une connexion, configurer les délais d'expiration, lire les en-têtes de réponse et le corps, et où s'arrête l'API neutre par rapport au travail spécifique à HTTP.

Ouverture et configuration

URL url = URI.create("http://example.com/data").toURL();
URLConnection conn = url.openConnection();   // not connected yet
conn.setConnectTimeout(2000);                // ms to establish the connection
conn.setReadTimeout(2000);                   // ms to wait for data
conn.connect();                              // optional; reading connects implicitly

openConnection() ne touche pas au réseau — il crée simplement un objet configurable. La connexion réelle s'effectue de façon paresseuse lorsque vous appelez connect() ou, plus couramment, lorsque vous lisez pour la première fois depuis getInputStream(). Définissez les délais d'expiration avant de vous connecter ; tous deux ont pour valeur par défaut 0, ce qui signifie « attendre indéfiniment », ce qui est rarement ce que vous souhaitez.

Lecture de la réponse

Deux types d'informations sont renvoyés : les en-têtes (métadonnées) et le corps (un flux d'entrée).

String type = conn.getContentType();      // e.g. "text/plain; charset=utf-8"
int length  = conn.getContentLength();    // -1 if the server did not send it
long when   = conn.getLastModified();

try (InputStream in = conn.getInputStream()) {
    // read the body bytes
}

Les accesseurs d'en-têtes comme getContentType() sont des raccourcis par rapport au getHeaderField("Name") général. Lisez toujours le corps via try-with-resources afin que le socket sous-jacent soit libéré.

Envoi de données

Pour envoyer un corps de requête, passez la connexion en mode sortie avec setDoOutput(true), puis écrivez dans getOutputStream(). Pour HTTP, cela implique un POST. Comme le contrôle de la méthode, du code de statut et du flux d'erreur nécessite un comportement spécifique à HTTP, ce travail appartient à HttpURLConnection.

Un exemple concret : lecture d'une ressource via une connexion

Ce programme sert un petit corps texte depuis un HttpServer en loopback, ouvre une URLConnection générique vers celui-ci, inspecte les en-têtes de réponse et diffuse le corps ligne par ligne — entièrement hors ligne.

Ce qu'il faut retenir de l'exécution :

• url.openConnection() a retourné une URLConnection sans se connecter ; le round-trip réseau n'a eu lieu que lors de l'appel à getInputStream(). Cette évaluation paresseuse explique pourquoi les délais d'expiration et les propriétés de requête doivent être définis en premier — une fois le corps lu, la connexion est déjà établie et ces paramètres sont verrouillés.
• Les accesseurs d'en-tête et le flux du corps sont deux canaux distincts. getContentType() et getContentLength() lisent les métadonnées de la réponse, tandis que getInputStream() lit la charge utile. Le serveur a défini Content-Type explicitement, et la connexion l'a exposé à la fois via l'accesseur typé et via le getHeaderField("Content-Type") générique.
• getContentLength() a retourné le nombre d'octets réel parce que le serveur a envoyé un en-tête Content-Length. Lorsqu'un serveur l'omet (réponses fragmentées), cela retourne -1 — le code qui pré-dimensionne un tampon à partir de cette valeur doit donc gérer le cas -1.
• Le corps a été lu via try-with-resources, garantissant que le socket est libéré même en cas d'exception. Laisser fuir les flux de connexion épuise le pool de connexions et finalement la limite de descripteurs de fichiers du système d'exploitation — la fermeture n'est pas optionnelle dans le code réseau.
• URLConnection est délibérément neutre vis-à-vis du protocole : rien ici ne mentionne les codes de statut HTTP ou les méthodes de requête. Lire le statut, choisir GET ou POST, et accéder au flux d'erreur nécessitent un cast vers HttpURLConnection, ce que fait le chapitre suivant.

Pratique