TagSupport-Klasse  
 
 
Klassenname:

javax.servlet.jsp.tagext.TagSupport

 
Erweitert:

Keine

 
Implementiert:

Tag, java.io.Serializable

 
Implementiert von:

Interne containerabhängige Klasse. Die meisten Container verwenden die Verweisimplementierung der Klasse (im Apache Jakarta-Projekt entwickelt).

 
Beschreibung

TagSupport ist eine Supportklasse, die Standardimplementierungen für alle Schnittstellenmethoden Tag bereitstellt. Sie dient als übergeordnete Klasse für Tag-Prozeduren, die keinen Zugriff auf den Body-Inhalt der entsprechenden benutzerdefinierten Aktionselemente benötigen.

 
Beispiel

Ein Beispiel für eine benutzerdefinierte Aktion, die als einfache Tag-Prozedur implementiert werden kann (das heißt durch Implementieren der Schnittstelle Tag), ist eine Aktion, die der HTTP-Antwort einen Cookie hinzufügt. Als Beispiel wird diese Aktion <ora:addCookie> genannt. Die Tag-Prozedurklasse heißt com.ora.jsp.tags.generic.AddCookieTag und erweitert die Klasse TagSupport, damit die meisten Methodenimplementierungen der Schnittstelle Tag übernommen werden:

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 {

Die Aktion <ora:addCookie> hat die beiden obligatorischen Attribute name und value sowie das optionale Attribut maxAge. Jedes Attribut wird von einer Instanzenvariable und einer Standardmethode zum Einstellen von Eigenschaften dargestellt:

    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;
    }

Alle Methoden zum Einstellen legen die entsprechenden Instanzenvariablen fest.

Die benutzerdefinierte Aktion hat den Zweck, ein neues Objekt javax.servlet.Cookie mit den von den Attributen angegebenen Werten für name, value und maxAge zu erstellen und den Cookie der Antwort hinzuzufügen. Dazu setzt die Tag-Prozedurklasse die Methode doEndTag() außer Kraft:

    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);
    }

Das Attribut maxAge ist optional. Deshalb wird getestet, ob das Attribut eingestellt ist, bevor der entsprechende String-Wert in einen int-Wert konvertiert wird. Für die Variablen name und value sind solche Tests nicht erforderlich, da der Webcontainer überprüft, ob alle obligatorischen Attribute in der benutzerdefinierten Aktion eingestellt sind. Wenn ein obligatorisches Attribut nicht eingestellt ist, verweigert der Webcontainer die Verarbeitung der Seite. So ist stets gewährleistet, dass Variablen für obligatorische Attribute einen Wert haben. In der TLD-Datei der Bibliothek ist festgelegt, ob ein Attribut obligatorisch ist oder nicht.

Die Tag-Prozedurklasse sollte auch die Methode release() implementieren, damit alle erworbenen Verweise auf Objekte freigegeben werden:

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

Die Methode release() wird aufgerufen, wenn die Tag-Prozedur nicht mehr benötigt wird. Die Klasse AddCookieTag stellt alle ihre Eigenschaften auf null ein und ruft super.release() auf, damit die Klasse TagSupport auch ihre Eigenschaften auf null einstellt. Damit können alle Eigenschaftsobjekte in den Papierkorb überführt werden.

Eine TagSupport-Methode, die zwar in diesem Beispiel nicht erforderlich ist, aber in anderen Situationen nützlich sein kann, ist die Methode findAncestorWithClass(). Sie kann von einer Tag-Prozedur verwendet werden, um das übergeordnete Element eines verschachtelten Aktionselements zu ermitteln. Die verschachtelte Tag-Prozedur kann dann Methoden aufrufen, die von der übergeordneten Tag-Prozedurklasse implementiert werden, um Informationen vom übergeordneten Element abzurufen oder an das übergeordnete Element zu senden. Beispielsweise können die <jsp:param>-Elemente bereitgestellt werden, die im Body von standardmäßigen JSP-Aktionselementen <jsp:forward> und <jsp:include> verschachtelt sind. Eine entsprechende benutzerdefinierte Aktion für ein verschachteltes Parameterelement kann mit einer Tag-Prozedur implementiert werden, die die Methode findAncestorWithClass() verwendet, wie im Folgenden gezeigt:

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()

Erstellt eine neue Instanz mit dem angegebenen Namen und Wert.

doEndTag()  
public int doEndTag() throws JspException

Gibt EVAL_PAGE zurück.

doStartTag()  
public int doStartTag() throws JspException

Gibt SKIP_BODY zurück.

findAncestorWithClass()  
public static final Tag findAncestorWithClass(Tag from, Class class)

Gibt die Instanz der angegebenen Klasse zurück. Dazu wird für jedes übergeordnete Element in einer verschachtelten Struktur von Tag-Prozeduren (entsprechend verschachtelten Aktionselementen) nach einer Übereinstimmung gesucht, wobei mit der angegebenen Tag-Instanz begonnen wird. Wenn keine Übereinstimmung gefunden wird, lautet die Rückgabe null.

getId()  
public String getId()

Gibt den Wert des Attributs id zurück. Wenn das Attribut nicht eingestellt ist, lautet die Rückgabe null.

getParent()  
public Tag getParent()

Gibt das übergeordnete Element dieser Tag-Instanz zurück (das Aktionselement, das das Aktionselement enthält, das dieser Tag-Instanz entspricht). Wenn die Instanz kein übergeordnetes Element hat (und sich deshalb auf der obersten Ebene in der JSP-Seite befindet), lautet die Rückgabe null.

getValue()  
public Object getValue(String k)

Gibt den Wert des angegebenen Attributs zurück, der mit der Methode setValue() festgelegt wurde. Wenn der Wert nicht gefunden wird, lautet die Rückgabe null.

getValues()  
public java.util.Enumeration getValues()

Gibt eine Enumeration aller Attributnamen für die Werte zurück, die mit der Methode setValue() eingestellt wurden.

release()  
public void release()

Entfernt die Verweise auf alle Objekte, die in dieser Instanz enthalten sind.

removeValue()  
public void removeValue(String k)

Entfernt einen Wert, der mit der Methode setValue() festgelegt wurde.

setPageContext()  
public void setPageContext(PageContext pageContext)

Speichert einen Verweis auf das aktuelle Objekt PageContext.

setId()  
public void setId(String id)

Stellt den Wert des Attributs id ein.

setParent()  
public void setParent(Tag t)

Speichert einen Verweis auf das übergeordnete Element für diese Instanz.

setValue()  
public void setValue(String k, Object o)

Speichert das angegebene Attribut mit dem angegebenen Wert. Unterklassen können diese Methode zum Speichern von Attributwerten als Alternative zu Instanzenvariablen verwenden.