Dans l’article précédent, on a vu que c’était Play, votre serveur d’application qui allait intercepter les requêtes HTTP et les traiter grâce aux classes Java « Controller »:
Play – Fonctionnement général et cycle de vie d’une requête HTTP
Pour décider quel Controller va devoir être appelé, Play va analyser un fichier nommé « routes », placé dans le répertoire « /conf/ » de votre application. Celui-ci va contenir des règles de redirection avec une syntaxe très simple. Pour ce qui ont déjà vu des règles de configuration de firewall, vous n’allez pas être perdu.
Play encourage le développement d’applications « RESTful »
Vous allez le voir par la suite, Play essaie de profiter pleinement de HTTP et vous permet notamment d’utiliser les différents verbes HTTP . Chaque URL est définie par une URL (ex. /user/135) et un verbe HTTP (GET, POST, PUT, DELETE, HEAD).
Une application dite « RESTful » possède les caractéristiques suivantes:
- L’application est découpée en « ressources »
- Chaque ressource peut-être accédée par une URL
- Le serveur ne gère pas l’état du client (variables de session) = stateless
Play encourage le développement de telles applications, notamment grâce au mécanisme de routing. Ce type d’application a de nombreux avantages, comme:
- la possibilité de les mettre facilement sur plusieurs serveurs. Peu importe qui demande la ressource et quand il la demande, la ressource servie sera toujours la même
- la possibilité de mettre les ressources en cache (prévisible)
Syntaxe du fichier routes de Play! Framework
Le fichier « routes » est créé automatiquement lors de la création d’un nouveau projet Play. Celui-ci se trouve dans le dossier /conf/ de l’application.
Comme on l’a présenté plus tôt, chaque route est constituée de 3 éléments, dans cet ordre:
- Un verbe HTTP (GET, POST, PUT, DELETE, HEAD)
- Une URL (plutôt une URI en fait)
- Une référence vers une action d’un Controller (représentée par une de ses méthodes)
Voici un exemple:
GET /clients/{id} Clients.show
Pour ajouter un commentaire dans le fichier routes, ajoutez un « # » en début de ligne. Cela permet de documenter rapidement son API:
# Display a client
GET /clients/{id} Clients.show
Valeurs spéciales pour les verbes HTTP
Il existe deux valeurs spéciales qui peuvent remplacer les verbes HTTP:
- « ws » indique une requête WebSocket
- « * » est un joker, qui va être vérifié pour tout verbe HTTP
Valeurs et patterns pour les URI
De base, vous pouvez avoir des routes qui vont reconnaître qu’une URI exacte, comme:
/clients/list
Mais vous pouvez aussi indiquer que certaines parties de l’URL peuvent être dynamiques en les entourant d’accolades:
/clients/{id}
Cette règle va reconnaître les URI suivantes:
/clients/12121 /clients/toto
Vous pouvez avoir autant de parties dynamiques que vous le souhaitez:
/clients/{id}/accounts/{accountId}
Par défaut, Play va reconnaître tous les caractères jusqu’au prochain « / ». Mais vous pouvez aussi lui passer une expression régulière. Par exemple, la règle suivante ne va accepter que les id numériques:
/clients/{<[0-9]+>id}
Le nom du paramètres que vous placez entre accolades est important. En effet, il sera directement lié à la méthode de votre Controller.
Par défaut, l’URI /clients ne va pas fonctionner si vous entrez « /clients/ » avec un slash à la fin. Pour lui indiquer que vous voulez utiliser le slash de manière facultative, utilisez la syntaxe suivante:
GET /clients/? Clients.index
Valeur pour l’action Controller
La dernière partie de la route est la définition de l’action Controller à appeler. Vous devrez passer le nom d’une méthode public static void d’un des Controller de votre application. Un Controller dans le contexte de Play se trouve dans le dossier « /controllers/ » et hérite de play.mvc.Controller.
Par exemple pour la règle:
GET /clients/{id} Clients.show
La méthode static « show » de la classe Clients qui se trouve dans le package controllers sera appelée:
public static void show(String id) {
// code
}
Notez que dans cet exemple, la partie dynamique « {id} » sera automatiquement transmise à la méthode show du Controller.
Priorités entre les routes du fichier
Plusieurs routes peuvent être vérifiées pour une même requête. En cas de conflit, Play va utiliser la première route déclarée dans le fichier.
Par exemple si vous avez dans votre fichier:
GET /clients/all Clients.listAll
GET /clients/{id} Clients.show
Et que Play reçoit la requête « /clients/all », les deux règles vont être vérifiées. Mais comme /clients/all est déclarée en premier, c’est bien Clients.listAll qui sera appelé.
Ressources statiques
De base, une application Play contient un dossier « public » qui va contenir les éléments « statiques » de votre application (non-compilés) comme les JS / CSS / HTML ou tout autre fichier à servir. Pour cela, il existe une route spéciale:
GET /public/ staticDir:public
Vous pouvez aussi mapper directement un fichier à une URI:
GET /home staticFile:/public/html/index.html
Préciser le type MIME renvoyé
De base, Play va servir un fichier de type MIME HTML. Pour préciser le type MIME renvoyé, vous pouvez utilisé la notation (format:’TYPE_MIME’) en fin d’action:
GET /index.xml Application.index(format:'xml')
ou vous pouvez aussi extraire le format depuis l’URI:
GET /index.{format} Application.index