From: kkolinko Date: Thu, 25 Feb 2010 06:05:55 +0000 (+0000) Subject: updated the JavaDoc X-Git-Url: https://git.internetallee.de/?a=commitdiff_plain;h=4c96b0daab22bdf5f79483c5004683e1d95fb970;p=tomcat7.0 updated the JavaDoc git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@916141 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/java/org/apache/jasper/JspC.java b/java/org/apache/jasper/JspC.java index 37a869518..7d9dd75ea 100644 --- a/java/org/apache/jasper/JspC.java +++ b/java/org/apache/jasper/JspC.java @@ -70,20 +70,17 @@ import org.apache.tools.ant.util.FileUtils; * * It can be used as an Ant task using: * 
- *   <taskdef classname="org.apache.jasper.JspC" name="jasper2" >
+ *   <taskdef classname="org.apache.jasper.JspC" name="jasper" >
  *      <classpath>
  *          <pathelement location="${java.home}/../lib/tools.jar"/>
- *          <fileset dir="${ENV.CATALINA_HOME}/server/lib">
- *              <include name="*.jar"/>
- *          </fileset>
- *          <fileset dir="${ENV.CATALINA_HOME}/common/lib">
+ *          <fileset dir="${ENV.CATALINA_HOME}/lib">
  *              <include name="*.jar"/>
  *          </fileset>
  *          <path refid="myjars"/>
  *       </classpath>
  *  </taskdef>
  *
- *  <jasper2 verbose="0"
+ *  <jasper verbose="0"
  *           package="my.package"
  *           uriroot="${webapps.dir}/${webapp.name}"
  *           webXmlFragment="${build.dir}/generated_web.xml"
@@ -269,6 +266,12 @@ public class JspC implements Options {
         }
     }
 
+    /**
+     * Apply command-line arguments.
+     * 
+     * @param arg
+     *            The arguments
+     */
     public void setArgs(String[] arg) throws JasperException {
         args = arg;
         String tok;
@@ -375,43 +378,76 @@ public class JspC implements Options {
         }
     }
 
+    /**
+     * In JspC this always returns true.
+     * {@inheritDoc}
+     */
     public boolean getKeepGenerated() {
         // isn't this why we are running jspc?
         return true;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public boolean getTrimSpaces() {
         return trimSpaces;
     }
 
+    /**
+     * Sets the option to trim white spaces between directives or actions.
+     */
     public void setTrimSpaces(boolean ts) {
         this.trimSpaces = ts;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public boolean isPoolingEnabled() {
         return poolingEnabled;
     }
 
+    /**
+     * Sets the option to enable the tag handler pooling.
+     */
     public void setPoolingEnabled(boolean poolingEnabled) {
         this.poolingEnabled = poolingEnabled;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public boolean isXpoweredBy() {
         return xpoweredBy;
     }
 
+    /**
+     * Sets the option to enable generation of X-Powered-By response header.
+     */
     public void setXpoweredBy(boolean xpoweredBy) {
         this.xpoweredBy = xpoweredBy;
     }
 
+    /**
+     * In JspC this always returns true.
+     * {@inheritDoc}
+     */
     public boolean getDisplaySourceFragment() {
         return true;
     }
-    
+
+    /**
+     * {@inheritDoc}
+     */
     public boolean getErrorOnUseBeanInvalidClassAttribute() {
         return errorOnUseBeanInvalidClassAttribute;
     }
 
+    /**
+     * Sets the option to issue a compilation error if the class attribute
+     * specified in useBean action is invalid.
+     */
     public void setErrorOnUseBeanInvalidClassAttribute(boolean b) {
         errorOnUseBeanInvalidClassAttribute = b;
     }
@@ -421,7 +457,7 @@ public class JspC implements Options {
     }
 
     /**
-     * Are we supporting HTML mapped servlets?
+     * {@inheritDoc}
      */
     public boolean getMappedFile() {
         return mappedFile;
@@ -432,23 +468,31 @@ public class JspC implements Options {
         return null;
     }
 
+    /**
+     * Sets the option to include debug information in compiled class.
+     */
     public void setClassDebugInfo( boolean b ) {
         classDebugInfo=b;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public boolean getClassDebugInfo() {
         // compile with debug info
         return classDebugInfo;
     }
 
-     /**
-      * @see Options#isCaching()
+    /**
+     * {@inheritDoc}
      */
     public boolean isCaching() {
         return caching;
     }
 
     /**
+     * Sets the option to enable caching.
+     * 
      * @see Options#isCaching()
      */
     public void setCaching(boolean caching) {
@@ -456,57 +500,61 @@ public class JspC implements Options {
     }
 
     /**
-     * @see Options#getCache()
+     * {@inheritDoc}
      */
     public Map getCache() {
         return cache;
     }
 
     /**
-     * Background compilation check intervals in seconds
+     * In JspC this always returns 0.
+     * {@inheritDoc}
      */
     public int getCheckInterval() {
         return 0;
     }
 
     /**
-     * Modification test interval.
+     * In JspC this always returns 0.
+     * {@inheritDoc}
      */
     public int getModificationTestInterval() {
         return 0;
     }
 
     /**
-     * Is Jasper being used in development mode?
+     * In JspC this always returns false.
+     * {@inheritDoc}
      */
     public boolean getDevelopment() {
         return false;
     }
 
     /**
-     * Is the generation of SMAP info for JSR45 debugging suppressed?
+     * {@inheritDoc}
      */
     public boolean isSmapSuppressed() {
         return smapSuppressed;
     }
 
     /**
-     * Set smapSuppressed flag.
+     * Sets smapSuppressed flag.
      */
     public void setSmapSuppressed(boolean smapSuppressed) {
         this.smapSuppressed = smapSuppressed;
     }
 
-    
     /**
-     * Should SMAP info for JSR45 debugging be dumped to a file?
+     * {@inheritDoc}
      */
     public boolean isSmapDumped() {
         return smapDumped;
     }
 
     /**
-     * Set smapSuppressed flag.
+     * Sets smapDumped flag.
+     * 
+     * @see Options#isSmapDumped()
      */
     public void setSmapDumped(boolean smapDumped) {
         this.smapDumped = smapDumped;
@@ -525,10 +573,7 @@ public class JspC implements Options {
     }
 
     /**
-     * Indicates whether text strings are to be generated as char arrays.
-     *
-     * @return true if text strings are to be generated as char arrays, false
-     * otherwise
+     * {@inheritDoc}
      */
     public boolean genStringAsCharArray() {
         return genStringAsCharArray;
@@ -536,24 +581,25 @@ public class JspC implements Options {
 
     /**
      * Sets the class-id value to be sent to Internet Explorer when using
-     *  tags.
-     *
-     * @param ieClassId Class-id value
+     * <jsp:plugin> tags.
+     * 
+     * @param ieClassId
+     *            Class-id value
      */
     public void setIeClassId(String ieClassId) {
         this.ieClassId = ieClassId;
     }
 
     /**
-     * Gets the class-id value that is sent to Internet Explorer when using
-     *  tags.
-     *
-     * @return Class-id value
+     * {@inheritDoc}
      */
     public String getIeClassId() {
         return ieClassId;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public File getScratchDir() {
         return scratchDir;
     }
@@ -569,48 +615,63 @@ public class JspC implements Options {
     }
 
     /**
-     * Compiler to use.
+     * {@inheritDoc}
      */
     public String getCompiler() {
         return compiler;
     }
 
+    /**
+     * Sets the option to determine what compiler to use.
+     * 
+     * @see Options#getCompiler()
+     */
     public void setCompiler(String c) {
         compiler=c;
     }
 
     /**
-     * Compiler class name to use.
+     * {@inheritDoc}
      */
     public String getCompilerClassName() {
         return null;
     }
-    
+
     /**
-     * @see Options#getCompilerTargetVM
+     * {@inheritDoc}
      */
     public String getCompilerTargetVM() {
         return compilerTargetVM;
     }
 
+    /**
+     * Sets the compiler target VM.
+     * 
+     * @see Options#getCompilerTargetVM()
+     */
     public void setCompilerTargetVM(String vm) {
         compilerTargetVM = vm;
     }
 
     /**
-     * @see Options#getCompilerSourceVM()
+     * {@inheritDoc}
      */
      public String getCompilerSourceVM() {
          return compilerSourceVM;
      }
-        
-    /**
-     * @see Options#getCompilerSourceVM()
-     */
+
+     /**
+      * Sets the compiler source VM.
+      * 
+      * @see Options#getCompilerSourceVM()
+      */
     public void setCompilerSourceVM(String vm) {
         compilerSourceVM = vm;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public TldLocationsCache getTldLocationsCache() {
         return tldLocationsCache;
     }
@@ -635,16 +696,26 @@ public class JspC implements Options {
         javaEncoding = encodingName;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public boolean getFork() {
         return false;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public String getClassPath() {
         if( classPath != null )
             return classPath;
         return System.getProperty("java.class.path");
     }
 
+    /**
+     * Sets the classpath used while compiling the servlets generated from JSP
+     * files
+     */
     public void setClassPath(String s) {
         classPath=s;
     }
@@ -676,7 +747,7 @@ public class JspC implements Options {
     }
 
     /**
-     * Sets the project.
+     * Sets the Ant project.
      *
      * @param theProject The project
      */
@@ -685,7 +756,7 @@ public class JspC implements Options {
     }
 
     /**
-     * Returns the project: may be null if not running
+     * Returns the project: may be null if not running
      * inside an Ant project.
      *
      * @return The project
@@ -696,7 +767,7 @@ public class JspC implements Options {
 
     /**
      * Base dir for the webapp. Used to generate class names and resolve
-     * includes
+     * includes.
      */
     public void setUriroot( String s ) {
         if( s==null ) {
@@ -770,6 +841,9 @@ public class JspC implements Options {
         }
     }
 
+    /**
+     * Sets the package name to be used for the generated servlet classes.
+     */
     public void setPackage( String p ) {
         targetPackage=p;
     }
@@ -799,32 +873,59 @@ public class JspC implements Options {
         webxmlLevel=ALL_WEBXML;
     }
 
+    /**
+     * Sets the option to merge generated web.xml fragment into the
+     * WEB-INF/web.xml file of the web application that we were processing.
+     * 
+     * @param b
+     *            true to merge the fragment into the existing
+     *            web.xml file of the processed web application
+     *            ({uriroot}/WEB-INF/web.xml), false to keep the
+     *            generated web.xml fragment
+     */
     public void setAddWebXmlMappings(boolean b) {
         addWebXmlMappings = b;
     }
 
     /**
-     * Set the option that throws an exception in case of a compilation error.
+     * Sets the option that throws an exception in case of a compilation error.
      */
     public void setFailOnError(final boolean b) {
         failOnError = b;
     }
 
+    /**
+     * Returns true if an exception will be thrown in case of a compilation
+     * error.
+     */
     public boolean getFailOnError() {
         return failOnError;
     }
 
     /**
-     * Obtain JSP configuration information specified in web.xml.
+     * {@inheritDoc}
      */
     public JspConfig getJspConfig() {
         return jspConfig;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public TagPluginManager getTagPluginManager() {
         return tagPluginManager;
     }
 
+    /**
+     * Adds servlet declaration and mapping for the JSP page servlet to the
+     * generated web.xml fragment.
+     * 
+     * @param file
+     *            Context-relative path to the JSP file, e.g.
+     *            /index.jsp
+     * @param clctxt
+     *            Compilation context of the servlet
+     */
     public void generateWebMapping( String file, JspCompilationContext clctxt )
         throws IOException
     {
diff --git a/java/org/apache/jasper/Options.java b/java/org/apache/jasper/Options.java
index 3571fee9f..aa0c1c070 100644
--- a/java/org/apache/jasper/Options.java
+++ b/java/org/apache/jasper/Options.java
@@ -86,7 +86,7 @@ public interface Options {
     /**
      * Indicates whether SMAP info for JSR45 debugging should be dumped to a
      * file.
-     * Ignored is suppressSmap() is true
+     * Ignored if suppressSmap() is true.
      */
     public boolean isSmapDumped();
 
@@ -96,7 +96,10 @@ public interface Options {
     public boolean getTrimSpaces();
 
     /**
-     * Class ID for use in the plugin tag when the browser is IE. 
+     * Gets the class-id value that is sent to Internet Explorer when using
+     * <jsp:plugin> tags.
+     *
+     * @return Class-id value
      */
     public String getIeClassId();
 
@@ -113,21 +116,28 @@ public interface Options {
 
     /**
      * Compiler to use.
+     * 
+     * 

+     * If null (the default), the java compiler from Eclipse JDT
+     * project, bundled with Tomcat, will be used. Otherwise, the
+     * javac task from Apache Ant will be used to call an external
+     * java compiler and the value of this option will be passed to it. See
+     * Apache Ant documentation for the possible values.
      */
     public String getCompiler();
 
     /**
-     * The compiler target VM, e.g. 1.1, 1.2, 1.3, 1.4, or 1.5.
+     * The compiler target VM, e.g. 1.1, 1.2, 1.3, 1.4, 1.5 or 1.6.
      */
     public String getCompilerTargetVM();
 
     /**
-     * Compiler source VM, e.g. 1.3, 1.4, or 1.5.
+     * The compiler source VM, e.g. 1.3, 1.4, 1.5 or 1.6.
      */
     public String getCompilerSourceVM();   
 
     /**
-     * Java compiler class to use.
+     * Jasper Java compiler class to use.
      */
     public String getCompilerClassName();   
 
@@ -151,7 +161,11 @@ public interface Options {
     public String getJavaEncoding();
 
     /**
-     * boolean flag to tell Ant whether to fork JSP page compilations.
+     * The boolean flag to tell Ant whether to fork JSP page compilations.
+     * 
+     * 

+     * Is used only when Jasper uses an external java compiler (wrapped through
+     * a javac Apache Ant task).
      */
     public boolean getFork();
 
@@ -171,7 +185,10 @@ public interface Options {
     public TagPluginManager getTagPluginManager();
 
     /**
-     * Are Text strings to be generated as char arrays?
+     * Indicates whether text strings are to be generated as char arrays.
+     * 
+     * @return true if text strings are to be generated as char
+     *         arrays, false otherwise
      */
     public boolean genStringAsCharArray();
     
@@ -186,11 +203,15 @@ public interface Options {
     public boolean isCaching();
     
     /**
-     * The web-application wide cache for the returned TreeNode
-     * by parseXMLDocument in TagLibraryInfoImpl.parseTLD,
-     * if isCaching returns true.
+     * The web-application wide cache for the TagLibraryInfo tag library
+     * descriptors, used if {@link #isCaching()} returns true.
+     * 
+     * 

+     * Using this cache avoids the cost of repeating the parsing of a tag
+     * library descriptor XML file (performed by TagLibraryInfoImpl.parseTLD).
+     * 

      * 
-     * @return the Map(String uri, TreeNode tld) instance.
+     * @return the Map(String uri, TagLibraryInfo tld) instance.
      */
     public Map getCache();