javax.servlet.jsp.tagext.TagSupport

Aucun

Tag, java.io.Serializable

Classe interne dépendante du container. La plupart des containers utilisent l'implémentation de référence de la classe (développée dans le projet Apache Jakarta).

La classe TagSupport est une classe de support qui fournit des implémentations par défaut pour toutes les méthodes de l'interface Tag. Elle doit normalement servir de superclasse aux gestionnaires de balises n'ayant pas besoin d'accéder aux contenus des corps des éléments de l'action personnalisée correspondants.

Tout exemple d'action personnalisée pouvant être implémenté comme gestionnaire de balises simple (c'est-à-dire, implémenter uniquement l'interface Tag) représente une action qui ajoute un cookie à la réponse HTTP. Appelons cette action <ora:addCookie>. La classe du gestionnaire de balises est appelée com.ora.jsp.tags.generic.AddCookieTag et elle étend la classe TagSupport pour hériter de la plupart des implémentations de méthodes de l'interface Tag :

package com.ora.jsp.tags.generic;

import javax.servlet.http.*;
import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;
import com.ora.jsp.util.*;

public class AddCookieTag extends TagSupport {

L'action <ora:addCookie> possède deux attributs obligatoires, name et value, ainsi qu'un attribut facultatif, maxAge. Chaque attribut est représenté par une variable d'instance et une méthode de réglage des propriétés standard :

    private String name;
    private String value;
    private String maxAgeString;

    public void setName(String name) {
        this.name = name;
    }

    public void setValue(String value) {
        this.value = value;
    }

    public void setMaxAge(String maxAgeString) {
        this.maxAgeString = maxAgeString;
    }

Toutes les méthodes de réglage définissent les variables d'instance correspondantes.

L'action personnalisée a pour but de créer un nouvel objet javax.servlet.Cookie avec les valeurs name, value et maxAge spécifiées par les attributs et d'ajouter le cookie à la réponse. La classe de gestionnaire de balises remplace la méthode doEndTag() pour effectuer cette tâche :

    public int doEndTag() throws JspException {
        int maxAge = -1;
        if (maxAgeString != null) {
            try {
                maxAge = Integer.valueOf(maxAgeString).
                  intValue();
            }
            catch (NumberFormatException e) {
                throw new JspException("Invalid maxAge: " + 
                    e.getMessage());
            }
        }
        sendCookie(name, value, maxAge,
            (HttpServletResponse) pageContext.getResponse());
        return EVAL_PAGE;
    }

    private void sendCookie(String name, String value, 
      int maxAge,
        HttpServletResponse res) {
        Cookie cookie = new Cookie(name, value);
        cookie.setMaxAge(maxAge);
        res.addCookie(cookie);
    }

L'attribut maxAge est facultatif, par conséquent, avant de convertir la valeur String correspondante en int, on réalise un test pour vérifier qu'il soit défini. Les variables name et value n'ont pas besoin de pareils tests puisque le container web vérifie que tous les attributs obligatoires soient bien définis dans l'action personnalisée. Si un attribut obligatoire n'est pas défini, le container web refuse de traiter la page ce qui permet de garantir l'existence d'une valeur pour chaque variable correspondant à un attribut obligatoire. Pour savoir si un attribut est obligatoire ou non, il faut consulter le fichier TLD de la bibliothèque.

La classe de gestionnaire de balises doit également implémenter la méthode release() afin de libérer toutes les références des objets qu'elle a acquis :

public void release() {
    name = null;
    value = null;
    maxAgeString = null;
    super.release();
}

La méthode release() est appelée lorsqu'il n'est plus nécessaire d'utiliser le gestionnaire de balises. La classe AddCookieTag affecte la valeur null à toutes ses propriétés et appelle super.release() pour permettre à la classe TagSupport de faire de même. Cette action permet de récupérer la mémoire allouée à tous les objets des propriétés.

La méthode findAncestorWithClass() est une méthode TagSupport ne présentant aucun intérêt dans ce cas précis mais qui peut s'avérer utile dans d'autres situations. Elle peut être utilisée par un gestionnaire de balises pour permettre à un élément d'action imbriqué de trouver son parent. Le gestionnaire de balises imbriqué peut ensuite appeler des méthodes implémentées par la classe de gestionnaire parent pour obtenir ou fournir des informations au parent. Par exemple, il peut indiquer les éléments <jsp:param> imbriqués dans le corps des éléments d'action JSP standard <jsp:forward> et <jsp:include>. Un gestionnaire de balises utilisant la méthode findAncestorWithClass() peut implémenter une action personnalisée équivalente pour un élément de paramètre imbriqué de la manière suivante :

import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;
public class ParamTag extends TagSupport {
    private String name;
    private String value;

    public void setName(String name) {
        this.name = name;
    }

    public void setValue(String value) {
        this.value = value;
    }

    public int doEndTag() throws JspException {
        Tag parent = findAncestorWithClass(this, 
          ParamParent.class);
        if (parent == null) {
            throw new JspException("The param action is not " +
                "enclosed by a supported action type");
        }
        ParamParent paramParent = (ParamParent) parent;
        paramParent.setParam(name, URLEncoder.
          encode(value));
        return EVAL_PAGE;
    }
}