6. Notion de requête

Ces deux interfaces modélisent une requête HTTP. Elles exposent donc des méthodes qui permettent d'accéder à l'ensemble des paramètres, en-têtes, et plus généralement au contenu d'une telle requête.

6.1. Accès aux paramètres d'une requête

Une requête HTTP peut porter un certain nombre de paramètres. Dans le cas d'une requête de type GET ces paramètres sont codés sur l'URL de requête. Dans le cas d'une requête de type POST, il se trouvent dans le flux HTTP. Dans tous les cas, l'API servlet décode ces paramètres, et les expose au travers de quatre méthodes :

getParameterNames() : retourne l'ensemble des noms de paramètres disponibles sur la requêtes, sous forme d'une Enumeration.
getParameter(String) : retourne la valeur du paramètre dont on a donné le nom, s'il existe.
getParameteValues(String) : retourne l'ensemble des valeurs associées au paramètre dont on a donné le nom, sous forme d'un tableau de String.
getParameterMap() : retourne une Map dont les clés sont les noms des paramètres, et les valeurs celles des paramètres associés.

Notons que les valeurs des paramètres sont toujours de type String, tout simplement parce que c'est le type utilisé dans l'en-tête HTTP. Il appartient donc à l'application de convertir ces chaînes de caractères dans les bons types.

6.2. Accès aux éléments de l'en-tête HTTP

Plusieurs méthodes permettent d'accéder aux éléments de l'en-tête.

getHeaderNames(): retourne les noms des paramètres d'en-tête déclarés dans cette requête, sous forme d'une Enumeration.
getHeader(String), getIntHeader(String) et getDateHeader(String) : retournent la valeur du paramètre de l'en-tête dont on donne le nom, sous forme d'une String, d'un int ou d'une Date respectivement.
getHeaders() : retourne l'ensemble des noms des éléments de l'en-tête HTTP disponibles dans cette requête, sous forme d'une Enumeration.
getMethod() : retourne le nom de la méthode HTTP utilisée pour cette requête ( GET, POST, etc...).
getCharacterEncoding() : retourne l'encodage utilisé pour cette requête. Par défaut l'encodage utilisé par HTTP est ISO-8859-1, mais les autres encodages, notamment l'UTF-8 peut aussi être utilisé. Notons qu'il existe une méthode setCharacterEncoding() qui permet de forcer l'encodage. Elle doit obligatoirement être appelée avant tout accès au contenu de la requête HTTP.
getLocale() et getLocales() retournent le contenu de l'élément d'en-tête Accept-Language, qui indique la locale par défaut supportée par le navigateur. C'est à partir de ce paramètre qu'une application peut décider d'envoyer des pages en français ou en anglais par exemple.
getContentType() et getContentLength() permettent d'accèder au type MIME du contenu de la requête, et au nombre d'octets qui la composent.
getInputStream() retourne un flux binaire de type ServletInputStream sur la requête directement, qu'il est donc possible de traiter sans passer par toutes ces méthodes.

6.3. Accès aux éléments de l'URL

Les éléments de l'URL d'accès à la ressource que nous sommes en train de traiter sont exposés au travers de trois variables : contextPath, servletPath et pathInfo. Ces trois variables sont accessibles via leurs getters standards. De plus, deux variables sont disponibles : requestURI et requestURL.

getRequestURI() : URI de la requête, c'est-à-dire ce qui se trouve entre le groupe {nom du protocole, nom du serveur, port} et les paramètres de la requête.
getRequestURL() : retourne l'URL complète de la requête. Notons que le type de retour est StringBuffer, ce qui permet de modifier cette URL facilement et efficacement.
getContextPath() : retourne le chemin sous lequel se trouve l'application web dans laquelle se trouve cette servlet. Il correspond à l'attribut path de l'élément Context du fichier context.xml de cette application web, dans le cas de Tomcat. Si la valeur de path vaut /, alors le contextPath est vide.
getServletPath() : retourne le chemin sous lequel se trouve cette ressource, sous le chemin de l'application web. Cette valeur correspond à l'élément servlet-mapping du fichier web.xml de cette application web. Si servlet-mapping vaut / alors servletPath est vide.
getPathInfo() : retourne ce qui reste à retourner. Dans le cas d'une servlet, pathInfo est vide. Dans le cas d'une ressource statique (une image, ou une page HTML), pathInfo correspond au nom de cette ressource.

Chacune de ces trois variables, si elle n'est pas vide, commence toujours par le caractère /. Notons qu'une page JSP est une servlet, que son servletPath porte le nom de cette page et que son pathInfo est vide. Notons enfin que l'on a toujours :

    requestURI = contextPath + servletPath + pathInfo

6.4. Accès aux paramètres du client

Trois méthodes nous permettent d'accéder aux paramètres du client qui fait la requête :

getRemoteHost() : nous fournit le nom complet du client. Plus précisément, il s'agit du nom du dernier proxy utilisé si ce client fait sa requête au travers d'un proxy.
getRemoteAddr() : même méthode que la précédente, sauf qu'elle retourne l'adresse IP du client.
getRemotePort() : même méthode que la précédente, nous retourne le port du client.

6.5. Accès aux informations de sécurité

Tous les serveurs de servlets exposent un mécanisme d'authentification standard, qui permet de fixer l'identité d'un utilisateur. La configuration de la sécurité associe les utilisateurs à des rôles, et c'est à ces rôles que le serveur donne des droits et impose des restrictions. La requête expose deux méthodes permettant d'accéder à des informations sur les rôles que possède un utilisateur authentifié :

getUserPrincipal() : retourne un objet Principal qui encapsule le nom de l'utilisateur authentifié.
isUserInRole(String) : retourne true si l'utilisateur authentifié qui est à l'origine de cette requête est déclaré dans le rôle passé en paramètre.

6.6. Accès à la session, au contexte et aux informations d'initialisation

Une méthode permet d'accéder à la session HTTP dans laquelle cette requête se place.

getSession() : retourne un objet de type HttpSession, détaillé dans la suite de ce chapitre. Notons que l'appel à cette méthode crée une session s'il n'en existe pas déjà une, ce qui est en général indésirable. La même méthode existe dans une seconde version, qui prend un booléen en paramètre. Si ce booléen est false, alors aucune session n'est créée. Dans ce cas la méthode retourne null.
getServletContext() : retourne un objet de type ServletContext, qui modèlise l'application web.
getServletConfig() : retourne un objet de type ServletConfig, qui encapsule les paramètres d'initialisation de la servlet. Cet objet expose deux méthodes : getInitParameterNames() et getInitParameter(String), qui permettent d'accèder aux noms des paramètres d'initialisation d'une part, et aux valeurs associées d'autre part.