Save This Page
Home » apache-tomcat-6.0.16-src » javax » servlet » jsp » tagext » [javadoc | source]
    1   /*
    2   * Licensed to the Apache Software Foundation (ASF) under one or more
    3   * contributor license agreements.  See the NOTICE file distributed with
    4   * this work for additional information regarding copyright ownership.
    5   * The ASF licenses this file to You under the Apache License, Version 2.0
    6   * (the "License"); you may not use this file except in compliance with
    7   * the License.  You may obtain a copy of the License at
    8   *
    9   *     http://www.apache.org/licenses/LICENSE-2.0
   10   *
   11   * Unless required by applicable law or agreed to in writing, software
   12   * distributed under the License is distributed on an "AS IS" BASIS,
   13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   14   * See the License for the specific language governing permissions and
   15   * limitations under the License.
   16   */
   17   package javax.servlet.jsp.tagext;
   18   
   19   import java.io.Serializable;
   20   import java.util.Enumeration;
   21   import java.util.Hashtable;
   22   
   23   import javax.servlet.jsp.JspException;
   24   import javax.servlet.jsp.PageContext;
   25   
   26   /**
   27    * A base class for defining new tag handlers implementing Tag.
   28    *
   29    * <p> The TagSupport class is a utility class intended to be used as
   30    * the base class for new tag handlers.  The TagSupport class
   31    * implements the Tag and IterationTag interfaces and adds additional
   32    * convenience methods including getter methods for the properties in
   33    * Tag.  TagSupport has one static method that is included to
   34    * facilitate coordination among cooperating tags.
   35    *
   36    * <p> Many tag handlers will extend TagSupport and only redefine a
   37    * few methods. 
   38    */
   39   
   40   public class TagSupport implements IterationTag, Serializable {
   41   
   42       /**
   43        * Find the instance of a given class type that is closest to a given
   44        * instance.
   45        * This method uses the getParent method from the Tag
   46        * interface.
   47        * This method is used for coordination among cooperating tags.
   48        *
   49        * <p>
   50        * The current version of the specification only provides one formal
   51        * way of indicating the observable type of a tag handler: its
   52        * tag handler implementation class, described in the tag-class
   53        * subelement of the tag element.  This is extended in an
   54        * informal manner by allowing the tag library author to
   55        * indicate in the description subelement an observable type.
   56        * The type should be a subtype of the tag handler implementation
   57        * class or void.
   58        * This addititional constraint can be exploited by a
   59        * specialized container that knows about that specific tag library,
   60        * as in the case of the JSP standard tag library.
   61        *
   62        * <p>
   63        * When a tag library author provides information on the
   64        * observable type of a tag handler, client programmatic code
   65        * should adhere to that constraint.  Specifically, the Class
   66        * passed to findAncestorWithClass should be a subtype of the
   67        * observable type.
   68        * 
   69        *
   70        * @param from The instance from where to start looking.
   71        * @param klass The subclass of Tag or interface to be matched
   72        * @return the nearest ancestor that implements the interface
   73        * or is an instance of the class specified
   74        */
   75   
   76       public static final Tag findAncestorWithClass(Tag from, Class klass) {
   77   	boolean isInterface = false;
   78   
   79   	if (from == null ||
   80   	    klass == null ||
   81   	    (!Tag.class.isAssignableFrom(klass) &&
   82   	     !(isInterface = klass.isInterface()))) {
   83   	    return null;
   84   	}
   85   
   86   	for (;;) {
   87   	    Tag tag = from.getParent();
   88   
   89   	    if (tag == null) {
   90   		return null;
   91   	    }
   92   
   93   	    if ((isInterface && klass.isInstance(tag)) ||
   94   	        klass.isAssignableFrom(tag.getClass()))
   95   		return tag;
   96   	    else
   97   		from = tag;
   98   	}
   99       }
  100   
  101       /**
  102        * Default constructor, all subclasses are required to define only
  103        * a public constructor with the same signature, and to call the
  104        * superclass constructor.
  105        *
  106        * This constructor is called by the code generated by the JSP
  107        * translator.
  108        */
  109   
  110       public TagSupport() { }
  111   
  112       /**
  113        * Default processing of the start tag, returning SKIP_BODY.
  114        *
  115        * @return SKIP_BODY
  116        * @throws JspException if an error occurs while processing this tag
  117        *
  118        * @see Tag#doStartTag()
  119        */
  120    
  121       public int doStartTag() throws JspException {
  122           return SKIP_BODY;
  123       }
  124   
  125       /**
  126        * Default processing of the end tag returning EVAL_PAGE.
  127        *
  128        * @return EVAL_PAGE
  129        * @throws JspException if an error occurs while processing this tag
  130        *
  131        * @see Tag#doEndTag()
  132        */
  133   
  134       public int doEndTag() throws JspException {
  135   	return EVAL_PAGE;
  136       }
  137   
  138   
  139       /**
  140        * Default processing for a body.
  141        *
  142        * @return SKIP_BODY
  143        * @throws JspException if an error occurs while processing this tag
  144        *
  145        * @see IterationTag#doAfterBody()
  146        */
  147       
  148       public int doAfterBody() throws JspException {
  149   	return SKIP_BODY;
  150       }
  151   
  152       // Actions related to body evaluation
  153   
  154   
  155       /**
  156        * Release state.
  157        *
  158        * @see Tag#release()
  159        */
  160   
  161       public void release() {
  162   	parent = null;
  163   	id = null;
  164   	if( values != null ) {
  165   	    values.clear();
  166   	}
  167   	values = null;
  168       }
  169   
  170       /**
  171        * Set the nesting tag of this tag.
  172        *
  173        * @param t The parent Tag.
  174        * @see Tag#setParent(Tag)
  175        */
  176   
  177       public void setParent(Tag t) {
  178   	parent = t;
  179       }
  180   
  181       /**
  182        * The Tag instance most closely enclosing this tag instance.
  183        * @see Tag#getParent()
  184        *
  185        * @return the parent tag instance or null
  186        */
  187   
  188       public Tag getParent() {
  189   	return parent;
  190       }
  191   
  192       /**
  193        * Set the id attribute for this tag.
  194        *
  195        * @param id The String for the id.
  196        */
  197   
  198       public void setId(String id) {
  199   	this.id = id;
  200       }
  201   
  202       /**
  203        * The value of the id attribute of this tag; or null.
  204        *
  205        * @return the value of the id attribute, or null
  206        */
  207       
  208       public String getId() {
  209   	return id;
  210       }
  211   
  212       /**
  213        * Set the page context.
  214        *
  215        * @param pageContext The PageContext.
  216        * @see Tag#setPageContext
  217        */
  218   
  219       public void setPageContext(PageContext pageContext) {
  220   	this.pageContext = pageContext;
  221       }
  222   
  223       /**
  224        * Associate a value with a String key.
  225        *
  226        * @param k The key String.
  227        * @param o The value to associate.
  228        */
  229   
  230       public void setValue(String k, Object o) {
  231   	if (values == null) {
  232   	    values = new Hashtable<String, Object>();
  233   	}
  234   	values.put(k, o);
  235       }
  236   
  237       /**
  238        * Get a the value associated with a key.
  239        *
  240        * @param k The string key.
  241        * @return The value associated with the key, or null.
  242        */
  243   
  244       public Object getValue(String k) {
  245   	if (values == null) {
  246   	    return null;
  247   	} else {
  248   	    return values.get(k);
  249   	}
  250       }
  251   
  252       /**
  253        * Remove a value associated with a key.
  254        *
  255        * @param k The string key.
  256        */
  257   
  258       public void removeValue(String k) {
  259   	if (values != null) {
  260   	    values.remove(k);
  261   	}
  262       }
  263   
  264       /**
  265        * Enumerate the keys for the values kept by this tag handler.
  266        *
  267        * @return An enumeration of all the keys for the values set,
  268        *     or null or an empty Enumeration if no values have been set.
  269        */
  270   
  271       public Enumeration<String> getValues() {
  272   	if (values == null) {
  273   	    return null;
  274   	}
  275   	return values.keys();
  276       }
  277   
  278       // private fields
  279   
  280       private   Tag         parent;
  281       private   Hashtable<String, Object>   values;
  282       /**
  283        * The value of the id attribute of this tag; or null.
  284        */
  285       protected String	  id;
  286   
  287       // protected fields
  288   
  289       /**
  290        * The PageContext.
  291        */
  292       protected PageContext pageContext;
  293   }
  294   

Save This Page
Home » apache-tomcat-6.0.16-src » javax » servlet » jsp » tagext » [javadoc | source]