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):
Replace 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 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 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
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.
jsp
org.apache.jasper.servlet.JspServlet
keepgenerated
true
sendErrToClient
true
jsp
*.jsp
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());
}
}
}