Modifier le fichier

Objectif

Cette documentation explique, pas à pas, comment obtenir et utiliser une classe héritant de AbstractControllerUrlBuilder pour construire des URLs d’endpoints de vos controllers (Spring MVC) dans une extension Kosmos.

Rappels des classes en jeu

  • AbstractControllerUrlBuilder (base commune):
    • Résout la base d’URL du DispatcherServlet de l’extension via le bean ControllerUrlResolver.
    • Expose 3 surcharges de buildUrl(...) pour composer l’URL finale à partir d’un chemin relatif, de variables de chemin et/ou de paramètres de requête.
  • CoreControllerUrlBuilder: implémentation prête à l’emploi pour le “core” (contexte par défaut).
  • DemarcheControllerUrlBuilder: implémentation pour l’extension Démarche.
  • ControllerUrlResolver: préfixe vos chemins relatifs par l’URL de base du DispatcherServlet de l’extension. Peut renvoyer une chaîne vide si la servlet dédiée est désactivée.

Emplacements utiles:

  • koreparent/webapp-front/src/main/java/com/kosmos/common/AbstractControllerUrlBuilder.java
  • koreparent/webapp-front/src/main/java/com/kosmos/common/CoreControllerUrlBuilder.java
  • demarche/demarche-webapp-front/src/main/java/com/kosmos/demarche/DemarcheControllerUrlBuilder.java
  • koreparent/core/src/main/java/com/kosmos/controllers/ControllerUrlResolver.java

Quand utiliser un ControllerUrlBuilder ?

Utilisez un UrlBuilder dès que vous devez créer un lien vers un endpoint de controller d’une extension. Il garantit le bon préfixe (base URL de la DispatcherServlet de l’extension) et gère proprement:

  • les segments variables ({id}, {slug}, …),
  • les paramètres de requête (?page=1&size=20),
  • les cas où l’extension est désactivée (URL vide).

Obtenir une instance (Core et Démarche)

  • Core: Récupérer (ApplicationContextManager.getBean()) / injecter le bean coreControllerUrlBuilder dans vos beans.

  • Démarche: Récupérer (ApplicationContextManager.getBean()) / injecter le bean demarcheControllerUrlBuilder dans vos beans.

Construire des URLs: les 3 surcharges de buildUrl

AbstractControllerUrlBuilder expose:

  1. buildUrl(String path)
String url = urls.buildUrl("/users");
// -> "/<base-dispatcher>/users" (préfixée par l’extension)
  1. buildUrl(String path, Map<String, String> variables)
  • Pour les chemins contenant des variables {...}.
Map<String, String> vars = Map.of("userId", "42");
String url = urls.buildUrl("/users/{userId}", vars);
// -> "/<base-dispatcher>/users/42"
  1. buildUrl(String path, MultiValueMap<String, String> queryParams)
  • Pour ajouter des paramètres de requête.
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;

MultiValueMap<String, String> qp = new LinkedMultiValueMap<>();
qp.add("page", "1");
qp.add("size", "20");
String url = urls.buildUrl("/users", qp);
// -> "/<base-dispatcher>/users?page=1&size=20"
  1. Complet: buildUrl(String path, MultiValueMap<String,String> queryParams, Map<String,String> variables)
  • Combine variables de chemin et query params.
MultiValueMap<String, String> qp = new LinkedMultiValueMap<>();
qp.add("include", "roles");

Map<String, String> vars = Map.of("userId", "42");
String url = urls.buildUrl("/users/{userId}", qp, vars);
// -> "/<base-dispatcher>/users/42?include=roles"

Sous le capot, la méthode:

UriComponentsBuilder.fromPath(path)
    .queryParams(queryParams)
    .buildAndExpand(variables)
    .toString();

assure l’expansion des variables et l’encodage correct.

Créer votre propre UrlBuilder pour une autre extension

Si votre extension « X » n’a pas encore son builder, créez une classe finale qui hérite de AbstractControllerUrlBuilder et passez l’ID d’extension à super(...).

package com.kosmos.x;

import com.kosmos.common.AbstractControllerUrlBuilder;

public final class XControllerUrlBuilder extends AbstractControllerUrlBuilder {
    public XControllerUrlBuilder() {
        super("x-extension-id"); // l’ID de contexte/extension tel que configuré
    }
}

Bonnes pratiques:

  • Faites référencer l’ID via une constante de config de l’extension (ex.: XConfig.ID_EXTENSION) plutôt qu’une chaîne en dur.
  • Gardez la classe final (utilitaire simple, non destinée à l’héritage).

Ensuite, usage identique:

XControllerUrlBuilder urls = new XControllerUrlBuilder();
String url = urls.buildUrl("/features/{featureId}", Map.of("featureId", "abc"));

Gestion des erreurs et cas limites

  • Bean manquant: si le bean ControllerUrlResolver n’est pas trouvé pour l’extension, une IllegalArgumentException est levée par AbstractControllerUrlBuilder.getUrlResolver(...).
  • Extension désactivée: ControllerUrlResolver peut renvoyer "" (vide). Tenez-en compte si vous affichez l’URL telle quelle dans une vue.
  • Variables non fournies: si path contient {var} mais que la clé manque dans variables, UriComponentsBuilder.buildAndExpand(...) lèvera une IllegalArgumentException.
  • Encodage: UriComponentsBuilder gère l’encodage des query params et des segments de chemin lors de la transformation en chaîne.