Concepts avancés de Jakarta RESTful Web Services

Université de Toulon

LIS UMR CNRS 7020

2025-02-25

Git Repository Status

Category	Details
🌿 Current Branch	`develop`
📝 Latest Commit	`b798c84` (2024-10-03 15:16:24)
🔗 Remote	git@github.com:ebpro/notebook-java-restfulws.git
🏷️ Latest Tag	`No tags`

☕ Java Development Environment

Component	Details
☕ Java Runtime	`21.0.6` (openjdk)
🎯 Maven	`3.9.9`

Les exemples suivants sont accessibles dans le dépôt :

Source: ebpro/notebook-java-rest-sample-jakartarestfull
Branch: develop
Latest Commit: dbac38c (fix maven wrapper exec bit, 2025-02-24)
Cloned to: ${SRC_DIR}=/home/jovyan/work/materials/github/ebpro/notebook-java-rest-sample-jakartarestfull

To get it:

git clone -b develop https://github.com/ebpro/notebook-java-rest-sample-jakartarestfull

Les liens sémantiques

Les liens sémantiques entre les resources peuvent être réprésentés à l’aide d’URLs de façon standard ((RFC8288)[https://tools.ietf.org/html/rfc8288]). Une liste complète est données sur le site de l’IANA : https://www.iana.org/assignments/link-relations/link-relations.xhtml. Les plus classiquement utilisé avec REST sont self, first, previous, next et last. Pour simplifier l’usage de l’API ces liens peuvent être fournis dans l’entête d’une réponse http et/ou dans le corps de la réponse (par exemple lors de la pagination).

Link: <http://MyServer:8080/MyApp/Persons/1>; rel="first-person", <http://MyServer:8080/MyApp/Persons/10>; rel="next-person", <http://MyServer:8080/MyApp/Persons/8>; rel="previous-person", <http://MyServer:8080/MyApp/Persons/90>; rel="last-person"

Etendre JAX-RS avec les Providers

D’une façon générale une classe annotée par @Provider ajoute des fonctions à JAXRS (traitement des exceptions, conversion des données, …).

Les mappers : application aux exceptions

Le traitement des exceptions peut être simplifié en utilisant des mappers (cf. package exceptions et mapper) qui s’appliquent automatiquement lors qu’une exception est émise. Dans ce cas un objet Response est construit manuellement pour contrôler le détail du corps et de l’entête.

@XmlRootElement
public class NotFoundException extends BusinessException {
    public NotFoundException() {
        super(Response.Status.NOT_FOUND);
    }
}

@SuppressWarnings("unused")
@Provider
@FieldDefaults(level = AccessLevel.PRIVATE)
@Log
public class BusinessExceptionMapper implements ExceptionMapper<BusinessException> {
    public Response toResponse(BusinessException ex) {
        return Response.status(ex.getStatus())
                .entity(ex)
                .build();
    }
}

If a resource doesn’t exist an exception is raised, and the 404 http status code is returned

. . .

Les filtres : application au statut et à la pagination

@Provider
public class StatusFilter implements ContainerResponseFilter {

    @Override
    public void filter(ContainerRequestContext containerRequestContext, ContainerResponseContext containerResponseContext) {
        if (containerResponseContext.getStatus() == Response.Status.OK.getStatusCode()) {
            for (Annotation annotation : containerResponseContext.getEntityAnnotations()) {
                if (annotation instanceof Status) {
                    containerResponseContext.setStatus(((Status) annotation).value());
                    break;
                }
            }
        }
    }

}

Un exemple de filtre appliqué à la requête sera donné dans la partie sur la sécurité.

Schéma d’une API REST

WSDL un autre langage de service Web permet de décrire un tel schéma.
Le langage WADL est spécifique à REST.
Par défaut Jersey génére une description WADL /application.wadl
Cependant, pour cela l’application nécessite une implantation du standard pour traiter les documents XML appelé JAXB qui n’est plus fournie en standard dans le JDK depuis la version 8 (nous utilisons ici la version 15).

Si JAXB est dans le classpath (cf. pom.xml) la génération d’une description WADL est automatique.

https://jakarta.ee/specifications/restful-ws/3.0/jakarta-restful-ws-spec-3.0.html#context