Java HttpURLConnection | W3Docs Learn Java

HttpURLConnection est la sous-classe de URLConnection adaptée à HTTP. Lorsque vous appelez openConnection() sur une URL http: ou https:, l'objet retourné est un HttpURLConnection — effectuez un cast pour accéder aux fonctionnalités HTTP spécifiques : définir la méthode de requête, lire le code de statut et accéder au flux d'erreur séparé. Il s'agit du client HTTP d'origine du JDK, disponible depuis Java 1.1.

Ce chapitre traite du cast de la connexion et du choix d'une méthode, de l'envoi d'un corps de requête, du code de statut et des deux flux de réponse (le piège classique du flux d'erreur), ainsi qu'un exemple complet de requête POST que vous pouvez exécuter.

Note moderne : pour tout nouveau code, préférez java.net.http.HttpClient — il est plus propre, supporte HTTP/2 et gère l'asynchrone. HttpURLConnection est encore très présent dans les bases de code plus anciennes, il vaut donc la peine d'être bien maîtrisé.

Cast et choix d'une méthode

URL url = URI.create("http://example.com/api").toURL();
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");                       // GET is the default
conn.setRequestProperty("Content-Type", "application/json");
conn.setConnectTimeout(2000);
conn.setReadTimeout(2000);

setRequestMethod accepte "GET", "POST", "PUT", "DELETE", etc. Ajoutez des en-têtes de requête avec setRequestProperty.

Envoyer un corps de requête

Pour envoyer un corps, vous devez activer cette option avec setDoOutput(true) (ce qui fait également passer la méthode par défaut à POST), puis écrire dans le flux de sortie :

conn.setDoOutput(true);
try (OutputStream os = conn.getOutputStream()) {
    os.write(payload.getBytes(StandardCharsets.UTF_8));
}

Code de statut et les deux flux

La fonctionnalité HTTP déterminante est le code de statut, et le piège qui en découle :

int code = conn.getResponseCode();          // triggers the request
InputStream body = (code >= 200 && code < 400)
        ? conn.getInputStream()             // success body
        : conn.getErrorStream();            // error body (4xx/5xx)

getInputStream() lève une IOException pour une réponse 4xx/5xx. Le corps d'erreur se trouve sur un flux différent, getErrorStream(). Oublier cela est le bug classique de HttpURLConnection : une réponse d'erreur provoque une exception au lieu de vous permettre de lire l'explication du serveur. Commencez toujours par appeler getResponseCode(). Terminez avec conn.disconnect().

Exemple concret : un aller-retour POST

Ce programme lance un serveur loopback qui renvoie le corps de la requête avec un 201 Created, puis effectue un POST via HttpURLConnection : définition de la méthode, écriture d'un corps, lecture du statut et choix du bon flux.

java— editable, runs on the server

import com.sun.net.httpserver.HttpServer;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.InetSocketAddress;
import java.net.URI;
import java.net.URL;
import java.nio.charset.StandardCharsets;

public class HttpUrlConnectionDemo {
  public static void main(String[] args) throws Exception {
    HttpServer server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
    server.createContext("/echo", ex -> {
      String received = new String(
          ex.getRequestBody().readAllBytes(), StandardCharsets.UTF_8);
      byte[] body = ("you sent: " + received).getBytes(StandardCharsets.UTF_8);
      ex.sendResponseHeaders(201, body.length);   // 201 Created
      try (OutputStream os = ex.getResponseBody()) { os.write(body); }
    });
    server.start();
    int port = server.getAddress().getPort();

URL url = URI.create("http://127.0.0.1:" + port + "/echo").toURL();
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    conn.setRequestMethod("POST");
    conn.setRequestProperty("Content-Type", "text/plain");
    conn.setConnectTimeout(2000);
    conn.setReadTimeout(2000);
    conn.setDoOutput(true);                         // we will send a body

try (OutputStream os = conn.getOutputStream()) {
      os.write("hello server".getBytes(StandardCharsets.UTF_8));
    }

int code = conn.getResponseCode();
    System.out.println("status: " + code + " " + conn.getResponseMessage());

// Success bodies and error bodies are on DIFFERENT streams
    InputStream stream = (code >= 200 && code < 400)
        ? conn.getInputStream()
        : conn.getErrorStream();
    try (BufferedReader r = new BufferedReader(
            new InputStreamReader(stream, StandardCharsets.UTF_8))) {
      r.lines().forEach(l -> System.out.println("body  : " + l));
    }

conn.disconnect();
    server.stop(0);
  }
}

Ce qu'il faut retenir de cet exemple :

Caster le URLConnection en HttpURLConnection a débloqué la couche HTTP : setRequestMethod("POST"), getResponseCode() et getResponseMessage() n'existent que sur la sous-classe. Pour une URL http:, l'objet est réellement un HttpURLConnection, donc le cast réussit toujours.
Envoyer un corps a nécessité setDoOutput(true) avant d'écrire dans getOutputStream(). Sans cet appel, la connexion reste en lecture seule et l'écriture échoue — activer la sortie est le commutateur qui transforme un GET en une requête avec corps.
getResponseCode() a retourné 201 et c'est lui qui a effectivement déclenché la requête vers le serveur. Le code de statut est la première chose à lire, car la décision suivante — quel flux lire — en dépend.
L'exemple a bifurqué entre getInputStream() et getErrorStream(). Ici 201 est un succès, donc le flux d'entrée portait le corps renvoyé, mais pour une réponse 4xx/5xx getInputStream() aurait levé une exception et le message du serveur n'aurait été accessible qu'à travers getErrorStream(). Cette bifurcation est l'angle le plus tranchant de l'API.
Le flux a nécessité plus de cinq appels de configuration pour un seul POST, et disconnect() pour le nettoyage. Cette verbosité — flux manuels, piège du flux d'erreur, pas d'async intégré — est exactement la raison pour laquelle HttpClient existe.

Quand utiliser HttpURLConnection

Optez pour HttpURLConnection lorsque vous êtes sur un ancien JDK (avant Java 11), lorsqu'une bibliothèque ou une base de code l'utilise déjà comme standard, ou lorsque vous souhaitez éviter toute dépendance supplémentaire pour un seul appel simple. Pour tout ce qui est nouveau et non trivial — réutilisation des connexions, HTTP/2, async ou des objets requête/réponse plus propres — préférez le moderne HttpClient. Si vous avez seulement besoin de lire depuis une URL sans contrôle HTTP spécifique, les classes URL et URLConnection suffisent.

Pratique

Un client effectue un PUT avec 'HttpURLConnection'. Lorsque le serveur retourne '400 Bad Request', le code plante avec une 'IOException' sur 'conn.getInputStream()' au lieu de journaliser le message d'erreur du serveur. Quelle est la correction appropriée ?

Vérifier d'abord 'getResponseCode()' ; pour les réponses 4xx/5xx, lire le corps depuis 'getErrorStream()' plutôt que 'getInputStream()', qui lève une exception pour les statuts d'erreurEnvelopper 'getInputStream()' dans une boucle de tentatives, puisqu'un 400 est une erreur réseau transitoire qui réussit généralement au deuxième essaiAppeler 'setDoInput(false)' pour que les réponses d'erreur soient ignorées et qu'aucune exception ne soit levéeChanger la méthode de requête en GET, car 'HttpURLConnection' ne peut pas lire les corps de réponse pour les requêtes PUT