Modifications du comportement de Servlet 3.1
L'implémentation de Servlet 3.1 inclut des modifications de comportement. Par conséquent, une application écrite pour Servlet 3.0 peut se comporter différemment ou échouer lorsque vous utilisez la fonction Servlet 3.1.
Vous pouvez choisir d'implémenter Servlet 3.0 ou Servlet 3.1 pour chaque instance de serveur, en fonction des modifications de comportement. Si le comportement souhaité est présent dans Servlet 3.1 uniquement, vous devez utiliser cette fonction. Si les modifications de comportement dans la fonction Servlet 3.1 devaient entraîner des conséquences néfastes pour une application existante, l'utilisation de la fonction Servlet 3.0 préserve 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. Configurer ces deux fonctions serait une erreur. Si c'était le cas, aucune fonction de servlet ne serait chargée.
- Modifications qui sont requises à des fins d'éclaircissements dans la spécification Servlet 3.1.
- Modifications qui sont requises pour l'implémentation de Servlet 3.1 avec le kit Technology Compatibility Kit (TCK).
- Modifications destinées à améliorer l'implémentation du servlet.
Servlets ajoutés à l'aide d'un programme et programmes d'écoutes
Un éclaircissement concernant la spécification Servlet 3.1 interdit désormais qu'un élément ServletContextListener configure des servlets, des filtres ou des programmes d'écoute à l'aide d'un programme, si l'élément ServletContextListener n'a pas été déclaré dans le fichier web.xml ou web-fragment.xml ou s'il a été annoté avec @WebListener. Par conséquent, tout appel sur l'élément ServletContext pour effectuer une telle configuration par programmation se traduit par une exception UnsupportedOperationException.
La méthode de réacheminement après traitement asynchrone est démarrée
Dans l'implémentation de Servlet 3.0, une réponse est toujours fermée avant la méthode de réacheminement des retours d'interface RequestDispatcher. Toutefois, en raison d'un éclaircissement dans la spécification Servlet 3.1, l'implémentation de Servlet 3.1 ne ferme pas ou ne vide pas la réponse avant la méthode de réacheminement des retours d'interface RequestDispatcher, si la demande est mise en mode asynchrone. Cette correction peut avoir une incidence sur les applications existantes en version 3.0, lesquelles ajoutent une sortie de réponse sur le retour de réacheminement car ces données de réponse sont désormais envoyées, alors que ce n'était pas le cas dans Servlet 3.0.
Conflits de masque d'URL
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 retourne désormais IBM WebSphere Liberty/8.5.5.<x>, où <x> est le numéro de 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 Servlet 3.0, les éléments <injection-target> d'une référence de ressource qui est définie dans un fichier web-fragment.xml sont ajouts uniquement au fichier parent web.xml si la définition de référence de ressource web.xml du même nom ne comporte pas d'éléments <injection-target>. Dans la spécification Servlet 3.1, il est précisé que tous les éléments <injection-target> des descripteurs web-fragment.xml sont ajoutés à la liste des descripteurs web.xml parents 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, il est précisé qu'un fichier web.xml ne peut pas contenir deux éléments <absolute-ordering>. Le déploiement d'une application avec 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 avec 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é dans les cas où un descripteur web.xml est marqué 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 les cas metadata-complete est considéré comme terminé. Conséquence de cette modification, les fragments qui ne sont pas répertoriés dans l'élément <absolute-ordering> sont exclus du traitement.
AsyncContext.dispatch()
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.
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ègle 1 : fichiers web.xml et web-fragment.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 à WebSphere Application Server 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.
- Cas 1 : pages d'erreur par défaut utilisant un schéma Servlet 3.0
et une fonction de conteneur Web
version 3.0.
- 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">