Looking at CATALINA_HOME

The best place to start a discussion of Tomcat’s directory structure is in the default installation directory, commonly called CATALINA_HOME. If you’ve installed Tomcat, then you’ll have an environment variable pointing to this directory. Let’s start by examining the bin directory and all the scripts it contains.

The bin Directory

The bin directory contains many scripts (in Windows they’re called batch files, but the term scripts will do for the sake of brevity) for starting Tomcat in different modes and for stopping Tomcat, a number of utilities, and some Windows-specific executables.

The catalina and catalina.50 (Tomcat 5.0.x Only) Scripts

You can use the catalina script to start and stop the server. In addition, a number of the other scripts in the bin directory call it. catalina.50 does the same job as catalina but has the following command-line parameter removed:

 -Djava.endorsed.dirs="%JAVA_ENDORSED_DIRS%" 

This means you use catalina.50 to start Tomcat without enabling its endorsed mechanism. Therefore, Tomcat won’t load any of the classes in CATALINA_HOME/common/endorsed. You may want to do this to force Web applications to use Java’s default classes. However, none of the other scripts refers to this file; they still use catalina. Tomcat 5.5 doesn’t contain the new script at all. From now on, catalina is the only script that will be referenced.

You can use it to start Tomcat in a variety of modes. For example, you can start it with or without debugging, with or without a security manager, and in embedded mode to use it as part of a bigger application.

The catalina script has a number of options associated with it, as described in Table 3-1.

Table 3-1: The Options for the catalina Script

Option

Description

debug

Runs Tomcat in a debugger.

debug -security

Runs Tomcat in a debugger with the security manager.

jpda start

Runs Tomcat in the Java Platform Debugger Architecture (JPDA) debugger. This API allows a developer to write custom debugging applications.

run

Runs Tomcat in the current window. This option is useful for debugging startup issues because you can see any error messages without the window vanishing.

run -security

Runs Tomcat in the current window with the security manager.

start

Runs Tomcat in a new window.

start -security

Runs Tomcat in a new window with the security manager.

stop

Stops Tomcat.

version

Shows the version of Tomcat.

The cpappend Script

Other scripts use the cpappend script to create the classpath dynamically before starting the server. You can override the setting provided here to allow each user to have personalized configuration files for the same server installation, whether for different instances of the server running at the same time or for a development environment for nonconcurrent users. This means each user can configure the server without affecting the work of other users.

The digest Script

You can use the digest script to create digested passwords. This is a particularly useful feature if you’re using Tomcat’s security features and want to implement container-managed security. By digesting a user’s password, you make it harder for someone to obtain it, especially if you’re using the file-based version of container-managed security. Plain-text passwords in text files are very vulnerable. Digesting a password doesn’t mean that the password can’t be discovered, but it does make it more difficult. Chapter 12 covers container-managed security.

The following is an example of digesting a password with the MD5 algorithm:

 > digest -a md5 tomcat 

The -a switch specifies the algorithm to use and is mandatory. The following is the result, with the clear-text password followed by a colon and then the digested password:

 tomcat:1b359d8753858b55befa0441067aaed3 

The digest script also supports the SHA algorithm, like so:

 > digest -a sha tomcat  tomcat:536c0b339345616c1b33caf454454d8b8a190d6c 

The service Script

The service script is a Windows-only script. You can use it to install and remove Tomcat as an NT service. Table 3-2 describes the options.

Table 3-2: The Options for Running the service Script

Option

Description

install

Installs Tomcat as a service called Tomcat5 unless an alternative name is given

remove

Removes the Tomcat service called Tomcat5 unless an alternative name is given

The following is an example of installing a service called TomcatServ and then removing it:

 service install TomcatServ  service remove TomcatServ 

The setclasspath Script

The catalina script calls the setclasspath script to check that all the necessary binaries, such as the Java compiler, are on the system, to set any Java options that have been specified, and to set its classpath.

The startup and shutdown Scripts

You can use the startup and shutdown scripts to start and stop the server, just as you could use the catalina script. However, in this case you don’t have to specify any command-line options, so you can create shortcuts to start and stop Tomcat.

The startup-using-launcher and shutdown-using-launcher Scripts (Tomcat 5.0.x Only)

You can use the startup-using-launcher and shutdown-using-launcher scripts to start and stop the server using Ant’s launcher mechanism. The catalina.xml file in the bin directory is used as the Ant project file. For this to work, you must place the ANT_HOME/lib/ant-launcher.jar file in your path. Note that this isn’t the classpath, because the ant-launcher.jar file is considered an executable in this case.

Windows users should note that they may have to change the shutdown-using-launcher.bat file as follows for the shutdown command to work. Delete the following bold line:

 rem %0 must have been found by DOS using the %PATH% so we assume that  rem setenv.bat will also be found in the %PATH%  call setenv.bat  goto doneSetenv 

However, in most cases the script will complete its execution with an error message as follows:

 'setenv.bat' is not recognized as an internal or external command,  operable program or batch file. 

The tomcat5 Windows Executable

You can use the tomcat5 executable to run the server if it’s installed as an NT service. You can install Tomcat as a service either when you first install Tomcat, as described in the previous chapter, or using the service.bat file as described earlier in this chapter.

Note that the name of this executable must be the same as that of the service you want to start. So, if you install the service as TomcatServ, you must rename this file TomcatServ.exe if you want to use its services.

The tomcat5w Windows Executable

You can use the tomcat5w executable to run the Tomcat Properties box if Tomcat is installed as a service. Chapter 2 described this utility. You can use it to start and stop the service and set other options.

Note that the name of this executable must be the same as that of the service you want to start, with a w appended. So, if you install the service as TomcatServ, you must rename this file TomcatServw.exe if you want to use its services.

The tool-wrapper and tool-wrapper-using-launcher (Tomcat 5.0.x Only) Scripts

This script allows command-line tools to be called in the same environment as Tomcat so that they have a common set of references. For example, command-line analysis tools may need to run within the same environment as Tomcat to identify problems that are specific to Tomcat. If the classpath for the analysis tool isn’t the same as for the server, then obviously classpath issues can’t be identified, and so on.

The same instructions apply for the launcher version of this script as for the startup and shutdown scripts described previously. Windows users should remove the line that called setenv.bat.

The version Script

The version script calls the version option of the catalina script and produces the same results.

The common Directory

The common directory contains three subdirectories: classes, endorsed, and lib. Tomcat 5.5 also has the i18n directory. Classes in the subdirectories of common will be available to Tomcat and all the Web applications running on the server. Common contents of these directories, bar the defaults that come with Tomcat, will be database drivers for serverwide data sources.

You should place class files in the classes folder and utility Java archive (JAR) files (that is, packaged classes and supporting resources) in lib. Never place application-specific classes in either of these directories. The endorsed directory is a special case for working with JDK 1.4 and later.

JDK 1.4 (and later JDKs) comes packaged with a number of APIs, the most important of which, from your point of view, are XML parsers. It used to be the case that to change the systemwide XML parser you simply dropped the new parser’s JAR files into common/lib. However, the class-loading mechanism always prefers the JDK’s XML parser to any other XML parser in the classpath. The good news is that the JDK allows you to override this setting, and Tomcat does so by providing the endorsed directory and the following switch to the startup command in the bin/catalina script (though not the catalina.50 script for Tomcat 5.0.x, as explained previously):

 -Djava.endorsed.dirs="%JAVA_ENDORSED_DIRS%" 

You can set the JAVA_ENDORSED_DIRS variable in the bin/setclasspath script.

If you place JAR files here, they will be used by the class loader in preference to the JDK’s classes and will be available to all Web applications running on the server.

The Tomcat 5.5 i18n directory contains optional internationalization messages that Tomcat uses to customize its output when dealing with browsers from a country other than your own. They can be removed if you don’t require them.

The conf Directory

The conf directory contains the following Tomcat configuration files:

  • catalina.policy sets up the necessary permissions for Catalina when it’s run within the context of a security manager.

  • catalina.properties sets the locations of the various class loader directories. The defaults are the common, server, and shared directories and their subdirectories. The settings in this file determine which classes are available to all Web applications and which classes are available to Tomcat. In other words, these settings configure the classpath of Tomcat and all Web applications.

  • context.xml is a Tomcat 5.5–only file that sets the defaults for individual contexts.

  • jk2.properties sets the properties for the Tomcat connector that connects to an external Web server. You’ll see more of this in Chapter 9.

  • server.xml is the main configuration file for Tomcat and is discussed in detail in Chapter 4. You use it to configure everything from the shutdown command to logging, filtering, connections to other Web servers, the port and host on which the server is running, and the location of each Web application’s files.

  • server-minimal.xml is a minimal version of server.xml.

  • tomcat-users.xml is the default user database for container-managed authentication. You can change the name and location of the file in server.xml. You’ll see more on this mechanism in Chapter 4.

  • web.xml is the default deployment descriptor for all Web applications. Tomcat processes it before processing the web.xml files in the server’s Web applications.

The Subdirectories of the conf Directory

If you have to configure a Web application context, you should place the XML configuration file for that context in the conf/[Service_name]/[Host_name] subdirectory.

Tomcat 5.5 also allows you to configure host-level context defaults by placing the context.xml file in conf/[Service_name]/[Host_name]. This is analogous to the context.xml file described in the previous section. You’ll see how to do all this in Chapter 5.

The logs Directory

The logs directory is the default location for application log files. The default Tomcat 5.0.x installation generates time-stamped logs for the localhost host (the default home of the server). You can easily configure logs for each component of the server using logger components in conf/server.xml. Tomcat 5.5 uses a different mechanism that you’ll learn about in Chapter 4.

You may have to schedule housekeeping tasks to ensure that the size of the logs directory doesn’t grow out of hand.

The server Directory

The server directory contains three subdirectories: classes, lib, and webapps. Classes in the subdirectories of server will be available to Tomcat only.

You should place class files in the classes folder and utility JAR files (that is, packaged classes and supporting resources) in lib.

The webapps directory contains classes and resources for admin and manager, Tomcat’s two admin Web applications. If you’re using Tomcat 5.5, you’ll have to download the admin application separately. However, the source distribution of Tomcat 5.5 includes the admin application, which means you will install it if you build Tomcat 5.5 from source.

The shared Directory

The shared directory contains two subdirectories: classes and lib. Classes in the subdirectories of shared will be available to all the Web applications running on the server but not to Tomcat.

You should place class files in the classes folder and utility JAR files (that is, packaged classes and supporting resources) in lib. Never place application-specific classes in either of these directories.

The temp Directory

Tomcat uses the temp directory for storing temporary files.

The webapps Directory

The webapps directory is the default location of Tomcat’s Web applications. You can change this location, and it’s recommended that you do so, as you can then separate the application files that change relatively frequently from the server files that don’t tend to change much. As a bonus, the installation directory for Tomcat can be kept as read/write for the administrator only, thus maintaining greater security—read/write access for other users need be provided only for the now separate webapps folder.

You can deploy Web applications in webapps by placing them here, in both packaged and unpackaged formats, and they will be automatically deployed at the next server bootup. This is an alternative to the conf/[Service_name]/[Host_name] method and the various deployer (such as Ant and the Tomcat manager application) methods.

The work Directory

The work directory is where Tomcat places the JSP code after it has been converted into servlet code. Once a JSP page has been visited, Tomcat also stores the compiled servlet here.



Pro Jakarta Tomcat 5
Pro Apache Tomcat 5/5.5 (Experts Voice in Java)
ISBN: 1590593316
EAN: 2147483647
Year: 2004
Pages: 94

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net