Classe TagSupport |
Nom de la classe :
javax.servlet.jsp.tagext.TagSupport
Etend :
Aucun
Implémente :
Tag, java.io.Serializable
Implémentée par :
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).
Description
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.
Exemple
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;
        }
    }

TagSupport() |
public TagSupport()
Crée une nouvelle instance avec le nom et la valeur spécifiés.

doEndTag() |
public int doEndTag() throws JspException
Renvoie la valeur EVAL_PAGE.

doStartTag() |
public int doStartTag() throws JspException
Renvoie la valeur SKIP_BODY.

findAncestorWithClass() |
public static final Tag findAncestorWithClass(Tag from, Class class)
Renvoie l'instance de la classe spécifiée trouvée en évaluant la concordance de tous les parents d'une structure d'imbrication de gestionnaire de balises (correspondant à des éléments d'action imbriqués) commençant par l'instance Tag spécifiée, ou bien la valeur null si l'instance est introuvable.

getId() |
public String getId()
Renvoie la valeur d'attribut id, ou bien la valeur null si non défini.

getParent() |
public Tag getParent()
Renvoie le parent de cette instance Tag (représentant l'élément d'action qui contient l'élément d'action correspondant à cette instance Tag), ou bien la valeur null si l'instance n'a pas de parent (c'est-à-dire qu'elle se trouve au niveau supérieur dans la page JSP).

getValue() |
public Object getValue(String k)
Renvoie la valeur de l'attribut spécifié défini avec la méthode setValue(), ou bien la valeur null si la valeur est introuvable.

getValues() |
public java.util.Enumeration getValues()
Renvoie une Enumeration de tous les noms d'attribut des valeurs définies avec la méthode setValue().

release() |
public void release()
Supprime les références de tous les objets conservés par cette instance.

removeValue() |
public void removeValue(String k)
Supprime une valeur définie avec la méthode setValue().

setPageContext() |
public void setPageContext(PageContext pageContext)
Enregistre une référence dans l'instance PageContext actuelle.

setId() |
public void setId(String id)
Définit la valeur d'attribut id.

setParent() |
public void setParent(Tag t)
Enregistre une référence dans le parent de cette instance.

setValue() |
public void setValue(String k, Object o)
Enregistre l'attribut spécifié avec la valeur définie. Les sous-classes peuvent utiliser cette méthode pour enregistrer des valeurs d'attribut plutôt que d'utiliser des variables d'instance.