Some Frequently Asked Questions (FAQ) on Tomcat
-----------------------------------------------

Q: I am getting a 404 Error, what does it mean?

A: In simple terms, it means the server was not able to locate 
   the resource you requested. This can occur because of five
   reasons:

   * One, the URL you typed was wrong or has a typo.
   * Two, the URL you requested could not be resolved with 
     the current "docBase". If you are trying to run your own 
     "web-application" please read  the questions related to 
     "installing your own web-application" in this FAQ.
   * Three, you're using JDK 1.1.x on a Windows platform. It's
     a known bug (see Readme) that the server doesn't serve files
     in this configuration. Use JDK 1.2.x instead.
   * Four, on a Windows platform you have installed Tomcat in
     a directory with a path part longer than 8 characters, e.g.
     C:\Program Files\jakarta, and run the "startup" script from
     a command tool after you have cd'd to the directory using
     the short form of the name, e.g.

      > cd C:\Progra~1\jakarta
      > startup

     If you cd using the long name it works fine, e.g.

      > cd "C:\Program Files\jakarta"
      > startup

   * Five, on a Unix platform, you are attempting to access a file
     that is a symbolic link. 

   The last three cases are caused by a test in 
   org.apache.tomcat.core.DefaultServlet to see whether the absolute 
   name of a file equals the canonical name. This test is intended
   to solve a serious security problem, where mixed case or additional
   characters in a file name can get Tomcat to serve the source
   file instead of the processed file for JSP files on a Windows
   platform. This test should be replaced with a solution that doesn't
   have the above side effects.


Q: I am getting a 500 Error, what does it mean?

A: In simple terms, it means that there was some "Internal Server
   Error" while processing your request. You need to study carefully
   the trace at the server window to find out more about the error.

   These errors can occur while translating your jsp source to a 
   servlet. These are translation-time errors and occur mostly because
   of some syntax error in the jsp file or in the generated java file.
   Please use the error-message at the server-window for debugging.

   Errors can also occur at request-time. Again, the information about 
   specific problem/exception can be obtained by looking at the 
   server-side trace.


Q: What do I need in my CLASSPATH?

A: All you need is a correct version of JDK (1.1.x or 1.2). 

   Since the JSP engine also uses 'javac' it needs to be in the CLASSPATH.
   If you are using JDK 1.1.x it will automatically be included. If 
   you are using JDK 1.2 you will need to set JAVA_HOME to the directory
   where JDK is installed or alternately you can put "tools.jar" in your
   CLASSPATH.

   All other classes, jar files that are needed, are put by the startserver
   script and you don't need to worry about them.


Q: Where are the classes for JSPs and Servlets?

A: lib classes:

     tomcat.jar         -- Executable jar for starting Tomcat
     stop-tomcat.jar    -- Executable jar for stopping Tomcat

   lib/common classes

     core_util.jar      -- Utility classes used by apps and container
     jasper-runtime.jar -- JSP Engine runtime classes
     servlet.jar        -- Public APIs for Servlets and JSP
     tomcat_core.jar    -- Tomcat web server core classes

   lib/container classes

     facade22.jar       -- Servlet Engine classes.
     jasper.jar         -- JSP Engine translation classes
     jaxp.jar           -- Public APIs for XML parser interface
     parser.jar         -- Public XML parser reference implementation
     tomcat_modules.jar -- Tomcat module classes
     tomcat_util.jar    -- Utility classes.
     tomcat-startup.jar -- Tomcat start/stop classes


Q: Can I combine these classes with other webservers?

A: The JSP engine uses just the public portion of the Java Servlet 2.2 
   API. In theory, it could run on other servlet engines that support 
   the Servlet 2.2 API but we have not tested this release on any servlet 
   engine other than the one in Tomcat.


Q: Where do I put my jsp sources and beans?

A: If you just want to test JSPs without creating a separate web-application
   you can use the default "example" application. If you want to create
   a new web-application please read "how to install a new web-application?".

   To use the default, put all your JSP source under /examples/jsp, either 
   in the same directory or under a new subdirectory of /examples/jsp (as
   done in the included examples). Put all your beans (class files) under
   /examples/WEB-INF/jsp/beans appropriately (as done for the included 
   beans). The startserver script will automatically add these classes to 
   the CLASSPATH at runtime.

   If your server is already running, you will need to stop and restart it.
   You can invoke your jsps using http://locahost:8080/examples/jsp/yours.jsp


Q: What is a web-application? How can I install a new web-application?

A: A web-application is a collection of resources such as jsps, servlets,
   html files, images, etc. which are mapped to a specific "URI" prefix.

   For example, all the resources related to baseball can be assembled
   into a "baseball" directory and correspondingly all the requests that
   start with "/baseball"  can be mapped to this application.

   A new application can be added to Tomcat by editing server.xml file.
   To add "baseball" application you can make the following additions to 
   the file (at the appropriate place):

   <Context path="/baseball" docBase="<baseball>"
      debug="0" reloadable="true"/>

   Replace <baseball> with an absolute path to the "baseball" directory,
   or a relative path that is relative to the Tomcat home directory.

   Please read "server.xml" for more details.

   In addition, thanks to the AutoSetup interceptor, you may create or
   copy the "baseball" directory to the "webapps" directory found under
   the Tomcat home directory.  When placed there, it will be served
   automcatically with the default settings.  A <Context ... /> entry
   in the server.xml is not required unless you want to override the
   default settings.

   a) To install servlets within a web-application, you can do the following:

   * Once a servlet has been compiled, it can be added to Tomcat by:
     determine which "web application" context you'd like to add the servlet 
     to

		add the servlet class file to the
		WEBAPP/WEB-INF/classes directory

   * In order to define a name and init params for the newly installed 
     servlet you need to also:

		register the servlet with a <servlet> element in the
		WEBAPP/WEB-INF/web.xml file

		you can optionally map your servlet
		to uri requests relative to the context
		within it is located by adding a <servlet-mapping>
		element in the WEBAPP/WEB-INF/web.xml
		file
		
    * And finally restart the server

	You can access your new servlet via a URI similiar
	to the following:

		http://localhost:8080/WEBAPP/servlet/SERVLET-NAME

	If you've associated a URI path mapping to your
	servlet you can access it via a URI similiar to the
	following:

		http://localhost:8080/WEBAPP/foo.EXTENSION

			- or -

		http://localhost:8080/WEBAPP/MAP-PATH

	where:

		WEBAPP = the web-application URI name
		SERVLET-NAME = the base name of a servlet
		EXTENSION = a file time extension
		MAP-PATH = associated URI MAP path

   b) To install jsps and beans within a web-application you can do 
      the following:

   * Put the jsp sources in any directory under /WEBAPP.
   
   * Make sure that the compiled beans are in the CLASSPATH. This can
     be done either by setting the CLASSPATH manually or by editing 
     the startup script.

   * And finally restart the server.

     You can invoke your new jsp via a URI similar to the following:

     http://localhost:8080/WEBAPP/yourfile.jsp


Q: How are the URIs mapped at the server?

A: First, the web-server will match the beginning of the requested URI
   against the prefixes of all contexts (web-applications). If no context 
   matches, it will use the default context instead. 


Q: What do different init parameters for the JSP engine mean?

   * keepgenerated: 
        Whether to keep the generated java file or not. Can take a
        value of true/false. If value is true, then the generated files 
        are kept, otherwise they are deleted. The default is true.

   * scratchdir: 
	The work dir which will be created for storing all the
	generated code. This can be set to any dir. That directory will be 
	created under the docbase.

   * largefile: 
	Can take a value of true/false. If the file is really large then 
	all the static html is stored is a separate data file if the value 
	of this param is set to true. If true, this setting overrides
        the mappedfile param. The default is false.

   * mappedfile: 
	Can take a value of true/false. If you prefer each line of static
        html be output separately, set this parameter true.  If largefile
        is set true, this param is ignored.  If neither largefile or
        mappedfile is true, the static html is output in blocks up to 32K
        in length. The default is false.

   * sendErrToClient: 
	Can take a value of true/false. If set to true then all
	the compilation/parsing errors will be sent as part of the response 
	to the client. The default is false.

   * ieClassId: 
	This is used with the plugin. This is a particular id that is
	set to activate the plugin. The default value for IE 4 and 5 are 
	set as of now. This is for future use in case the classId for IE 
	changes in the future. 

   * classdebuginfo: 
	Whether to include debugging information in the class file. Can take
        a value of true/false. If the value is true, then class debugging
        information is included in the servlet class file when it is
        compiled. The default is false.


   To set any of these to a value other than the default you need to
   explicitely define the JSP engine servlet and a mapping for the
   .jps extension in WEBAPP/WEB-INF/web.xml, e.g.

    <servlet>
      <servlet-name>
          jsp
      </servlet-name>
      <servlet-class>
          org.apache.jasper.servlet.JspServlet
      </servlet-class>
      <init-param>
          <param-name>
              keepgenerated
          </param-name>
          <param-value>
              true
          </param-value>
      </init-param>
      <init-param>
          <param-name>
              sendErrToClient
          </param-name>
          <param-value>
              true
          </param-value>
      </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>
            jsp
        </servlet-name>
        <url-pattern>
            *.jsp
        </url-pattern>
    </servlet-mapping>


Q. I have a bean with a property whose second letter is capitalized.
   Why won't my JSP page that uses this bean compile?

A. This may not happen often, but can be difficult to determine why.
   The reason is found in the Java Beans specification, where in section
   "8.8 Capitalization of inferred names" it states:

       Thus when we extract a property or event name from the middle of an
       existing Java name, we normally convert the first character to lower
       case. However to support the occasional use of all upper-case names,
       we check if the first two characters of the name are both upper case
       and if so leave it alone.

   This means that if you have a bean with a setter method of "setXLoc",
   then the inferred property is "XLoc", not "xLoc".  If you used this
   bean in a JSP page and you tried to use "xLoc" as the property, it
   would not compile. Using "XLoc" as the property would succeed.

   If you insist on using "xLoc" on the JSP page, you can make this possible
   by creating a BeanInfo class for the bean.  The following is an example
   of such a BeanInfo class for a simple bean called Coordinate.  It
   explicitly defines the properties of the bean to be "xLoc" and "yLoc".

   import java.beans.*;
   public class CoordinateBeanInfo extends SimpleBeanInfo
   {
      private final static Class beanClass = Coordinate.class;

      public PropertyDescriptor[] getPropertyDescriptors()
      {
         try {
            PropertyDescriptor xLocDesc =
               new PropertyDescriptor("xLoc",beanClass,"getXLoc","setXLoc");
            PropertyDescriptor yLocDesc =
               new PropertyDescriptor("yLoc",beanClass,"getYLoc","setYLoc");

            PropertyDescriptor [] pdv = { xLocDesc, yLocDesc };
            return pdv; 
         } catch (IntrospectionException e) {
            throw new Error(e.toString());
         }
      }
   }


Q. Whey I run Tomcat, my JVM gives me segmentation fault of segmentation
   violation errors. Should I be reporting a Tomcat bug?

A. No. This is surely a JVM problem. Possible solutions are to switch to
   another JVM, apply relevant patches to your OS or find out if there are
   any particular environmental settings required.
