Modifications de comportement dans Servlet 3.1

L'implémentation Servlet 3.1 contient des modifications de comportement pouvant entraîner un comportement différent, voire un échec d'une application composée pour Servlet 3.0 lorsque vous utilisez la fonction Servlet 3.1.

Vous pouvez choisir une implémentation de la fonction Servlet 3.0 ou de la fonction Servlet 3.1 pour chaque instance, mais devez prendre en compte les différences de comportement. Si le comportement est inclus uniquement dans la fonction Servlet 3.1, vous devez utiliser cette-ci. Si les modifications de comportement de Servlet 3.1 ont un effet négatif sur une application existante, il est préférable dans ce cas d'utiliser Servlet 3.0 afin de conserver le comportement existant pour cette application. Il n'est pas possible d'utiliser en même temps les fonctions Servlet 3.0 et Servlet 3.1 sur le même serveur. La configuration des deux fonctions est une erreur. Si vous configurez les deux fonctions, aucune fonction de servlet n'est chargée.

Les modifications de comportement ont été introduites pour trois raisons :
  • Modifications requises par des clarifications dans la spécification Servlet 3.1.
  • Modifications requises dans l'implémentation de Servlet 3.1 pour passage du test TCK (Technology Compatibility Kit).
  • Modifications pour optimisation de l'implémentation du servlet.

Servlets, filtres et programmes d'écoute ajoutés à l'aide d'un programme

Une clarification de la spécification Servlet 3.1 interdit dorénavant à ServletContextListener de configurer à l'aide d'un programme des servlets, des filtres, ou des programmes d'écoute si ServletContextListener n'a pas été déclaré dans le fichier web.xml ou le fichier web-fragment.xml, ou n'a pas été annoté avec @WebListener. Par conséquent, tout appel à ServletContext pour effectuer une telle configuration par voie de programmation génère une exception UnsupportedOperationException.

Acheminement après démarrage de traitement asynchrone

Dans l'implémentation Servlet 3.0, une réponse est toujours fermée avant que la méthode forward de l'interface RequestDispatcher rende la main. Toutefois, en raison d'une clarification dans l'implémentation de Servlet 3.1, celle-ci ne ferme pas ou ne crée pas un vidage de la réponse avant que la méthode forward de l'interface RequestDispatcher ne rende la main, si la demande est placée en mode asynchrone. Cette modification peut affecter les applications 3.0 existantes, lesquelles ajoutent une sortie de la réponse à l'issue de la méthode vu que ces données de réponse sont maintenant envoyées, ce qui n'est pas le cas dans Servlet 3.0.

Conflits de masque d'URL

Dans Servlet 3.0, une application démarre correctement même si un masque d'URL a été mappé à plusieurs servlets. Toutefois, en raison d'une clarification dans la spécification Servlet 3.1, le démarrage de l'application doit échouer. Dans l'implémentation Servlet 3.1 dans Liberty, un message est renvoyé et le démarrage de l'application échoue :
SRVE9016E: Unable to insert mapping [{0}] for servlet named [{1}]. The URL pattern is already defined for servlet named [{2}].

Explanation: There is an application error. A servlet mapping URL pattern should not map to multiple servlets.

User action: Change the URL pattern for the servlet mapping.

ServletContext.getMinorVersion()

Dans l'implémentation de la fonction Servlet 3.0, cette API retournait 0.

Dans la fonction Servlet 3.1, cette API renvoie désormais 1.

ServletContext.getServerInfo()

Dans l'implémentation de la fonction Servlet 3.0, cette API retournait SMF WebContainer.

Dans la fonction Servlet 3.1, cette API renvoie désormais IBM WebSphere Liberty/8.5.5.<x>, où <x> est le numéro du groupe de correctifs de WebSphere Application Server.

ServletResponse.reset()

Vous pouvez utiliser ServletResponse.reset() pour effacer des données de réponse en mémoire tampon, le code d'état et les en-têtes de réponse lorsqu'une réponse n'est pas déjà validée. Si la fonction Servlet 3.1 est utilisée, cette méthode efface également tout enregistrement des éléments ServletResonse.getWriter() ou ServletResponse.getOutputStream() qui ont été préalablement appelés.

En-tête X-Powered-By

Dans l'implémentation de la fonction Servlet 3.0, l'en-tête X-Powered-By est défini sur Servlet/3.0. Dans l'implémentation de la fonction Servlet 3.1, l'en-tête X-Powered-By est défini sur Servlet/3.1.

Fusion de cible d'injection de référence de ressource

Dans la spécification de Servlet 3.0, les éléments <injection-target> d'une référence de ressource définie dans le fichier web-fragment.xml ne sont ajoutés au fichier web.xml parent que si la définition de référence de ressource web.xml portant le même nom ne contient pas d'éléments <injection-target>. Dans la spécification Servlet 3.1, une clarification est ajoutée pour stipuler que tous les éléments <injection-target> contenus dans les descripteurs web-fragment.xml sont ajoutés à la liste de descripteurs parents web.xml des éléments <injection-target> pour une référence de ressource du même nom. Lorsque la fonction Servlet 3.1 est utilisée, elle peut changer une option existante en activant des cibles d'injection qui étaient auparavant exclues du fichier web.xml.

Tolérance des éléments en double dans les descripteurs Web

Dans la spécification Servlet 3.1, une clarification a été ajoutée pour stipuler qu'un fichier web.xml ne peut pas contenir deux éléments <absolute-ordering>. Le déploiement d'une application comportant plusieurs éléments <absolute-ordering> échoue. De plus, les descripteurs web-fragment.xml ne peuvent pas contenir deux éléments <ordering>. Le déploiement d'une application comportant plusieurs éléments <ordering> échoue. Auparavant, le déploiement n'aurait pas échoué, mais la fonction des éléments peut être indéterminée.

Modification de l'ordre des fragments Web dans les cas metadata - complete

Le traitement de l'élément <absolute-ordering> est modifié lorsqu'un descripteur web.xml est marqué avec metadata-complete="true". Auparavant, dans les cas metadata-complete="true", toutes les archives de fragment Web étaient utilisées. Lorsque la fonction Servlet-3.1 est utilisée, l'élément <absolute-ordering> dans le cas de métadonnées complètes est considéré comme étant complet. Cette modification génère des fragments qui ne sont pas répertoriés dans l'élément <absolute-ordering> à exclure du traitement.

AsyncContext.dispatch()

Lorsque AsyncContext.dispatch() est utilisé (sans paramètres, par exemple), la demande est attribuée à l'URL d'origine. Avec la fonction Servlet-3.0, si une chaîne de requête est incluse avec la demande d'origine, elle est disponible pour la ressource répartie. Toutefois, si la fonction Servlet 3.1 est utilisée, si une chaîne de requête a été fournie à la ressource de répartition, c'est cette chaîne de requête qui est disponible pour la ressource répartie. Exemple :
Request for /FirstResource?param=One
First Resource:
    getParameter("param") returns "One"
           forward request to /SecondResource?param=Two
SecondResource
           getParameter(param) returns "Two"
           ac.start()
           ac.dispacth() dispatches to /FirstResource
First Resource
           Servlet-3.0 feature : getParamter("param") returns "One"
           Servlet-3.1 feature : getParameter("param") returns "Two"

This change was required by the Servlet 3.1 TCK.
Obtaining the request or response object after an AsyncContext.dispatch() or AsyncContext.complete() is not permitted and results in the following exception being thrown:
java.lang.IllegalStateException: SRVE9015E: Cannot obtain the request or response object after an AsyncContext.dispatch() or AsyncContext.complete().
    at com.ibm.ws.webcontainer31.async.AsyncContext31Impl.getRequest(AsyncContext31Impl.java:72)
    [...]

SessionCookieConfig.setComment()

Selon la spécification Java™ Servlet 3.1, cette API retourne une exception illegalStateException si elle est appelée une fois l'initialisation de ServletContext terminée, et la fonctionnalité Servlet 3.1 adopte le comportement requis. Toutefois, la fonctionnalité Servlet 3.0 n'empêche pas l'utilisation de l'API une fois le contexte initialisé et, par conséquent, l'application qui dépend du comportement de la fonctionnalité Servlet 3.0 ne fonctionnera pas avec la fonctionnalité Servlet.

API sendRedirect(java.lang.String location)

L'API sendRedirect(java.lang.String location) accepte les URL relatives ; toutefois, le conteneur de servlet doit convertir l'URL relative en URL absolue avant de pouvoir envoyer la réponse au client. Si l'emplacement est relatif dans l'élément '/' au début (folder/default.jsp), le conteneur l'interprète en tant qu'emplacement relatif par rapport à l'URI de demande en cours. Si l'emplacement est relatif avec un élément '/' au début, le conteneur l'interprète en tant qu'emplacement relatif pour la racine de conteneur de servlet.

Par exemple, si l'emplacement de redirection qui est fourni par l'application est folder/default.jsp, sans aucun élément '/' de début, et si l'URL de demande entrante est http://host:port/context_root/folder ou http://host:port/context_root/folder/, la demande est redirigée vers http://host:port/context_root/folder/folder/default.jsp, qui est relatif à l'URI de demande en cours.

Ce comportement est détecté dans la fonction Servlet 3.0 lorsque la propriété com.ibm.ws.webcontainer.redirectwithpathinfo est définie sur true. Cette propriété est ignorée dans la fonction Servlet 3.1 et le comportement par défaut est celui décrit.

Pages d'erreur par défaut

Une fonction étendue IBM® permet de spécifier une page d'erreur par défaut avec une extension Web, par exemple ibm-web-ext.xml.

En tant que fonction de Servlet 3.0 et versions suivantes, les pages d'erreur par défaut modifient cette possibilité de spécifier des pages d'erreur. Comme pour les pages d'erreur normales (non par défaut), les pages d'erreur par défaut sont spécifiées dans des descripteurs de module Web (web.xml), et dans des descripteurs de fragment Web (web-fragment.xml).

Les pages d'erreur normales spécifient un élément exception-type ou error-code. Une page d'erreur par défaut omet l'élément exception-type et error-code. Une page d'erreur par défaut est utilisée lorsqu'un servlet génère une exception ou définit un résultat élément error-code et qu'aucune page d'erreur configurée ne correspond aux type de l'exception ou au code d'erreur défini.

La capacité à définir des pages d'erreur par défaut est fournie par la spécification Servlet 3.0, et elle est prise en charge par les schémas Servlet 3.0. Les pages d'erreur par défaut sont des pages d'erreur qui ne contiennent pas d'élément exception-type ou error-code, conformément à la spécification Servlet 3.1.

Voici des exemples de pages d'erreur et de pages d'erreur par défaut.

Règles de priorité des pages d'erreur par défaut
Trois règles s'appliquent pour déterminer la priorité des pages d'erreur par défaut dans les fichiers web.xml, web-fragment.xml et ibm-web-ext.xml.
  • Règle 1 : fichiers web.xml et web-fragment.xml.

    Lorsqu'une page d'erreur par défaut est spécifiée dans le fichier web.xml, elle remplace (masque) toute page d'erreur qui est spécifiée dans un fichier web-fragment.xml. De même, il n'y a pas d'erreur si, en outre, plusieurs fichiers web-fragment.xml spécifient des pages d'erreur par défaut.

  • Règle 2 : fichiers web-fragment.xml et web-fragment.xml.

    Lorsqu'aucune page d'erreur par défaut n'est spécifié dans le fichier web.xml, une condition d'erreur existe si différentes pages d'erreur sont spécifiées par au moins deux fichiers web-fragment.xml.

  • Règle 3 : fichiers ibm-web-ext.xml et web.xml ou web-fragment.xml files.

    La règle de préséance entre le fichier ibm-web-ext.xml et les fichiers web.xml ou web-fragment.xml dépend du niveau de fonction de conteneur Web.

Lorsque le niveau de fonction de conteneur Web est 3.0, une page d'erreur par défaut qui est définie par un fichier ibm-web-ext.xml a priorité sur une page d'erreur par défaut qui est définie dans les fichiers web.xml ou web-fragment.xml.
Remarque : Lorsque le conteneur Web utilise le niveau de fonction 3.0, vous ne pouvez pas utiliser les schémas Servlet 3.1. Consultez la règle relative à l'utilisation des pages d'erreur par défaut pour les schémas Servlet 3.0.

Lorsque le niveau de fonction de conteneur Web est 3.1 ou version suivante, une page d'erreur par défaut qui est spécifiée par le fichier web.xml ou web-fragment.xml a priorité sur une page d'erreur par défaut qui est spécifiée dans le fichier ibm-web-ext.xml.

Règles de schéma

Deux règles s'appliquent si des pages d'erreur par défaut sont traitées les fichiers web.xml ou web-fragment.xml. Ces règles dépendent de la version de la fonction de conteneur Web, du schéma Servlet qui est utilisé, et du paramètre d'une propriété personnalisée Java.

Ces règles ont été créées car IBM WebSphere Application Server Traditional V8.0 ne prenait pas en charge les pages d'erreur par défaut dans l'édition de disponibilité générale V8.0. La prise en charge des pages d'erreur par défaut a été ajoutée à WebSphere Application Server Traditional, dans un service pack, par l'APAR PM94199. La prise en charge des pages d'erreur par défaut a été ajoutée à Liberty dans un service pack par l'APAR PI05845. Ces mises à jour constituant une modification de la fonction visible en externe, la nouvelle fonction est désactivée par défaut et elle doit être activée par une propriété système Java.

  • Cas 1 : pages d'erreur par défaut utilisant un schéma Servlet 3.0 et une fonction de conteneur Web version 3.0.

    Lorsque la fonction de conteneur Web est en version 3.0 et qu'une page d'erreur par défaut est spécifiée dans les fichiers web.xml ou web-fragment.xml qui utilisent un schéma Servlet 3.0, les pages d'erreur par défaut sont traitées uniquement si la propriété système com.ibm.ws.webcontainer.allowdefaulterrorpage Java est définie sur true. Lorsqu'aucune propriété système Java n'est définie, ou lorsqu'elle n'est pas définie sur true, la page d'erreur par défaut est ignorée. Une page d'erreur par défaut qui est spécifiée par le fichier ibm-web-ext.xml est utilisée.

  • Cas 2 : Pages d'erreur par défaut utilisant la fonction de conteneur Web version 3.1.

    Lorsque la fonction de conteneur Web est en version 3.1 ou version suivante, une page d'erreur par défaut qui est spécifiée dans le fichier web.xml ou le fichier web-fragment.xml est toujours traitée, quelle que soit la version de schéma de servlet utilisée, et même si la propriété personnalisée Java est définie.

    Ce cas se produit lorsqu'un descripteur de schéma utilise un schéma Servlet 3.1, car le traitement d'un descripteur utilisant un schéma Servlet 3.1 requiert la fonction de conteneur Web version 3.1.

Avertissement : Aucun fragment Web n'a été ajouté jusqu'à la version Servlet 3.0. Le fichier web-fragment.xml ne comporte aucun schéma depuis la version Servlet 2.5.
Exemples de page d'erreur et de pages d'erreur par défaut
Page d'erreur par défaut définie dans un fichier ibm-web-ext.xml :
<?xml version="1.0" encoding="UTF-8"?>
<web-ext xmlns="http://websphere.ibm.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-web-ext_1_0.xsd"
    version="1.0">

	<default-error-page uri="/ExtErrorPage.html"/>
</web-ext>
Elément de page d'erreur error-code, défini dans le fichier web.xml ou le fichier web-fragment.xml :
<error-page>
		<error-code>404</error-code>
			<location>/ErrorCodeErrorPage.html</location>
</error-page>
Elément de page d'erreur exception-type, défini dans le fichier web.xml ou le fichier web-fragment.xml :
<error-page>
		<exception-type>javax.servlet.ServletException</exception-type>
		<location>/ExceptionTypeErrorPage.html</location>
</error-page>
Elément de page d'erreur par défaut, défini dans le fichier web.xml ou le fichier web-fragment.xml :
<error-page>
		<location>/DefaultErrorPage.html</location>
</error-page>
Exemples de schéma
Exemple d'en-tête d'un fichier web.xml qui utilise un schéma Servlet 2.5 :
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
		 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
      version="2.5">
Exemple d'en-tête d'un fichier web.xml qui utilise un schéma Servlet 3.0 :
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
      version="3.0">
Exemple d'en-tête d'un fichier web.xml qui utilise un schéma Servlet 3.1 :
<?xml version="1.0" encoding="UTF-8"?>
<web-app
    xmlns="http://xmlns.jcp.org/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
    version="3.1">
Exemple d'en-tête d'un fichier web-fragment.xml qui utilise un schéma Servlet 3.0 :
<?xml version="1.0" encoding="utf-8"?>
<web-fragment xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-fragment_3_0.xsd"
      version="3.0">
Exemple d'en-tête d'un fichier web-fragment.xml qui utilise un schéma Servlet 3.1 :
<?xml version="1.0" encoding="utf-8"?>
<web-fragment xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns="http://xmlns.jcp.org/xml/ns/javaee"
      xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-fragment_3_1.xsd"
      version="3.1">

Icône indiquant le type de rubrique Rubrique de concept

Nom du fichier : cwlp_servlet31_behavior.html