001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *  http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    
020    //
021    // This source code implements specifications defined by the Java
022    // Community Process. In order to remain compliant with the specification
023    // DO NOT add / change / or delete method signatures!
024    //
025    
026    package javax.servlet.jsp.tagext;
027    
028    /**
029     * Optional class provided by the tag library author to describe additional
030     * translation-time information not described in the TLD.
031     * The TagExtraInfo class is mentioned in the Tag Library Descriptor file (TLD).
032     *
033     * <p>
034     * This class can be used:
035     * <ul>
036     * <li> to indicate that the tag defines scripting variables
037     * <li> to perform translation-time validation of the tag attributes.
038     * </ul>
039     *
040     * <p>
041     * It is the responsibility of the JSP translator that the initial value
042     * to be returned by calls to getTagInfo() corresponds to a TagInfo
043     * object for the tag being translated. If an explicit call to
044     * setTagInfo() is done, then the object passed will be returned in
045     * subsequent calls to getTagInfo().
046     * 
047     * <p>
048     * The only way to affect the value returned by getTagInfo()
049     * is through a setTagInfo() call, and thus, TagExtraInfo.setTagInfo() is
050     * to be called by the JSP translator, with a TagInfo object that
051     * corresponds to the tag being translated. The call should happen before
052     * any invocation on validate() and before any invocation on
053     * getVariableInfo().
054     *
055     * <p>
056     * <tt>NOTE:</tt> It is a (translation time) error for a tag definition
057     * in a TLD with one or more variable subelements to have an associated
058     * TagExtraInfo implementation that returns a VariableInfo array with
059     * one or more elements from a call to getVariableInfo().
060     */
061    
062    public abstract class TagExtraInfo {
063    
064        /**
065         * Sole constructor. (For invocation by subclass constructors, 
066         * typically implicit.)
067         */
068        public TagExtraInfo() {
069        }
070        
071        /**
072         * information on scripting variables defined by the tag associated with
073         * this TagExtraInfo instance.
074         * Request-time attributes are indicated as such in the TagData parameter.
075         *
076         * @param data The TagData instance.
077         * @return An array of VariableInfo data, or null or a zero length array
078         *         if no scripting variables are to be defined.
079         */
080        public VariableInfo[] getVariableInfo(TagData data) {
081            return ZERO_VARIABLE_INFO;
082        }
083    
084        /**
085         * Translation-time validation of the attributes. 
086         * Request-time attributes are indicated as such in the TagData parameter.
087         * Note that the preferred way to do validation is with the validate()
088         * method, since it can return more detailed information.
089         *
090         * @param data The TagData instance.
091         * @return Whether this tag instance is valid.
092         * @see TagExtraInfo#validate
093         */
094    
095        public boolean isValid(TagData data) {
096            return true;
097        }
098    
099        /**
100         * Translation-time validation of the attributes.
101         * Request-time attributes are indicated as such in the TagData parameter.
102         * Because of the higher quality validation messages possible, 
103         * this is the preferred way to do validation (although isValid() 
104         * still works).  
105         * 
106         * <p>JSP 2.0 and higher containers call validate() instead of isValid().
107         * The default implementation of this method is to call isValid().  If 
108         * isValid() returns false, a generic ValidationMessage[] is returned
109         * indicating isValid() returned false.</p>
110         *
111         * @param data The TagData instance.
112         * @return A null object, or zero length array if no errors, an 
113         *     array of ValidationMessages otherwise.
114         * @since 2.0
115         */
116        public ValidationMessage[] validate( TagData data ) {
117            ValidationMessage[] result = null;
118    
119            if( !isValid( data ) ) {
120                result = new ValidationMessage[] {
121                    new ValidationMessage( data.getId(), "isValid() == false" ) };
122            }
123    
124            return result;
125        }
126    
127        /**
128         * Set the TagInfo for this class.
129         *
130         * @param tagInfo The TagInfo this instance is extending
131         */
132        public final void setTagInfo(TagInfo tagInfo) {
133            this.tagInfo = tagInfo;
134        }
135    
136        /**
137         * Get the TagInfo for this class.
138         *
139         * @return the taginfo instance this instance is extending
140         */
141        public final TagInfo getTagInfo() {
142            return tagInfo;
143        }
144        
145        // private data
146        private TagInfo tagInfo;
147    
148        // zero length VariableInfo array
149        private static final VariableInfo[] ZERO_VARIABLE_INFO = { };
150    }
151