You are viewing a plain text version of this content. The canonical link for it is here.
Posted to servletapi-dev@jakarta.apache.org by da...@locus.apache.org on 2000/08/24 23:05:38 UTC
cvs commit: jakarta-servletapi/src/share/javax/servlet/jsp/tagext IterationTag.java PageInfo.java TagLibraryValidator.java BodyContent.java BodyTag.java BodyTagSupport.java Tag.java TagAttributeInfo.java TagData.java TagExtraInfo.java TagInfo.java TagLibraryInfo.java TagSupport.java VariableInfo.java
dannyc 00/08/24 14:05:36
Modified: src/share/javax/servlet/jsp Tag: SERVLET_23_JSP_12
HttpJspPage.java JspEngineInfo.java
JspException.java JspFactory.java JspPage.java
JspWriter.java PageContext.java
src/share/javax/servlet/jsp/tagext Tag: SERVLET_23_JSP_12
BodyContent.java BodyTag.java BodyTagSupport.java
Tag.java TagAttributeInfo.java TagData.java
TagExtraInfo.java TagInfo.java TagLibraryInfo.java
TagSupport.java VariableInfo.java
Added: src/share/javax/servlet/jsp/tagext Tag: SERVLET_23_JSP_12
IterationTag.java PageInfo.java
TagLibraryValidator.java
Log:
Checking in the initial version of the JSP API classes in sync with the public draft of the JSP 1.2 specification.
Revision Changes Path
No revision
No revision
1.1.1.1.4.1 +19 -5 jakarta-servletapi/src/share/javax/servlet/jsp/HttpJspPage.java
Index: HttpJspPage.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/HttpJspPage.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- HttpJspPage.java 2000/04/26 05:22:31 1.1.1.1
+++ HttpJspPage.java 2000/08/24 21:05:22 1.1.1.1.4.1
@@ -60,16 +60,30 @@
import java.io.IOException;
/**
- * This is the interface that a JSP processor-generated class for the
- * HTTP protocol must satisfy.
+ * The HttpJspPage interface describes the interaction that a JSP Page
+ * Implementation Class must satisfy when using the HTTP protocol.
+ *
+ * <p>HttpJspPage objects are obtained from the JspFactory class.
+ *
+* <p>
+ * The behaviour is identical to that of the JspPage, except for the signature
+ * of the _jspService method, which is now expressable in the Java type
+ * system and included explicitly in the interface.
+ *
+ * @see JspPage
*/
public interface HttpJspPage extends JspPage {
/**
- * _jspService corresponds to the body of the JSP page.
- * This method is defined automatically by the JSP processor
- * and should NEVER BE DEFINED BY THE JSP AUTHOR
+ * The _jspService()method corresponds to the body of the JSP page. This
+ * method is defined automatically by the JSP container and should never
+ * be defined by the JSP page author.
+ * <p>
+ * If a superclass is specified using the extends attribute, that
+ * superclass may choose to perform some actions in its service() method
+ * before or after calling the _jspService() method. See using the extends
+ * attribute in the JSP_Engine chapter of the JSP specification.
*/
public void _jspService(HttpServletRequest request,
HttpServletResponse response)
1.1.1.1.4.1 +5 -6 jakarta-servletapi/src/share/javax/servlet/jsp/JspEngineInfo.java
Index: JspEngineInfo.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/JspEngineInfo.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- JspEngineInfo.java 2000/04/26 05:22:31 1.1.1.1
+++ JspEngineInfo.java 2000/08/24 21:05:22 1.1.1.1.4.1
@@ -56,25 +56,24 @@
package javax.servlet.jsp;
/**
- * <p>
* The JspEngineInfo is an abstract class that provides information on the
- * current JSP engine
- * </p>
+ * current JSP engine.
*/
public abstract class JspEngineInfo {
/**
+ * Return the version number of the JSP specification that is supported by
+ * this JSP engine.
* <p>
- * Specification version numbers use a "Dewey Decimal"
- * syntax that consists of positive decimal integers
+ * Specification version numbers that consists of positive decimal integers
* separated by periods ".", for example, "2.0" or "1.2.3.4.5.6.7".
* This allows an extensible number to be used to
* represent major, minor, micro, etc versions.
* The version number must begin with a number.
* </p>
*
- * @return the specification version, nullis returned if it is not known
+ * @return the specification version, null is returned if it is not known
*/
public abstract String getSpecificationVersion();
1.1.1.1.4.1 +3 -1 jakarta-servletapi/src/share/javax/servlet/jsp/JspException.java
Index: JspException.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/JspException.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- JspException.java 2000/04/26 05:22:31 1.1.1.1
+++ JspException.java 2000/08/24 21:05:23 1.1.1.1.4.1
@@ -56,7 +56,9 @@
package javax.servlet.jsp;
/**
- * A generic exception known to the JSP engine
+ * A generic exception known to the JSP engine; uncaught
+ * JspExceptions will result in an invocation of the errorpage
+ * machinery.
*/
public class JspException extends Exception {
1.1.1.1.4.1 +7 -3 jakarta-servletapi/src/share/javax/servlet/jsp/JspFactory.java
Index: JspFactory.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/JspFactory.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- JspFactory.java 2000/04/26 05:22:31 1.1.1.1
+++ JspFactory.java 2000/08/24 21:05:23 1.1.1.1.4.1
@@ -66,13 +66,17 @@
* methods available to a JSP page at runtime for the purposes of creating
* instances of various interfaces and classes used to support the JSP
* implementation.
- * </p>
* <p>
* A conformant JSP Engine implementation will, during it's initialization
* instantiate an implementation dependent subclass of this class, and make
* it globally available for use by JSP implementation classes by registering
- * the instance created with this class via the static <code> setDefaultFactory() </code> method.
- * </p>
+ * the instance created with this class via the
+ * static <code> setDefaultFactory() </code> method.
+ * <p>
+ * The PageContext and the JspEngineInfo classes are the only implementation-dependent
+ * classes that can be created from the factory.
+ * <p>
+ * JspFactory objects should not be used by JSP page authors.
*/
public abstract class JspFactory {
1.1.1.1.4.1 +45 -29 jakarta-servletapi/src/share/javax/servlet/jsp/JspPage.java
Index: JspPage.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/JspPage.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- JspPage.java 2000/04/26 05:22:31 1.1.1.1
+++ JspPage.java 2000/08/24 21:05:23 1.1.1.1.4.1
@@ -58,8 +58,13 @@
import javax.servlet.*;
/**
- * This is the interface that a JSP processor-generated class must
- * satisfy.
+ * The JspPage interface describes the generic interaction that a JSP Page
+ * Implementation class must satisfy; pages that use the HTTP protocol
+ * are described by the HttpJspPage interface.
+ *
+ * <p>JspPage objects are obtained from the JspFactory object.
+ *
+ * <p><B>Two plus One Methods</B>
* <p>
* The interface defines a protocol with 3 methods; only two of
* them: jspInit() and jspDestroy() are part of this interface as
@@ -71,45 +76,56 @@
* the above methods at the apropriate time based on the
* corresponding Servlet-based method invocations.
* <p>
- * The jspInit(0 and jspDestroy() methods can be defined by a JSP
+ * The jspInit() and jspDestroy() methods can be defined by a JSP
* author, but the _jspService() method is defined authomatically
* by the JSP processor based on the contents of the JSP page.
+ *
+ * <p><B>_jspService()</B>
+ * <p>
+ * The _jspService()method corresponds to the body of the JSP page. This
+ * method is defined automatically by the JSP container and should never
+ * be defined by the JSP page author.
+ * <p>
+ * If a superclass is specified using the extends attribute, that
+ * superclass may choose to perform some actions in its service() method
+ * before or after calling the _jspService() method. See using the extends
+ * attribute in the JSP_Engine chapter of the JSP specification.
+ * <p>
+ * The specific signature depends on the protocol supported by the JSP page.
+ *
+ * <pre>
+ * public void _jspService(<em>ServletRequestSubtype</em> request,
+ * <em>ServletResponseSubtype</em> response)
+ * throws ServletException, IOException;
+ * </pre>
*/
-public interface JspPage extends Servlet {
- /**
- * Methods that can be DEFINED BY THE JSP AUTHOR
- * either directly (via a declaration) or via an event handler
- * (in JSP 1.1)
- */
+public interface JspPage extends Servlet {
/**
- * jsp_init() is invoked when the JspPage is initialized.
- * At this point getServletConfig() will return the desired value.
+ * The jspInit() method is invoked when the JSP page is initialized. It
+ * is the responsibility of the JSP implementation (and of the class
+ * mentioned by the extends attribute, if present) that at this point
+ * invocations to the getServletConfig() method will return the desired
+ * value.
+ *
+ * A JSP page can override this method by including a definition for it
+ * in a declaration element.
+ *
+ * A JSP page should redefine the init() method from Servlet
*/
public void jspInit();
/**
- * jsp_destroy() is invoked when the JspPage is about to be destroyed.
+ * The jspDestroy() method is invoked when the JSP page is about to be
+ * destroyed.
+ *
+ * A JSP page can override this method by including a definition for it
+ * in a declaration element.
+ *
+ * A JSP page should redefine the destroy() method from Servlet
*/
public void jspDestroy();
- /**
- * service is the main service entry from the superclass. It is
- * responsible from determine if the protocol is valid and to call
- * into the appropriate _jspService(), after the appropriate casting.
- */
-
- /**
- * _jspService corresponds to the body of the JSP page.
- * This method is defined automatically by the JSP processor
- * and should NEVER BE DEFINED BY THE JSP AUTHOR
- *
- * The specific signature depends on the protocol supported by the JSP page.
- *
- * public void _jspService(<ServletRequestSubtype> request,
- * <ServletResponseSubtype> response)
- * throws ServletException, IOException;
- */
}
1.1.1.1.4.1 +66 -9 jakarta-servletapi/src/share/javax/servlet/jsp/JspWriter.java
Index: JspWriter.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/JspWriter.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- JspWriter.java 2000/04/26 05:22:31 1.1.1.1
+++ JspWriter.java 2000/08/24 21:05:23 1.1.1.1.4.1
@@ -59,12 +59,53 @@
/**
* <p>
+ * The actions and template data in a JSP page is written using the
+ * JspWriter object that is referenced by the implicit variable out which
+ * is initialized automatically using methods in the PageContext object.
+ *<p>
* This abstract class emulates some of the functionality found in the
* java.io.BufferedWriter and java.io.PrintWriter classes,
* however it differs in that it throws java.io.IOException from the print
- * methods with PrintWriter does not.
- * </p>
+ * methods while PrintWriter does not.
+ * <p><B>Buffering</B>
* <p>
+ * The initial JspWriter object is associated with the PrintWriter object
+ * of the ServletResponse in a way that depends on whether the page is or
+ * not buffered. If the page is not buffered, output written to this
+ * JspWriter object will be written through to the PrintWriter directly,
+ * which will be created if necessary by invoking the getWriter() method
+ * on the response object. But if the page is buffered, the PrintWriter
+ * object will not be created until when the buffer is flushed, and
+ * operations like setContentType() are legal. Since this flexibility
+ * simplifies programming substantially, buffering is the default for JSP
+ * pages.
+ * <p>
+ * Buffering raises the issue of what to do when the buffer is
+ * exceeded. Two approaches can be taken:
+ * <ul>
+ * <li>
+ * Exceeding the buffer is not a fatal error; when the buffer is
+ * exceeded, just flush the output.
+ * <li>
+ * Exceeding the buffer is a fatal error; when the buffer is exceeded,
+ * raise an exception.
+ * </ul>
+ * <p>
+ * Both approaches are valid, and thus both are supported in the JSP
+ * technology. The behavior of a page is controlled by the autoFlush
+ * attribute, which defaults to true. In general, JSP pages that need to
+ * be sure that correct and complete data has been sent to their client
+ * may want to set autoFlush to false, with a typical case being that
+ * where the client is an application itself. On the other hand, JSP
+ * pages that send data that is meaningful even when partially
+ * constructed may want to set autoFlush to true; a case may be when the
+ * data is sent for immediate display through a browser. Each application
+ * will need to consider their specific needs.
+ * <p>
+ * An alternative considered was to make the buffer size unbounded, but
+ * this has the disadvantage that runaway computations may consume an
+ * unbounded amount of resources.
+ * <p>
* The "out" implicit variable of a JSP implementation class is of this type.
* If the page directive selects autoflush="true" then all the I/O operations
* on this class shall automatically fluch the contents of the buffer if an
@@ -72,7 +113,6 @@
* without a flush. If autoflush="false" then all the I/O operations on this
* class shall throw an IOException if performing the current opertion would
* result in a buffer overflow condition.
- * </p>
*
* @see java.io.Writer
* @see java.io.BufferedWriter
@@ -306,8 +346,8 @@
/**
* Print an array of characters and then terminate the line. This method
- * behaves as though it invokes <code>{@link #print(char[])}</code> and then
- * <code>{@link #println()}</code>.
+ * behaves as though it invokes <code>print(char[])</code> and then
+ * <code>println()</code>.
* @throws java.io.IOException
*/
@@ -331,6 +371,7 @@
abstract public void println(Object x) throws IOException;
+
/**
* Clear the contents of the buffer. If the buffer has been already
* been flushed then the clear operation shall throw an IOException
@@ -347,7 +388,7 @@
* mehtod will not throw an IOException if the buffer has already been
* flushed. It merely clears the current content of the buffer and
* returns.
- *
+ *
* @throws IOException If an I/O error occurs
*/
@@ -359,6 +400,12 @@
* intended destination. Then, if that destination is another character or
* byte stream, flush it. Thus one flush() invocation will flush all the
* buffers in a chain of Writers and OutputStreams.
+ * <p>
+ * The method may be invoked indirectly if the buffer size is exceeded.
+ * <p>
+ * Once a stream has been closed,
+ * further write() or flush() invocations will cause an IOException to be
+ * thrown.
*
* @exception IOException If an I/O error occurs
*/
@@ -366,9 +413,13 @@
abstract public void flush() throws IOException;
/**
- * Close the stream, flushing it first. Once a stream has been closed,
- * further write() or flush() invocations will cause an IOException to be
- * thrown. Closing a previously-closed stream, however, has no effect.
+ * Close the stream, flushing it first
+ * <p>
+ * This method needs not be invoked explicitly for the initial JspWriter
+ * as the code generated by the JSP container will automatically
+ * include a call to close().
+ * <p>
+ * Closing a previously-closed stream, unlike flush(),, has no effect.
*
* @exception IOException If an I/O error occurs
*/
@@ -376,18 +427,24 @@
abstract public void close() throws IOException;
/**
+ * This method returns the size of the buffer used by the JspWriter.
+ *
* @return the size of the buffer in bytes, or 0 is unbuffered.
*/
public int getBufferSize() { return bufferSize; }
/**
+ * This method returns the number of unused bytes in the buffer.
+ *
* @return the number of bytes unused in the buffer
*/
abstract public int getRemaining();
/**
+ * This method indicates whether the JspWriter is autoFlushing.
+ *
* @return if this JspWriter is auto flushing or throwing IOExceptions on buffer overflow conditions
*/
1.1.1.1.4.1 +92 -66 jakarta-servletapi/src/share/javax/servlet/jsp/PageContext.java
Index: PageContext.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/PageContext.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- PageContext.java 2000/04/26 05:22:31 1.1.1.1
+++ PageContext.java 2000/08/24 21:05:24 1.1.1.1.4.1
@@ -76,60 +76,17 @@
* A PageContext instance provides access to all the namespaces associated with
* a JSP page, provides access to several page attributes, as well as a layer above the
* implementation details.
- * <p>
- * An instance of an implementation dependent subclass of this abstract base
- * class is created by a JSP implementation class at the begining of it's
- * <code> _jspService() </code> method via an implementation default
- * <code> JspFactory </code>, as follows:
- *</p>
- *<p>
- *<p>
- *<code>
- *<pre>
- * public class foo implements Servlet {
- *
- * // ...
- *
- *public void _jspService(HttpServletRequest request,
- * HttpServletResponse response)
- * throws IOException, ServletException {
- *
- * JspFactory factory = JspFactory.getDefaultFactory();
- * PageContext pageContext = factory.getPageContext(
- this,
- request,
- response,
- null, // errorPageURL
- false, // needsSession
- JspWriter.DEFAULT_BUFFER,
- true // autoFlush
- );
- *
- * // initialize implicit variables for scripting env ...
- *
- * HttpSession session = pageContext.getSession();
- * JspWriter out = pageContext.getOut();
- * Object page = this;
*
- * try {
- * // body of translated JSP here ...
- * } catch (Exception e) {
- * out.clear();
- * pageContext.handlePageException(e);
- * } finally {
- * out.close();
- * factory.releasePageContext(pageContext);
- * }
- *}
- *</pre>
- * </code>
- * </p>
- * <p>
- * The <code> PageContext </code> class is an abstract class, designed to be
+ * <p> The <code> PageContext </code> class is an abstract class, designed to be
* extended to provide implementation dependent implementations thereof, by
* conformant JSP engine runtime environments. A PageContext instance is
- * obtained by a JSP implementation class by calling the JspFactory.getPageContext() method, and is released by calling JspFactory.releasePageContext().
- * </p>
+ * obtained by a JSP implementation class by calling the
+ * JspFactory.getPageContext() method, and is released by calling
+ * JspFactory.releasePageContext().
+ *
+ * <p> An example of how PageContext, JspFactory, and other classes can be
+ * used within a JSP Page Implementation object is given elsewhere.
+ *
* <p>
* The PageContext provides a number of facilities to the page/component author and
* page implementor, including:
@@ -142,8 +99,40 @@
* <li>mechanisms to forward or include the current request to other active components in the application
* <li>a mechanism to handle errorpage exception processing
* </td>
- * </p>
*
+ * <p><B>Methods Intended for Container Generated Code</B>
+ * <p>Some methods are intended to be used by the code generated by the
+ * container, not by code written by JSP page authors, or JSP tag library authors.
+ * <p>The methods supporting <B>lifecycle</B> are <code>initialize()</code>
+ * and <code>release()</code>
+ *
+ * <p>
+ * The following methods enable the <B>management of nested</B> JspWriter streams to
+ * implement Tag Extensions: <code>pushBody()</code> and <code>popBody()</code>
+ *
+ * <p><B>Methods Intended for JSP authors</B>
+ * <p>
+ * Some methods provide <B>uniform access</B> to the diverse scopes objects.
+ * The implementation must use the underlying Servlet machinery
+ * corresponding to that scope, so information can be passed back and
+ * forth between Servlets and JSP pages. The methods are:
+ * <code>setAttribute()</code>, <code>getAttribute()</code>,
+ * <code>findAttribute()</code>, <code>removeAttribute()</code>,
+ * <code>getAttributesScope()</code> and <code>getAttributeNamesInScope()</code> .
+ *
+ * <p>
+ * The following methods provide <B>convenient access</B> to implicit objects:
+ * <ul>
+ * <code>getOut()</code>, <code>getException()</code>, <code>getPage()</code>
+ * <code>getRequest()</code>, <code>getResponse()</code>,
+ * <code>getSession()</code>, <code>getServletConfig()</code>
+ * and <code>getServletContext()</code>.
+ *
+ * <p>
+ * The following methods provide support for <B>forwarding, inclusion
+ * and error handling</B>:
+ * <code>forward()</code>, <code>include()</code>,
+ * and <code>handlePageException()</code>.
*/
abstract public class PageContext {
@@ -236,16 +225,18 @@
* The initialize emthod is called to initialize an uninitialized PageContext
* so that it may be used by a JSP Implementation class to service an
* incoming request and response wihtin it's _jspService() method.
- * </p>
+ *
* <p>
* This method is typically called from JspFactory.getPageContext() in
* order to initialize state.
- * </p>
+ *
* <p>
* This method is required to create an initial JspWriter, and associate
* the "out" name in page scope with this newly created object.
- * </p>
*
+ * <p>
+ * This method should not be used by page or tag libray authors.
+ *
* @param servlet The Servlet that is associated with this PageContext
* @param request The currently pending request for this Servlet
* @param response The currently pending response for this Servlet
@@ -266,16 +257,23 @@
* all internal references, and preparing the PageContext for potential
* reuse by a later invocation of initialize(). This method is typically
* called from JspFactory.releasePageContext().
- * </p>
*
- * <p> subclasses shall envelope this method </p>
+ * <p>
+ * Subclasses shall envelope this method.
+ *
+ * <p>
+ * This method should not be used by page or tag libray authors.
*
*/
abstract public void release();
+
/**
- * register the name and object specified with page scope semantics
+ * Register the name and object specified with page scope semantics.
+ *
+ * @param name the name of the attribute to set
+ * @param attribute the object to associate with the name
*
* @throws NullPointerException if the name or object is null
*/
@@ -297,7 +295,8 @@
abstract public void setAttribute(String name, Object o, int scope);
/**
- * <p>return the object associated with the name in the page scope or null </p>
+ * Return the object associated with the name in the page scope or null
+ * if not found.
*
* @param name the name of the attribute to get
*
@@ -308,7 +307,8 @@
abstract public Object getAttribute(String name);
/**
- * <p>return the object associated with the name in the specifed scope or null </p>
+ * Return the object associated with the name in the specifed scope or null if not
+ * found.
*
* @param name the name of the attribute to set
* @param scope the scope with which to associate the name/object
@@ -320,11 +320,9 @@
abstract public Object getAttribute(String name, int scope);
/**
- * <p>
* Searches for the named attribute in page, request, session (if valid),
* and application scope(s) in order and returns the value associated or
* null.
- * </p>
*
* @return the value associated or null
*/
@@ -332,24 +330,35 @@
abstract public Object findAttribute(String name);
/**
- * remove the object reference associated with the specified name
+ * Remove the object reference associated with the given name,
+ * look in all scopes in the scope order.
+ *
+ * @param name The name of the object to remove.
*/
abstract public void removeAttribute(String name);
/**
- * remove the object reference associated with the specified name
+ * Remove the object reference associated with the specified name
+ * in the given scope.
+ *
+ * @param name The name of the object to remove.
+ * @param scope The scope where to look.
*/
abstract public void removeAttribute(String name, int scope);
/**
+ * Get the scope where a given attribute is defined.
+ *
* @return the scope of the object associated with the name specified or 0
*/
abstract public int getAttributesScope(String name);
/**
+ * Enumerate all the attributes in a given scope
+ *
* @return an enumeration of names (java.lang.String) of all the attributes the specified scope
*/
@@ -357,18 +366,24 @@
abstract public Enumeration getAttributeNamesInScope(int scope);
/**
+ * The current value of the out object (a JspWriter).
+ *
* @return the current JspWriter stream being used for client response
*/
abstract public JspWriter getOut();
/**
+ * The current value of the session object (an HttpSession).
+ *
* @return the HttpSession for this PageContext or null
*/
abstract public HttpSession getSession();
/**
+ * The current value of the page object (a Servlet).
+ *
* @return the Page implementation class instance (Servlet) associated with this PageContext
*/
@@ -376,30 +391,40 @@
/**
+ * The current value of the request object (a ServletRequest).
+ *
* @return The ServletRequest for this PageContext
*/
abstract public ServletRequest getRequest();
/**
+ * The current value of the response object (a ServletResponse).
+ *
* @return the ServletResponse for this PageContext
*/
abstract public ServletResponse getResponse();
/**
+ * The current value of the exception object (an Exception).
+ *
* @return any exception passed to this as an errorpage
*/
abstract public Exception getException();
/**
+ * The ServletConfig instance.
+ *
* @return the ServletConfig for this PageContext
*/
abstract public ServletConfig getServletConfig();
/**
+ * The ServletContext instance.
+ *
* @return the ServletContext for this PageContext
*/
@@ -481,13 +506,14 @@
* by redirecting the exception to either the specified error page for this
* JSP, or if none was specified, to perform some implementation dependent
* action.
- * </p>
+ *
* <p>
* A JSP implementation class shall typically clean up any local state
* prior to invoking this and will return immediately thereafter. It is
* illegal to generate any output to the client, or to modify any
* ServletResponse state after invoking this call.
- * </p>
+ *
+ * <p><B>TODO</B> - should handle Throwable
*
* @param e the exception to be handled
*
No revision
No revision
1.1.1.1.4.1 +37 -16 jakarta-servletapi/src/share/javax/servlet/jsp/tagext/BodyContent.java
Index: BodyContent.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/tagext/BodyContent.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- BodyContent.java 2000/04/26 05:22:31 1.1.1.1
+++ BodyContent.java 2000/08/24 21:05:27 1.1.1.1.4.1
@@ -61,8 +61,28 @@
import javax.servlet.jsp.*;
/**
- * A JspWriter subclass that can be used to process body evaluations
- * so they can re-extracted later on.
+ * An encapsulation of the evaluation of the body of an action so it is
+ * available to a tag handler. BodyContent is a subclass of JspWriter.
+ *
+ * <p>
+ * Note that the content of BodyContent is the result of evaluation, so
+ * it will not contain actions and the like, but the result of their
+ * invocation.
+ *
+ * <p>
+ * BodyContent has methods to convert its contents into
+ * a String, to read its contents, and to clear the contents.
+ *
+ * <p>
+ * The buffer size of a BodyContent object is unbounded. A
+ * BodyContent object cannot be in autoFlush mode. It is not possible to
+ * invoke flush on a BodyContent object, as there is no backing stream.
+ *
+ * <p>
+ * Instances of BodyContent are created by invoking the pushBody and
+ * popBody methods of the PageContext class. A BodyContent is enclosed
+ * within another JspWriter (maybe another BodyContent object) following
+ * the structure of their associated actions.
*/
public abstract class BodyContent extends JspWriter {
@@ -70,7 +90,7 @@
/**
* Protected constructor.
*
- * Unbounded buffer, no autoflushing.
+ * Unbounded buffer, no autoflushing.
*/
protected BodyContent(JspWriter e) {
@@ -79,8 +99,11 @@
}
/**
- * Redefine flush().
- * It is not valid to flush.
+ * Redefined flush() so it is not legal.
+ *
+ * <p>
+ * It is not valid to flush a BodyContent because there is no backing
+ * stream behind it.
*/
public void flush() throws IOException {
@@ -88,7 +111,7 @@
}
/**
- * Clear the body.
+ * Clear the body without throwing any exceptions.
*/
public void clearBody() {
@@ -102,26 +125,23 @@
/**
* Return the value of this BodyContent as a Reader.
- * Note: this is after evaluation!! There are no scriptlets,
- * etc in this stream.
*
- * @returns the value of this BodyContent as a Reader
+ * @return the value of this BodyContent as a Reader
*/
public abstract Reader getReader();
+
/**
* Return the value of the BodyContent as a String.
- * Note: this is after evaluation!! There are no scriptlets,
- * etc in this stream.
*
- * @returns the value of the BodyContent as a String
+ * @return the value of the BodyContent as a String
*/
public abstract String getString();
+
/**
* Write the contents of this BodyContent into a Writer.
- * Subclasses are likely to do interesting things with the
- * implementation so some things are extra efficient.
+ * Subclasses may optimize common invocation patterns.
*
* @param out The writer into which to place the contents of
* this body evaluation
@@ -129,10 +149,11 @@
public abstract void writeOut(Writer out) throws IOException;
+
/**
- * Get the enclosing JspWriter
+ * Get the enclosing JspWriter.
*
- * @returns the enclosing JspWriter passed at construction time
+ * @return the enclosing JspWriter passed at construction time
*/
public JspWriter getEnclosingWriter() {
1.1.1.1.4.1 +82 -56 jakarta-servletapi/src/share/javax/servlet/jsp/tagext/BodyTag.java
Index: BodyTag.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/tagext/BodyTag.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- BodyTag.java 2000/04/26 05:22:31 1.1.1.1
+++ BodyTag.java 2000/08/24 21:05:28 1.1.1.1.4.1
@@ -57,53 +57,93 @@
import javax.servlet.jsp.*;
/**
- * The BodyTag interface extends Tag by defining additional methods that let
- * a Tag handler access its body.
+ * The BodyTag interface extends IterationTag by defining additional
+ * methods that let a tag handler manipulate the content of evaluating its body.
+ *
+ * <p>
+ * It is the responsibility of the tag handler to manipulate the body
+ * content. For example the tag handler may take the body content,
+ * convert it into a String using the bodyContent.getString
+ * method and then use it. Or the tag handler may take the body
+ * content and write it out into its enclosing JspWriter using
+ * the bodyContent.writeOut method.
+ *
+ * <p> A tag handler that implements BodyTag is treated as one that
+ * implements IterationTag, except that the doStartTag method can
+ * return SKIP_BODY, EVAL_BODY_INCLUDE or EVAL_BODY_BUFFERED.
+ *
* <p>
- * The interface provides two new methods: one is to be invoked with the BodyContent
- * for the evaluation of the body, the other is to be reevaluated after every body
- * evaluation.
+ * If EVAL_BODY_INCLUDE is returned, then evaluation happens
+ * as in IterationTag.
+ *
+ * <p>
+ * If EVAL_BODY_BUFFERED is returned, then a BodyContent object will be
+ * created to capture the body evaluation. This object is obtained by
+ * calling the pushBody method of the current pageContext, which
+ * additionally has the effect of saving the previous out value. The
+ * object is returned through a call to the popBody method of the
+ * PageContext class; the call also restores the value of out.
+ *
* <p>
- * Without repeating the portions described in Tag.java, a typical invocation sequence is:
+ * The interface provides one new property with a setter method and one
+ * new action method.
*
- * <pre>
- * <code>
+ * <p> The new property is bodyContent, to contain the BodyContent
+ * object, where the JSP Page implementation object will place the
+ * evaluation (and reevaluation, if appropriate) of the body. The setter
+ * method (setBodyContent) will only be invoked if doStartTag() returns
+ * EVAL_BODY_BUFFERED.
*
- * -- we are picking up after all the setters have been done
- * t.doStartTag();
- * out = pageContext.pushBody();
- * -- prepare for body
- * t.setBodyContent(out);
- * -- preamble
- * t.doBodyInit();
- * -- BODY evaluation into out
- * t.doAfterBody();
- * -- while doAfterBody returns EVAL_BODY_TAG we iterate
- * -- BODY evaluation into out
- * t.doAfterBody()
- * -- done
- * t.doEndTag()
+ * <p> The new action methods is doInitBody(), which is invoked right after
+ * setBodyContent() and before the body evaluation. This method is only
+ * invoked if doStartTag() returns EVAL_BODY_BUFFERED.
*
- * </code>
- * </pre>
*/
-public interface BodyTag extends Tag {
+public interface BodyTag extends IterationTag {
/**
- * Request the creation of new BodyContent on which to evaluate the
- * body of this tag.
- * Returned from doStartTag and doAfterBody.
- * This is an illegal return value for doStartTag when the class does not
- * implement BodyTag, since BodyTag is needed to manipulate the new Writer.
+ * Deprecated constant that has the same value as EVAL_BODY_BUFFERED
+ * and EVAL_BODY_AGAIN. This name has been marked as deprecated
+ * to encourage the use of the two different terms, which are much
+ * more descriptive.
+ *
+ * @deprecated As of Java JSP API 1.2, use BodyTag.EVAL_BODY_BUFFERED
+ * or IterationTag.EVAL_BODY_AGAIN.
*/
public final static int EVAL_BODY_TAG = 2;
+ /**
+ * Request the creation of new buffer, a BodyContent on which to
+ * evaluate the body of this tag.
+ *
+ * Returned from doStartTag when it implements BodyTag.
+ * This is an illegal return value for doStartTag when the class
+ * does not implement BodyTag.
+ */
+
+ public final static int EVAL_BODY_BUFFERED = 2;
+
+
/**
- * Setter method for the bodyContent property.
+ * Set the bodyContent property.
+ * This method is invoked by the JSP page implementation object at
+ * most once per action invocation. The method will be invoked before
+ * doInitBody and it will not be invoked if there is no body evaluation
+ * (for example if doStartTag() returns EVAL_BODY_INCLUDE
+ * or SKIP_BODY).
+ *
+ * <p>
+ * When setBodyContent is invoked, the value of the implicit object out
+ * has already been changed in the pageContext object. The BodyContent
+ * object passed will have not data on it but may have been reused
+ * (and cleared) from some previous invocation.
+ *
* <p>
- * This method will not be invoked if there is no body evaluation.
+ * The BodyContent object is available and with the appropriate content
+ * until after the invocation of the doEndTag method, at which case it
+ * may be reused.
*
* @param b the BodyContent
* @seealso #doInitBody
@@ -112,37 +152,23 @@
void setBodyContent(BodyContent b);
+
/**
* Prepare for evaluation of the body.
- * <p>
- * The method will be invoked once per action invocation by the page implementation
- * after a new BodyContent has been obtained and set on the tag handler
- * via the setBodyContent() method and before the evaluation
- * of the tag's body into that BodyContent.
+ * This method is invoked by the JSP page implementation object
+ * after setBodyContent and before the first time
+ * the body is to be evaluated. The method will not be invoked if there
+ * is no body evaluation.
+ *
* <p>
- * This method will not be invoked if there is no body evaluation.
+ * The JSP container will resynchronize
+ * any variable values that are indicated as so in TagExtraInfo after the
+ * invocation of doInitBody().
*
+ * @throws JspException
* @seealso #doAfterBody
*/
void doInitBody() throws JspException;
- /**
- * Actions after some body has been evaluated.
- * <p>
- * Not invoked in empty tags or in tags returning SKIP_BODY in doStartTag()
- * This method is invoked after every body evaluation.
- * The pair "BODY -- doAfterBody()" is invoked initially if doStartTag()
- * returned EVAL_BODY_TAG, and it is repeated as long
- * as the doAfterBody() evaluation returns EVAL_BODY_TAG
- * <p>
- * The method re-invocations may be lead to different actions because
- * there might have been some changes to shared state, or because
- * of external computation.
- *
- * @returns whether additional evaluations of the body are desired
- * @seealso #doInitBody
- */
-
- int doAfterBody() throws JspException;
}
1.1.1.1.4.1 +39 -39 jakarta-servletapi/src/share/javax/servlet/jsp/tagext/BodyTagSupport.java
Index: BodyTagSupport.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/tagext/BodyTagSupport.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- BodyTagSupport.java 2000/04/26 05:22:31 1.1.1.1
+++ BodyTagSupport.java 2000/08/24 21:05:28 1.1.1.1.4.1
@@ -64,7 +64,15 @@
import java.util.Hashtable;
/**
- * Actions in a Tag Library are defined through subclasses of Tag.
+ * A base class for defining tag handlers implementing BodyTag.
+ *
+ * <p>
+ * The BodyTagSupport class implements the BodyTag interface and adds
+ * additional convenience methods including getter methods for the
+ * bodyContent property and methods to get at the previous out JspWriter.
+ *
+ * <p>
+ * Many tag handlers will extend TagSupport and only redefine a few tags.
*/
public class BodyTagSupport extends TagSupport implements BodyTag {
@@ -76,7 +84,6 @@
*
* This constructor is called by the code generated by the JSP
* translator.
- *
*/
public BodyTagSupport() {
@@ -84,27 +91,22 @@
}
/**
- * Process the start tag for this instance.
- *
- * The doStartTag() method assumes that all setter methods have been
- * invoked before.
- *
- * When this method is invoked, the body has not yet been invoked.
+ * Default processing of the start tag returning EVAL_BODY_BUFFERED
*
- * @returns EVAL_BODY_TAG if the tag wants to process body, SKIP_BODY if it
- * does ont want to process it.
+ * @return EVAL_BODY_BUFFERED;
+ * @seealso BodyTag#doStartTag
*/
public int doStartTag() throws JspException {
- return EVAL_BODY_TAG;
+ return EVAL_BODY_BUFFERED;
}
/**
- * Process the end tag. This method will be called on all Tag objects.
+ * Default processing of the end tag returning EVAL_PAGE.
*
- * All instance state associated with this instance must be reset.
- * The release() method should be called after this invocation.
+ * @return EVAL_PAGE
+ * @seealso Tag#doEndTag
*/
public int doEndTag() throws JspException {
@@ -115,56 +117,50 @@
// Actions related to body evaluation
/**
- * Prepare for evaluation of the body
- * It will be invoked at most once per action invocation.
- * Will not be invoked if there is no body evaluation.
+ * Prepare for evaluation of the body: stash the bodyContent away.
*
- * Frequently it is not redefined by Tag author.
- *
* @param b the BodyContent
* @seealso #doAfterBody
+ * @seealso #doInitBody()
+ * @seealso BodyTag#setBodyContent
*/
public void setBodyContent(BodyContent b) {
this.bodyContent = b;
}
+
/**
- * Prepare for evaluation of the body
- * It will be invoked at most once per action invocation.
- * Will not be invoked if there is no body evaluation.
- *
- * Frequently it is not redefined by Tag author.
+ * Prepare for evaluation of the body just before the first body evaluation:
+ * no action.
*
+ * @seealso #setBodyContent
* @seealso #doAfterBody
+ * @seealso BodyTag#doInitBody
*/
public void doInitBody() throws JspException {
}
+
/**
- * Actions after some body has been evaluated.
- *
- * Not invoked in empty tags or in tags returning SKIP_BODY in doStartTag()
- * This method is invoked after every body evaluation.
- * The pair "BODY -- doAfterBody()" is invoked initially if doStartTag()
- * returned EVAL_BODY_TAG, and it is repeated as long
- * as the doAfterBody() evaluation returns EVAL_BODY_TAG
- * <p>
- * The method re-invocations may be lead to different actions because
- * there might have been some changes to shared state, or because
- * of external computation.
+ * After the body evaluation: do not reevaluate and continue with the page.
+ * By default nothing is done with the bodyContent data (if any).
*
- * @returns whether additional evaluations of the body are desired
+ * @return SKIP_BODY
* @seealso #doInitBody
+ * @seealso BodyTag#doAfterBody
*/
public int doAfterBody() throws JspException {
return SKIP_BODY;
}
+
/**
- * reset the state of the Tag
+ * Release state.
+ *
+ * @seealso Tag#release
*/
public void release() {
@@ -174,7 +170,9 @@
}
/**
- * Get current bodyContent
+ * Get current bodyContent.
+ *
+ * @return the body content.
*/
public BodyContent getBodyContent() {
@@ -183,7 +181,9 @@
/**
- * Get surrounding out
+ * Get surrounding out JspWriter.
+ *
+ * @return the enclosing JspWriter, from the bodyContent.
*/
public JspWriter getPreviousOut() {
1.1.1.1.4.1 +112 -60 jakarta-servletapi/src/share/javax/servlet/jsp/tagext/Tag.java
Index: Tag.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/tagext/Tag.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- Tag.java 2000/04/26 05:22:31 1.1.1.1
+++ Tag.java 2000/08/24 21:05:29 1.1.1.1.4.1
@@ -59,61 +59,48 @@
/**
- * The Tag interface defines the basic protocol between a Tag handler and JSP page
- * implementation class. It defines the life cycle and the methods to be invoked at
- * start and end tag.
- * <p>
- * There are several methods that get invoked to set the state of a Tag handler.
- * The Tag handler is required to keep this state so the page compiler can
- * choose not to reinvoke some of the state setting.
- * <p>
- * The page compiler guarantees that setPageContext and setParent
- * will all be invoked on the Tag handler, in that order, before doStartTag() or
- * doEndTag() are invoked on it.
- * The page compiler also guarantees that release will be invoked on the Tag
- * handler before the end of the page.
+ * The interface of a simple tag handler that does not want to manipulate its body.
+ * The Tag interface defines the basic protocol between a Tag handler and
+ * JSP page implementation class. It defines the life cycle and the
+ * methods to be invoked at start and end tag.
+ *
+ * <p><B>Properties</B>
+ *
* <p>
- * Here is a typical invocation sequence:
+ * The Tag interface specifies the setter and getter methods for the core
+ * pageContext and parent properties.
*
- * <pre>
- * <code>
- *
- * ATag t = new ATag();
- *
- * -- need to set required information
- * t.setPageContext(...);
- * t.setParent(...);
- * t.setAttribute1(value1);
- * t.setAttribute2(value2);
- *
- * -- all ready to go
- * t.doStartTag();
- * t.doEndTag();
- *
- * ... other tags and template text
- *
- * -- say one attribute is changed, but parent and pageContext have not changed
- * t.setAttribute2(value3);
- * t.doStartTag()
- * t.doEndTag()
- *
- * ... other tags and template text
- *
- * -- assume that this new action happens to use the same attribute values
- * -- it is legal to reuse the same handler instance, with no changes...
- * t.doStartTag();
- * t.doEndTag();
- *
- * -- OK, all done
- * t.release()
- * </code>
- * </pre>
+ * <p> The JSP page implementation object invokes setPageContext and
+ * setParent, in that order, before invoking doStartTag() or doEndTag().
*
+ * <p> The JSP 1.2 specification has the resetCustomProperties()
+ * method to reset all custom properties to default values. Note that the
+ * JSP translator can determine whether a specific tag handler class supports
+ * or not this method.
+ *
+ * <p><B>Methods</B>
+ *
* <p>
- * The Tag interface also includes methods to set a parent chain, which is used
- * to find enclosing tag handlers.
+ * There are two main actions: doStartTag and doEndTag. Once all
+ * appropriate properties have been initialized, the doStartTag and
+ * doEndTag methods can be invoked on the tag handler. Between these
+ * invocations, the tag handler is assumed to hold a state that must
+ * be preserved. After the doEndTag invocation, the tag handler is
+ * available for further invocations (and it is expected to have
+ * retained its properties).
+ *
+ * <p><B>Release</B>
+ *
+ * <p> Once all invocations on the tag handler
+ * are completed, the release method is invoked on it. Once a release
+ * method is invoked <em>all</em> properties, including parent and
+ * pageContext, are assumed to have been reset to an unspecified value.
+ * The page compiler guarantees that release will be invoked on the Tag
+ * handler before the end of the page.
*
- */
+ * <p> Lifecycle details are collected elsewhere in the JSP specification
+ * document.
+*/
public interface Tag {
@@ -149,9 +136,11 @@
// Setters for Tag handler data
+
/**
* Set the current page context.
- * Called by the page implementation prior to doStartTag().
+ * This method is invoked by the JSP page implementation object
+ * prior to doStartTag().
* <p>
* This value is *not* reset by doEndTag() and must be explicitly reset
* by a page implementation
@@ -159,19 +148,29 @@
void setPageContext(PageContext pc);
+
/**
- * Set the current nesting Tag of this Tag.
- * Called by the page implementation prior to doStartTag().
+ * Set the parent (closest enclosing tag handler) of this tag handler.
+ * Invoked by the JSP page implementation object prior to doStartTag().
* <p>
* This value is *not* reset by doEndTag() and must be explicitly reset
* by a page implementation. Code can assume that setPageContext
* has been called with the proper values before this point.
+ *
+ * @param t The parent tag, or null.
*/
+
void setParent(Tag t);
+
/**
- * @return the current parent
+ * Get the parent (closest enclosing tag handler) for this tag handler.
+ * This method is used by the findAncestorWithClass() method in
+ * TagSupport.
+ *
+ * @param t The enclosing tag handler.
+ * @returns the current parent, or null if none.
* @seealso TagSupport.findAncestorWithClass().
*/
@@ -180,15 +179,45 @@
// Actions for basic start/end processing.
+
+ /**
+ * Reset all custom (i.e. not parent, not pageContext) attributes to their
+ * default values
+ */
+ public void resetCustomAttributes();
+
+
/**
* Process the start tag for this instance.
+ * This method is invoked by the JSP page implementation object.
*
- * @returns EVAL_BODY_INCLUDE if the tag wants to process body, SKIP_BODY if it
- * does not want to process it.
+ * <p>
+ * The doStartTag method assumes that the properties pageContext and
+ * parent have been set. It also assumes that any properties exposed as
+ * attributes have been set too. When this method is invoked, the body
+ * has not yet been evaluated.
*
- * When a Tag returns EVAL_BODY_INCLUDE the body (if any) is evaluated
- * and written into the current "out" JspWriter then doEndTag() is invoked.
+ * <p>
+ * This method returns Tag.EVAL_BODY_INCLUDE or
+ * BodyTag.EVAL_BODY_BUFFERED to indicate
+ * that the body of the action should be evaluated or SKIP_BODY to
+ * indicate otherwise.
+ * When a Tag returns EVAL_BODY_INCLUDE the result of evaluating
+ * the body (if any) is included into the current "out" JspWriter as it
+ * happens and then doEndTag() is invoked.
+ *
+ * <p>
+ * BodyTag.EVAL_BODY_BUFFERED is only valid if the tag handler
+ * implements BodyTag.
+ *
+ * <p>
+ * The JSP container will resynchronize
+ * any variable values that are indicated as so in TagExtraInfo after the
+ * invocation of doStartBody().
*
+ * @returns EVAL_BODY_INCLUDE if the tag wants to process body, SKIP_BODY if it
+ * does not want to process it.
+ * @throws JspException.
* @see BodyTag
*/
@@ -196,14 +225,37 @@
/**
- * Process the end tag. This method will be called on all Tag objects.
+ * Process the end tag for this instance.
+ * This method is invoked by the JSP page implementation object
+ * on all Tag handlers.
+ *
+ * <p>
+ * This method will be called after returning from doStartTag. The
+ * body of the action may or not have been evaluated, depending on
+ * the return value of doStartTag.
+ *
+ * <p>
+ * If this method returns EVAL_PAGE, the rest of the page continues
+ * to be evaluated. If this method returns SKIP_PAGE, the rest of
+ * the page is not evaluated and the request is completed. If this
+ * request was forwarded or included from another page (or Servlet),
+ * only the current page evaluation is completed.
+ *
+ * <p>
+ * The JSP container will resynchronize
+ * any variable values that are indicated as so in TagExtraInfo after the
+ * invocation of doEndBody().
+ *
+ * @returns indication of whether to continue evaluating the JSP page.
+ * @throws JspException.
*/
int doEndTag() throws JspException;
/**
* Called on a Tag handler to release state.
- * The page compiler guarantees this method will be called on all tag handlers,
+ * The page compiler guarantees that JSP page implementation
+ * objects will invoke this method on all tag handlers,
* but there may be multiple invocations on doStartTag and doEndTag in between.
*/
1.1.1.1.4.1 +22 -10 jakarta-servletapi/src/share/javax/servlet/jsp/tagext/TagAttributeInfo.java
Index: TagAttributeInfo.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/tagext/TagAttributeInfo.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- TagAttributeInfo.java 2000/04/26 05:22:31 1.1.1.1
+++ TagAttributeInfo.java 2000/08/24 21:05:29 1.1.1.1.4.1
@@ -56,9 +56,10 @@
package javax.servlet.jsp.tagext;
/**
- * Information on Tag Attributes;
- * this class is instantiated from the Tag Library Descriptor file (TLD).
+ * Information on the attributes of a Tag, available at translation time.
+ * This class is instantiated from the Tag Library Descriptor file (TLD).
*
+ * <p>
* Only the information needed to generate code is included here. Other information
* like SCHEMA for validation belongs elsewhere.
*/
@@ -73,15 +74,15 @@
/**
* Constructor for TagAttributeInfo.
- * No public constructor; this class is to be instantiated only from the
+ * This class is to be instantiated only from the
* TagLibrary code under request from some JSP code that is parsing a
* TLD (Tag Library Descriptor).
*
* @param name The name of the attribute
+ * @param required If this attribute is required in tag instances
* @param type The name of the type of the attribute
- * @param reqTime Can this attribute hold a request-time Attribute
+ * @param reqTime Whether this attribute hold a request-time Attribute
*/
- // TODO -- add the content descriptor...
public TagAttributeInfo(String name, boolean required,
String type, boolean reqTime)
@@ -93,7 +94,9 @@
}
/**
- * @returns the name of the attribute
+ * The name of this attribute.
+ *
+ * @return the name of the attribute
*/
public String getName() {
@@ -101,7 +104,9 @@
}
/**
- * @returns the type of the attribute
+ * The type (as a String) of this attribute.
+ *
+ * @return the type of the attribute
*/
public String getTypeName() {
@@ -109,7 +114,9 @@
}
/**
- * Can this attribute hold a request-time value?
+ * Whether this attribute can hold a request-time value.
+ *
+ * @return if the attribute can hold a request-time value.
*/
public boolean canBeRequestTime() {
@@ -117,15 +124,20 @@
}
/**
- * Is this required or not?
+ * Whether this attribute is required.
+ *
+ * @return if the attribute is required.
*/
public boolean isRequired() {
return required;
}
/**
- * Convenience method that goes through an array of TagAttributeInfo
+ * Convenience static method that goes through an array of TagAttributeInfo
* objects and looks for "id".
+ *
+ * @param a An array of TagAttributeInfo
+ * @return The TagAttributeInfo reference with name "id"
*/
public static TagAttributeInfo getIdAttribute(TagAttributeInfo a[]) {
for (int i=0; i<a.length; i++) {
1.1.1.1.4.1 +30 -27 jakarta-servletapi/src/share/javax/servlet/jsp/tagext/TagData.java
Index: TagData.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/tagext/TagData.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- TagData.java 2000/04/26 05:22:31 1.1.1.1
+++ TagData.java 2000/08/24 21:05:29 1.1.1.1.4.1
@@ -58,38 +58,35 @@
import java.util.Hashtable;
/**
- * Tag instance attribute(s)/value(s); often this data is fully static in the
- * case where none of the attributes have runtime expresssions as their values.
- * Thus this class is intended to expose an immutable interface to a set of
- * immutable attribute/value pairs.
+ * The (translation-time only) attribute/value information for a tag instance.
*
- * This class is cloneable so implementations can create a static instance
- * and then just clone it before adding the request-time expressions.
+ * <p>
+ * TagData is only used as an argument to the isValid and getVariableInfo
+ * methods of TagExtraInfo, which are invoked at translation time.
*/
public class TagData implements Cloneable {
+
/**
* Distinguished value for an attribute to indicate its value
- * is a request-time expression which is not yet available because
- * this TagData instance is being used at translation-time.
+ * is a request-time expression (which is not yet available because
+ * TagData instances are used at translation-time).
*/
- // TODO -- revisit clonable; do we need a clone() method?
- // TODO -- Should we just use an array?
- // TODO -- should there be a factory?
public static final Object REQUEST_TIME_VALUE = new Object();
+
/**
- * Constructor for a TagData
+ * Constructor for TagData.
*
- * For simplicity and speed, we are just using primitive types.
+ * <p>
* A typical constructor may be
- *
+ * <pre>
* static final Object[][] att = {{"connection", "conn0"}, {"id", "query0"}};
* static final TagData td = new TagData(att);
+ * </pre>
*
- * In an implementation that uses the clonable approach sketched
- * above all values must be Strings except for those holding the
+ * All values must be Strings except for those holding the
* distinguished object REQUEST_TIME_VALUE.
* @param atts the static attribute and values. May be null.
@@ -109,18 +106,20 @@
}
/**
- * Constructor for a TagData
+ * Constructor for a TagData.
*
* If you already have the attributes in a hashtable, use this
* constructor.
*
-
+ * @param attrs A hashtable to get the values from.
*/
public TagData(Hashtable attrs) {
this.attributes = attrs;
}
/**
+ * The value of the id attribute, if available.
+ *
* @return the value of the id attribute or null
*/
@@ -129,20 +128,22 @@
}
/**
- * @return the attribute's value object. Returns the
- * distinguished object REQUEST_TIME_VALUE if the value is
- * request time and we are using TagData at translation time.
- * Returns null if the attribute is not set.
+ * The value of the attribute.
+ * Returns the distinguished object REQUEST_TIME_VALUE if
+ * the value is request time. Returns null if the attribute is not set.
+ *
+ * @return the attribute's value object
*/
- // TODO -- means we cannot distinguish from an unset attribute an
- // TODO -- one that is set to null.
public Object getAttribute(String attName) {
return attributes.get(attName);
}
/**
- * Set the value of this attribute to be
+ * Set the value of an attribute.
+ *
+ * @param attName the name of the attribute
+ * @param value the value.
*/
public void setAttribute(String attName,
Object value) {
@@ -150,8 +151,9 @@
}
/**
- * @return the attribute value string
+ * Get the value for a given attribute.
*
+ * @return the attribute value string
* @throw ClassCastException if attribute value is not a String
*/
@@ -165,7 +167,8 @@
}
/**
- * Enumerates the attributes
+ * Enumerates the attributes.
+ *
*@return An enumeration of the attributes in a TagData
*/
public java.util.Enumeration getAttributes() {
1.1.1.1.4.1 +34 -12 jakarta-servletapi/src/share/javax/servlet/jsp/tagext/TagExtraInfo.java
Index: TagExtraInfo.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/tagext/TagExtraInfo.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- TagExtraInfo.java 2000/04/26 05:22:31 1.1.1.1
+++ TagExtraInfo.java 2000/08/24 21:05:30 1.1.1.1.4.1
@@ -56,32 +56,54 @@
package javax.servlet.jsp.tagext;
/**
- * Extra Tag Information for a Custom Tag;
- * this class is mentioned in the Tag Library Descriptor file (TLD).
+ * Optional class provided by the tag library author to describe additional
+ * translation-time information not described in the TLD.
+ * The TagExtraInfo class is mentioned in the Tag Library Descriptor file (TLD).
*
+ * <p>
* This class must be used:
- * - if the tag defines any scripting variables
- * - if the tag wants to provide translation-time validation of the tag
+ * <ul>
+ * <li> if the tag defines any scripting variables
+ * <li> if the tag wants to provide translation-time validation of the tag
* attributes.
+ * </ul>
*
+ * <p>
+ * It is the responsibility of the JSP translator that the initial value
+ * to be returned by calls to getTagInfo() corresponds to a TagInfo
+ * object for the tag being translated. If an explicit call to
+ * setTagInfo() is done, then the object passed will be returned in
+ * subsequent calls to getTagInfo().
+ *
+ * <p>
+ * The only way to affect the value returned by getTagInfo()
+ * is through a setTagInfo() call, and thus, TagExtraInfo.setTagInfo() is
+ * to be called by the JSP translator, with a TagInfo object that
+ * corresponds to the tag being translated. The call should happen before
+ * any invocation on isValid() and before any invocation on
+ * getVariableInfo().
*/
public abstract class TagExtraInfo {
/**
- * information on scripting variables defined by this tag
+ * information on scripting variables defined by the tag associated with
+ * this TagExtraInfo instance.
+ * Request-time attributes are indicated as such in the TagData parameter.
*
- * @param data The translation-time TagData instance.
+ * @param data The TagData instance.
+ * @return An array of VariableInfo data.
*/
public VariableInfo[] getVariableInfo(TagData data) {
return new VariableInfo[0];
}
/**
- * Translation-time validation of the attributes. The argument is a
- * translation-time, so request-time attributes are indicated as such.
+ * Translation-time validation of the attributes.
+ * Request-time attributes are indicated as such in the TagData parameter.
*
- * @param data The translation-time TagData instance.
+ * @param data The TagData instance.
+ * @return Whether this tag instance is valid.
*/
public boolean isValid(TagData data) {
@@ -89,7 +111,7 @@
}
/**
- * Set the TagInfo for this class
+ * Set the TagInfo for this class.
*
* @param tagInfo The TagInfo this instance is extending
*/
@@ -98,9 +120,9 @@
}
/**
- * Get the TagInfo for this class
+ * Get the TagInfo for this class.
*
- * @returns the taginfo instnace this instance is extending
+ * @return the taginfo instance this instance is extending
*/
public final TagInfo getTagInfo() {
return tagInfo;
1.1.1.1.4.1 +39 -16 jakarta-servletapi/src/share/javax/servlet/jsp/tagext/TagInfo.java
Index: TagInfo.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/tagext/TagInfo.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- TagInfo.java 2000/04/26 05:22:32 1.1.1.1
+++ TagInfo.java 2000/08/24 21:05:30 1.1.1.1.4.1
@@ -57,8 +57,8 @@
/**
* Tag information for a tag in a Tag Library;
- * this class is instantiated from the Tag Library Descriptor file (TLD).
- *
+ * This class is instantiated from the Tag Library Descriptor file (TLD)
+ * and is available only at translation time.
*/
public class TagInfo {
@@ -84,8 +84,8 @@
/**
* Constructor for TagInfo.
- * No public constructor; this class is to be instantiated only from the
- * TagLibrary code under request from some JSP code that is parsing a
+ * This class is to be instantiated only from the TagLibrary code
+ * under request from some JSP code that is parsing a
* TLD (Tag Library Descriptor).
*
* @param tagName The name of this tag
@@ -118,7 +118,9 @@
}
/**
- * Tag name
+ * The name of the Tag.
+ *
+ * @return The (short) name of the tag.
*/
public String getTagName() {
@@ -126,7 +128,12 @@
}
/**
- * A null return means no information on attributes
+ * Attribute information (in the TLD) on this tag.
+ * The return is an array describing the attributes of this tag, as
+ * indicated in the TLD.
+ * A null return means no attributes.
+ *
+ * @return The array of TagAttributeInfo for this tag.
*/
public TagAttributeInfo[] getAttributes() {
@@ -134,11 +141,14 @@
}
/**
- * Information on the object created by this tag at runtime.
- * Null means no such object created.
- *
+ * Information on the scripting objects created by this tag at runtime.
+ * This is a convenience method on the associated TagExtraInfo class.
+ * <p>
* Default is null if the tag has no "id" attribute,
* otherwise, {"id", Object}
+ *
+ * @param data TagData describing this action.
+ * @return Array of VariableInfo elements.
*/
public VariableInfo[] getVariableInfo(TagData data) {
@@ -150,10 +160,11 @@
}
/**
- * Translation-time validation of the attributes. The argument is a
- * translation-time, so request-time attributes are indicated as such.
+ * Translation-time validation of the attributes.
+ * This is a convenience method on the associated TagExtraInfo class.
*
* @param data The translation-time TagData instance.
+ * @return Whether the data is valid.
*/
@@ -167,15 +178,19 @@
/**
- The instance (if any) for extra tag information
- */
+ * The instance (if any) for extra tag information
+ *
+ * @return The TagExtraInfo instance, if any.
+ */
public TagExtraInfo getTagExtraInfo() {
return tagExtraInfo;
}
/**
- * Name of the class that provides the (run-time handler for this tag
+ * Name of the class that provides the handler for this tag.
+ *
+ * @return The name of the tag handler class.
*/
public String getTagClassName() {
@@ -184,19 +199,27 @@
/**
- * @return the body content (hint) string
+ * The bodycontent information for this tag.
+ *
+ * @return the body content string.
*/
public String getBodyContent() { return bodyContent; }
+
/**
+ * The information string for the tag.
+ *
* @return the info string
*/
public String getInfoString() { return infoString; }
+
/**
- * @return the tab library instance we belong to
+ * The instance of TabLibraryInfo we belong to.
+ *
+ * @return the tab library instance we belong to.
*/
public TagLibraryInfo getTagLibrary() { return tagLibrary; }
1.1.1.1.4.1 +38 -13 jakarta-servletapi/src/share/javax/servlet/jsp/tagext/TagLibraryInfo.java
Index: TagLibraryInfo.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/tagext/TagLibraryInfo.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- TagLibraryInfo.java 2000/04/26 05:22:32 1.1.1.1
+++ TagLibraryInfo.java 2000/08/24 21:05:30 1.1.1.1.4.1
@@ -62,14 +62,14 @@
import java.io.InputStream;
/**
- * Information on the Tag Library;
- * this class is instantiated from the Tag Library Descriptor file (TLD).
+ * Information available at translation-time on a Tag Library.
+ * This class is instantiated from the Tag Library Descriptor file (TLD).
*/
abstract public class TagLibraryInfo {
/**
- * Constructor
+ * Constructor.
*
* This will invoke the constructors for TagInfo, and TagAttributeInfo
* after parsing the TLD file.
@@ -83,10 +83,11 @@
this.uri = uri;
}
- // TODO -- want a package private constructor with data spelled out?
/**
- * @return the URI from the <%@ taglib directive for this library
+ * The value of the uri attribute from the <%@ taglib directive for this library.
+ *
+ * @returns the value of the uri attribute
*/
public String getURI() {
@@ -94,7 +95,9 @@
}
/**
- * @return the prefix assigned to this taglib from the <%taglib directive
+ * The prefix assigned to this taglib from the <%taglib directive
+ *
+ * @returns the prefix assigned to this taglib from the <%taglib directive
*/
public String getPrefixString() {
@@ -104,46 +107,68 @@
// ==== methods using the TLD data =======
/**
- * @return the prefered short name for the library
+ * The prefered short name (prefix) as indicated in the TLD.
+ * This may be used by authoring tools as the prefered prefix
+ * to use when creating an include directive for this library.
+ *
+ * @returns the prefered short name for the library
*/
public String getShortName() {
return shortname;
}
/**
- * @return a reliable URN to a TLD like this
+ * The "reliable" URN indicated in the TLD.
+ * This may be used by authoring tools as a global identifier (the uri attribute)
+ * to use when creating an include directive for this library.
+ *
+ * @returns a reliable URN to a TLD like this
*/
public String getReliableURN() {
return urn;
}
+
/**
- * @return the info string for this tag lib
+ * Information (documentation) for this TLD.
+ *
+ * @returns the info string for this tag lib
*/
public String getInfoString() {
return info;
}
+
/**
- * The required version.
- * TODO -- minimal?
+ * A string describing the required version of the JSP container.
+ *
+ * @returns the (minimal) required version of the JSP container.
+ * @seealso JspEngineInfo.
*/
public String getRequiredVersion() {
return jspversion;
}
+
/**
- * @return the tags defined in this tag lib
+ * An array describing the tags that are defined in this tag library.
+ *
+ * @returns the tags defined in this tag lib
*/
public TagInfo[] getTags() {
return tags;
}
+
/**
- * Get the TagInfo for a given tag name
+ * Get the TagInfo for a given tag name, looking through all the
+ * tags in this tag library.
+ *
+ * @param shortname The short name (no prefix) of the tag
+ * @returns the TagInfo for that tag.
*/
public TagInfo getTag(String shortname) {
1.1.1.1.4.1 +76 -43 jakarta-servletapi/src/share/javax/servlet/jsp/tagext/TagSupport.java
Index: TagSupport.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/tagext/TagSupport.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- TagSupport.java 2000/04/26 05:22:32 1.1.1.1
+++ TagSupport.java 2000/08/24 21:05:31 1.1.1.1.4.1
@@ -66,18 +66,31 @@
import java.util.Enumeration;
/**
- * Actions in a Tag Library are defined through subclasses of Tag.
+ * A base class for defnining new tag handlers implementing Tag.
+ *
+ * <p> The TagSupport class is a utility class intended to be used as
+ * the base class for new tag handlers. The TagSupport class
+ * implements the Tag and IterationTag interfaces and adds additional
+ * convenience methods including getter methods for the properties in
+ * Tag. TagSupport has one static method that is included to
+ * facilitate coordination among cooperating tags.
+ *
+ * <p> Many tag handlers will extend TagSupport and only redefine a
+ * few tags.
*/
-public class TagSupport implements Tag, Serializable {
+public class TagSupport implements IterationTag, Serializable {
/**
* Find the instance of a given class type that is closest to a given
* instance.
- * This class is used for coordination among cooperating tags.
- *
- * @param the subclass of Tag or interface to be matched
- * @return the nearest ancestor that implements the interface
+ * This method uses the getParent method from the Tag
+ * interface.
+ * This method is used for coordination among cooperating tags.
+ *
+ * @param from The instance from where to start looking.
+ * @param klass The subclass of Tag or interface to be matched
+ * @returns the nearest ancestor that implements the interface
* or is an instance of the class specified
*/
@@ -113,33 +126,15 @@
*
* This constructor is called by the code generated by the JSP
* translator.
- *
- * @param libraryPrefix The namespace prefix used for this library.
- * For example "jsp:".
- * @param tagName The name of the element or yag, for example "useBean"
*/
public TagSupport() { }
- /**
- * doStartTag(), doEndTag() are most basic.
- * setBodyOut(), doBeforeBody(), and doAfterBody() deal with body
- *
- * In many cases not all of them are redefined.
- */
-
- // Actions for basic start/end processing.
-
/**
- * Process the start tag for this instance.
- *
- * The doStartTag() method assumes that all setter methods have been
- * invoked before.
+ * Default processing of the start tag, returning SKIP_BODY.
*
- * When this method is invoked, the body has not yet been invoked.
- *
- * @returns EVAL_BODY_INCLUDE if the tag wants to process body, SKIP_BODY if it
- * does ont want to process it.
+ * @returns SKIP_BODY
+ * @see Tag#doStartTag()
*/
public int doStartTag() throws JspException {
@@ -147,29 +142,51 @@
}
/**
- * Process the end tag. This method will be called on all Tag objects.
+ * Default processing of the end tag returning EVAL_PAGE.
*
- * All instance state associated with this instance must be reset.
+ * @returns EVAL_PAGE
+ * @see Tag#doEndTag()
*/
public int doEndTag() throws JspException {
return EVAL_PAGE;
}
+
/**
- * release() called after doEndTag() to reset state
+ * Default processing for a body
+ *
+ * @return SKIP_BODY
+ * @see IterationTag#doAfterBody()
*/
-
- public void release() {
- parent = null;
+
+ public int doAfterBody() throws JspException {
+ return SKIP_BODY;
}
+ // Actions related to body evaluation
+
/**
- * Methods to access state
+ * Reset all custom (i.e. not parent, not pageContext) attributes to their
+ * default values
*/
+ public void resetCustomAttributes() { }
+
/**
+ * Release state.
+ * @see Tag#release()
+ */
+
+ public void release() {
+ parent = null;
+ }
+
+ /**
* Set the nesting tag of this tag.
+ * @see Tag#setParent
+ *
+ * @param t The parent Tag.
*/
public void setParent(Tag t) {
@@ -177,9 +194,10 @@
}
/**
- * The Tag instance enclosing this tag instance.
+ * The Tag instance most closely enclosing this tag instance.
+ * @see Tag#getParent()
*
- * @return the parent tag instance or null
+ * @returns the parent tag instance or null
*/
public Tag getParent() {
@@ -187,7 +205,9 @@
}
/**
- * Set the id attribute
+ * Set the id attribute for this tag.
+ *
+ * @param id The String for the id.
*/
public void setId(String id) {
@@ -197,7 +217,7 @@
/**
* The value of the id attribute of this tag; or null.
*
- * @return the value of the id attribute, or null
+ * @returns the value of the id attribute, or null
*/
public String getId() {
@@ -205,7 +225,10 @@
}
/**
- * set the page context
+ * Set the page context.
+ * @see Tag#setPageContext
+ *
+ * @param pageContenxt The PageContext.
*/
public void setPageContext(PageContext pageContext) {
@@ -213,7 +236,10 @@
}
/**
- * Set a value
+ * Associate a value with a String key.
+ *
+ * @param k The key String.
+ * @param o The value to associate.
*/
public void setValue(String k, Object o) {
@@ -224,7 +250,10 @@
}
/**
- * Get a value
+ * Get a the value associated with a key.
+ *
+ * @param k The string key.
+ * @returns The value associated with the key, or null.
*/
public Object getValue(String k) {
@@ -236,7 +265,9 @@
}
/**
- * Remove a value
+ * Remove a value associated with a key.
+ *
+ * @param k The string key.
*/
public void removeValue(String k) {
@@ -246,7 +277,9 @@
}
/**
- * Enumerate the values
+ * Enumerate the values kept by this tag handler.
+ *
+ * @returns An enumeration of all the values set.
*/
public Enumeration getValues() {
1.1.1.1.4.1 +105 -9 jakarta-servletapi/src/share/javax/servlet/jsp/tagext/VariableInfo.java
Index: VariableInfo.java
===================================================================
RCS file: /home/cvs/jakarta-servletapi/src/share/javax/servlet/jsp/tagext/VariableInfo.java,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.4.1
diff -u -r1.1.1.1 -r1.1.1.1.4.1
--- VariableInfo.java 2000/04/26 05:22:32 1.1.1.1
+++ VariableInfo.java 2000/08/24 21:05:31 1.1.1.1.4.1
@@ -57,24 +57,120 @@
/**
* Information on the scripting variables that are created/modified by
- * a tag (at run-time); this information is provided by TagExtraInfo
+ * a tag (at run-time). This information is provided by TagExtraInfo
* classes and it is used by the translation phase of JSP.
*
+ * <p>
+ * Scripting variables generated by a custom action may have scope
+ * page, request, session, and application.
+ *
+ * <p>
+ * The class name (VariableInfo.getClassName) in the returned objects
+ * are used to determine the types of the scripting variables.
+ * Because of this, a custom action cannot create a scripting variable
+ * of a primitive type. The workaround is to use "boxed"
+ * types.
+ *
+ * <p>
+ * The class name may be a Fully Qualified Class Name, or a short
+ * class name.
+ *
+ * <p>
+ * If a Fully Qualified Class Name is provided, it should refer to a
+ * class that should be in the CLASSPATH for the Web Application (see
+ * Servlet 2.3 specification - essentially it is WEB-INF/lib and
+ * WEB-INF/classes). Failure to be so will lead to a translation-time
+ * error.
+ *
+ * <p>
+ * If a short class name is given in the VariableInfo objects, then
+ * the class name must be that of a public class in the context of the
+ * import directives of the page where the custom action appears (will
+ * check if there is a JLS verbiage to refer to). The class must also
+ * be in the CLASSPATH for the Web Application (see Servlet 2.3
+ * specification - essentially it is WEB-INF/lib and
+ * WEB-INF/classes). Failure to be so will lead to a translation-time
+ * error.
+ *
+ * <p><B>Usage Comments</B>
+ * <p>
+ * Frequently a fully qualified class name will refer to a class that
+ * is known to the tag library and thus, delivered in the same JAR
+ * file as the tag handlers. In almost other remaining cases it will
+ * refer to a class that is in the platform on which the JSP processor
+ * is build (like J2EE). Using fully qualified class names in this
+ * manner makes the usage relatively resistant to configuration
+ * errors.
+ *
+ * <p>
+ * A short name is usually generated by the tag library based on some
+ * attributes passed through from the custom action user (the author),
+ * and it is thus less robust: for instance a missing import directive
+ * in the referring JSP page will lead to an invalid short name class
+ * and a translation error.
+ *
+ * <p><B>Synchronization Protocol</B>
+ *
+ * <p>
+ * The result of the invocation on getVariableInfo is an array of
+ * VariableInfo objects. Each such object describes a scripting
+ * variable by providing its name, its type, whether the variable is
+ * new or not, and what its scope is. Scope is best described through
+ * a picture:.
+ *
+ * <p>
+ * <IMG src="doc-images/VariableInfo-1.gif"/>
+ *
+ *<p>
+ * The defined values for scope are:
+ *
+ * <ul>
+ * <li> NESTED, if the scripting variable is available between
+ * the start tag and the end tag of the action that defines it.
+ * <li>
+ * AT_BEGIN, if the scripting variable is available from the start tag
+ * of the action that defines it until the end of the page.
+ * <li> AT_END, if the scripting variable is available after the end tag
+ * of the action that defines it until the end of the page.
+ * </ul>
+ *
+ * The scope value for a variable implies what methods may affect its
+ * value and thus, in lack of additional information, where
+ * synchronization is needed:
+ *
+ * <ul>
+ * <li>
+ * for NESTED, after doInitBody and doAfterBody for a tag handler implementing
+ * BodyTag, and after doStartTag otherwise.
+ * <li>
+ * for AT_BEGIN, after doInitBody, doAfterBody, and doEndTag
+ * for a tag handler implementing BodyTag, and doStartTag and doEndTag otherwise.
+ * <li>
+ * for AT_END, after doEndTag method.
+ * </ul>
+ *
+ * <p><B>Variable Information in the TLD</B>
+ * <p>
+ * Scripting variable information can also be encoded directly for most cases
+ * into the Tag Library Descriptor using the <variable> subelement of the
+ * <tag> element. See the JSP specification.
*/
public class VariableInfo {
+
/**
- * Different types of scope for an scripting variable introduced
- * by this action
- *
- * <pre>
- * NESTED ==> variable is visible only within the start/end tags
- * AT_BEGIN ==> variable is visible after start tag
- * AT_END ==> variable is visible after end tag
- * </pre>
+ *Scope information that scripting variable is visible only within the start/end tags
*/
public static final int NESTED = 0;
+
+ /**
+ * Scope information that scripting variable is visible after start tag
+ */
public static final int AT_BEGIN = 1;
+
+ /**
+ * Scope information that scripting variable is visible after end tag
+ */
public static final int AT_END = 2;
No revision
No revision
1.1.2.1 +116 -0 jakarta-servletapi/src/share/javax/servlet/jsp/tagext/Attic/IterationTag.java
1.1.2.1 +77 -0 jakarta-servletapi/src/share/javax/servlet/jsp/tagext/Attic/PageInfo.java
1.1.2.1 +109 -0 jakarta-servletapi/src/share/javax/servlet/jsp/tagext/Attic/TagLibraryValidator.java