Servlet behavior changes

The Servlet 3.1 implementation contains behavior changes that might cause an application that was written for Servlet 3.0 to behave differently or fail when you use the Servlet 3.1 feature.

You can choose between the Servlet 3.0 and Servlet 3.1 feature implementations for each server instance, with consideration for behavior changes. Si le comportement souhaité est présent dans Servlet 3.1 uniquement, vous devez utiliser cette fonction. If an existing application would be adversely affected by behavior changes in the Servlet 3.1 feature, then using the Servlet 3.0 feature preserves the existing behavior for that 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.

The behavior changes are introduced for the following reasons:
  • Changes that are required by clarifications in the Servlet 3.1 specification.
  • Changes that are required for the implementation to pass the Servlet 3.1 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

Dans Servlet 3.0, une application démarrait sans aucun problème même si un masque d'URL était mappé à plusieurs servlets. However, due to a clarification in the Servlet 3.1 specification, the application must fail to start. In the Liberty Servlet 3.1 implementation, a message is output and the application fails to start:
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.

In the Servlet 3.1 feature this API now returns IBM WebSphere Liberty/8.5.5.<x>, where <x> is the WebSphere Application Server fix pack number.

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

In the Servlet 3.0 specification, the <injection-target> elements of a resource reference that is defined in a web-fragment.xml file are added only to the parent web.xml file if the web.xml resource reference definition with the same name has no <injection-target> elements. In the Servlet 3.1 specification, it is clarified that all <injection-target> elements in web-fragment.xml descriptors are added to the parent web.xml descriptors list of <injection-target> elements for a resource reference of the same name. 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

In the Servlet 3.1 specification, it was clarified that a web.xml file cannot contain two <absolute-ordering> elements. Deployment of an application with multiple <absolute-ordering> elements fails. Additionally, web-fragment.xml descriptors cannot contain two <ordering> elements. Deployment of an application with multiple <ordering> elements fails. 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

The processing of the <absolute-ordering> element is changed in cases where a web.xml descriptor is marked metadata-complete="true". Auparavant, dans les cas metadata-complete="true", toutes les archives de fragment Web étaient utilisées. When the Servlet-3.1 feature is in use, the <absolute-ordering> element in metadata-complete cases is considered to be complete. This change results in fragments that are not listed in the <absolute-ordering> element to be excluded from processing.

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. Par 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. However, the Servlet 3.0 feature does not prevent use of this API after the context is initialized and as a result, applications that depend on the Servlet 3.0 feature behavior will not work with the Servlet 3.1 feature.

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. If the location is relative without a leading '/' (folder/default.jsp), the container interprets it as relative to the current request URI. 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 à 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.

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



Icône d'horodatage Dernière mise à jour: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=cweb_servlet_behavior
Nom du fichier : cweb_servlet_behavior.html