You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by re...@apache.org on 2006/07/08 00:40:09 UTC
svn commit: r420006 [4/17] - in /tomcat/tc6.0.x/trunk: res/ res/deployer/
webapps/docs/ webapps/docs/META-INF/ webapps/docs/WEB-INF/
webapps/docs/api/ webapps/docs/appdev/ webapps/docs/appdev/sample/
webapps/docs/appdev/sample/docs/ webapps/docs/appdev...
Added: tomcat/tc6.0.x/trunk/webapps/docs/architecture/startup.xml
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/architecture/startup.xml?rev=420006&view=auto
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/architecture/startup.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/architecture/startup.xml Fri Jul 7 15:40:04 2006
@@ -0,0 +1,57 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="startup.html">
+
+ &project;
+
+ <properties>
+ <author email="yoavs@apache.org">Yoav Shapira</author>
+ <title>Startup</title>
+ </properties>
+
+<body>
+
+
+<section name="Server Startup">
+
+<p>
+This page describes how the Tomcat server starts up. There are several
+different ways to start tomcat, including:
+<ul>
+ <li>From the command line.</li>
+ <li>From a Java program as an embedded server.</li>
+ <li>Automatically as a Windows service.</li>
+</ul>
+</p>
+
+<subsection name="description">
+<p>
+A text description of the startup procedure is available
+<a href="startup/serverStartup.txt">here.</a>
+</p>
+</subsection>
+
+<subsection name="diagram">
+<p>
+A UML sequence diagram of the startup procedure is available
+<a href="startup/serverStartup.pdf">here.</a>
+</p>
+</subsection>
+
+<subsection name="comments">
+<p>
+The startup process can be customized in many ways, both
+by modifying Tomcat code and by implementing your own
+LifecycleListeners which are then registered in the server.xml
+configuration file.
+</p>
+
+</subsection>
+
+</section>
+
+
+</body>
+</document>
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/architecture/startup.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/tc6.0.x/trunk/webapps/docs/architecture/startup/serverStartup.pdf
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/architecture/startup/serverStartup.pdf?rev=420006&view=auto
==============================================================================
Binary file - no diff available.
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/architecture/startup/serverStartup.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
Added: tomcat/tc6.0.x/trunk/webapps/docs/architecture/startup/serverStartup.txt
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/architecture/startup/serverStartup.txt?rev=420006&view=auto
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/architecture/startup/serverStartup.txt (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/architecture/startup/serverStartup.txt Fri Jul 7 15:40:04 2006
@@ -0,0 +1,136 @@
+Tomcat 5 Startup Sequence
+
+Sequence 1. Start from Command Line
+Class: org.apache.catalina.startup.Bootstrap
+What it does:
+ a) Set up classloaders
+ commonLoader (common)-> System Loader
+ sharedLoader (shared)-> commonLoader -> System Loader
+ catalinaLoader(server) -> commonLoader -> System Loader
+ b) Load startup class (reflection)
+ org.apache.catalina.startup.Catalina
+ setParentClassloader -> sharedLoader
+ Thread.contextClassloader -> catalinaLoader
+ c) Bootstrap.daemon.init() complete
+
+Sequence 2. Process command line argument (start, startd, stop, stopd)
+Class: org.apache.catalina.startup.Bootstrap (assume command->start)
+What it does:
+ a) Catalina.setAwait(true);
+ b) Catalina.load()
+ b1) initDirs() -> set properties like
+ catalina.home
+ catalina.base == catalina.home (most cases)
+ b2) initNaming
+ setProperty(javax.naming.Context.INITIAL_CONTEXT_FACTORY,
+ org.apache.naming.java.javaURLContextFactory ->default)
+ b3) createStartDigester()
+ Configures a digester for the main server.xml elements like
+ org.apache.catalina.core.StandardServer (can change of course :)
+ org.apache.catalina.deploy.NamingResources
+ Stores naming resources in the J2EE JNDI tree
+ org.apache.catalina.LifecycleListener
+ implements events for start/stop of major components
+ org.apache.catalina.core.StandardService
+ The single entry for a set of connectors,
+ so that a container can listen to multiple connectors
+ ie, single entry
+ org.apache.coyote.tomcat5.CoyoteConnector
+ Connectors to listen for incoming requests only
+ It also adds the following rulesets to the digester
+ NamingRuleSet
+ EngineRuleSet
+ HostRuleSet
+ ContextRuleSet
+ b4) Load the server.xml and parse it using the digester
+ Parsing the server.xml using the digester is an automatic
+ XML-object mapping tool, that will create the objects defined in server.xml
+ Startup of the actual container has not started yet.
+ b5) Assigns System.out and System.err to the SystemLogHandler class
+ b6) Calls intialize on all components, this makes each object register itself with the
+ JMX agent.
+ During the process call the Connectors also initialize the adapters.
+ The adapters are the components that do the request pre-processing.
+ Typical adapters are HTTP1.1 (default if no protocol is specified,
+ org.apache.coyote.http11.Http11Protocol)
+ AJP1.3 for mod_jk etc.
+
+ c) Catalina.start()
+ c1) Starts the NamingContext and binds all JNDI references into it
+ c2) Starts the services under <Server> which are:
+ StandardService -> starts Engine (ContainerBase ->Logger,Loader,Realm,Cluster etc)
+ c3) StandardHost (started by the service)
+ Configures a ErrorReportValvem to do proper HTML output for different HTTP
+ errors codes
+ Starts the Valves in the pipeline (at least the ErrorReportValve)
+ Configures the StandardHostValve,
+ this valves ties the Webapp Class loader to the thread context
+ it also finds the session for the request
+ and invokes the context pipeline
+ Starts the HostConfig component
+ This component deploys all the webapps
+ (webapps & conf/Catalina/localhost/*.xml)
+ Webapps are installed using the deployer (StandardHostDeployer)
+ The deployer will create a Digester for your context, this digester
+ will then invoke ContextConfig.start()
+ The ContextConfig.start() will process the default web.xml (conf/web.xml)
+ and then process the applications web.xml (WEB-INF/web.xml)
+
+ c4) During the lifetime of the container (StandardEngine) there is a background thread that
+ keeps checking if the context has changed. If a context changes (timestamp of war file,
+ context xml file, web.xml) then a reload is issued (stop/remove/deploy/start)
+
+ d) Tomcat receives a request on an HTTP port
+ d1) The request is received by a separate thread which is waiting in the PoolTcpEndPoint
+ class. It is waiting for a request in a regular ServerSocket.accept() method.
+ When a request is received, this thread wakes up.
+ d2) The PoolTcpEndPoint assigns the a TcpConnection to handle the request.
+ It also supplies a JMX object name to the catalina container (not used I believe)
+ d3) The processor to handle the request in this case is Coyote Http11Processor,
+ and the process method is invoked.
+ This same processor is also continuing to check the input stream of the socket
+ until the keep alive point is reached or the connection is disconnected.
+ d4) The HTTP request is parsed using an internal buffer class (Coyote Http11 Internal Buffer)
+ The buffer class parses the request line, the headers, etc and store the result in a
+ Coyote request (not an HTTP request) This request contains all the HTTP info, such
+ as servername, port, scheme, etc.
+ d5) The processor contains a reference to an Adapter, in this case it is the
+ Coyote Tomcat 5 Adapter. Once the request has been parsed, the Http11 processor
+ invokes service() on the adapter. In the service method, the Request contains a
+ CoyoteRequest and CoyoteRespons (null for the first time)
+ The CoyoteRequest(Response) implements HttpRequest(Response) and HttpServletRequest(Response)
+ The adapter parses and associates everything with the request, cookies, the context through a
+ Mapper, etc
+ d6) When the parsing is finished, the CoyoteAdapter invokes its container (StandardEngine)
+ and invokes the invoke(request,response) method.
+ This initiates the HTTP request into the Catalina container starting at the engine level
+ d7) The StandardEngine.invoke() simply invokes the container pipeline.invoke()
+ d8) By default the engine only has one valve the StandardEngineValve, this valve simply
+ invokes the invoke() method on the Host pipeline (StandardHost.getPipeLine())
+ d9) the StandardHost has two valves by default, the StandardHostValve and the ErrorReportValve
+ d10) The standard host valve associates the correct class loader with the current thread
+ It also retrives the Manager and the session associated with the request (if there is one)
+ If there is a session access() is called to keep the session alive
+ d11) After that the StandardHostValve invokes the pipeline on the context associated
+ with the request.
+ d12) The first valve that gets invoked by the Context pipeline is the FormAuthenticator
+ valve. Then the StandardContextValve gets invoke.
+ The StandardContextValve invokes any context listeners associated with the context.
+ Next it invokes the pipeline on the Wrapper component (StandardWrapperValve)
+ d13) During the invokation of the StandardWrapperValve, the JSP wrapper (Jasper) gets invoked
+ This results in the actual compilation of the JSP.
+ And then invokes the actual servlet.
+ e) Invokation of the servlet class
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/architecture/startup/serverStartup.txt
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/tc6.0.x/trunk/webapps/docs/balancer-howto.xml
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/balancer-howto.xml?rev=420006&view=auto
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/balancer-howto.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/balancer-howto.xml Fri Jul 7 15:40:04 2006
@@ -0,0 +1,148 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="balancer-howto.html">
+
+ &project;
+
+ <properties>
+ <author email="yoavs@apache.org">Yoav Shapira</author>
+ <author>Remy Maucherat</author>
+ <author>Andy Oliver</author>
+ <title>Load Balancer HOW-TO</title>
+ </properties>
+
+<body>
+
+<section name="Table of Contents">
+<p>
+<a href="#Using the JK 1.2.x native connector">
+Using the JK native connector</a><br />
+<a href="#Using Apache HTTP Server 2.x with mod_proxy">
+Using Apache HTTP Server 2.x and mod_proxy</a><br />
+<a href="#Using the balancer webapp">Using the balancer webapp</a><br />
+</p>
+</section>
+
+<section name="Using the JK 1.2.x native connector">
+
+Please refer to the JK 1.2.x documentation.
+
+</section>
+
+<section name="Using Apache HTTP Server 2.x with mod_proxy">
+
+Please refer to the mod_proxy documentation for Apache HTTP Server 2.2. This supports either
+HTTP or AJP load balancing. This new version of mod_proxy is also useable with
+Apache HTTP Server 2.0, but mod_proxy will have to be compiled separately using the code
+from Apache HTTP Server 2.2.
+
+</section>
+
+<section name="Using the balancer webapp">
+
+<subsection name="Overview">
+
+<p>
+Tomcat 5.0.15 and later ships with a webapp named balancer. This is
+a simple implemention of a rules-based load balancer. It was not designed
+as a replacement for other load-balancing mechanisms used for high traffic
+environments. Rather, it is a simple, pure Java, easily extensible, and fast
+way to direct traffic among multiple servers.
+</p>
+<p>
+Although balancer ships with Tomcat, it is not Tomcat-specific and runs
+on other containers without any modification. The balancer webapp
+requires a Servlet Specification 2.3 or later container if you wish
+to use a filter to redirect traffic. If you wish to redirect traffic
+using a servlet, you may use any servlet container.
+</p>
+</subsection>
+
+<subsection name="Sample Configuration">
+<p>
+The default balancer installation uses a single filter, BalancerFilter,
+mapped to all requests (url-pattern /*). The filter reads its rules
+from the location specified in the balancer deployment descriptor
+(web.xml file). The default rules are:
+<ul>
+ <li>Redirect requests with News in the URL to www.cnn.com</li>
+ <li>Redirect requests with a parameter named paramName whose
+value is paramValue to www.yahoo.com.</li>
+ <li>Redirect all other requests to jakarta.apache.org.</li>
+</ul>
+
+Therefore, when you install tomcat, start it, and point your
+browser to http://localhost:8080/balancer, you will be redirected
+to http://jakarta.apache.org. If you point your browser to
+http://localhost:8080/balancer/News you will be redirected to
+http://www.cnn.com. The request for
+http://localhost:8080/balancer/BlahBlah?paramName=paramValue will
+be redirected to http://www.yahoo.com.
+</p>
+</subsection>
+
+<subsection name="Balancer Rules">
+<p>
+A <i>Rule</i> in the balancer system is a combination of
+a request matching criterion and a redirection URL for
+matching requests. Rules implement the
+org.apache.webapp.balancer.Rule interface.
+</p>
+
+<p>
+The balancer distribution contains a number of useful
+rules. The framework is also designed for easy extensibility
+so that you can write your own rules quickly. Rules
+should be JavaBeans (public no-args constructor, public
+setter method setXXX for property xxx), as they are
+instantiated by Jakarta Commons Digester. Feel free
+to inquire on the tomcat-user mailing list regarding
+the availability of rules or the inclusion of your rules
+in the distribution.
+</p>
+
+<p>
+Rules are assembled into RuleChains. Each BalancerFilter
+(or Servlet/JSP) refers to one RuleChain when making its
+redirection decisions. Note that you are not restricted
+to having one filter mapped to /* as done in the sample
+configuration. You can configure as many filters as
+desired, using the full filter mapping possibilities defined
+in the Servlet Specification. Each filter will have
+its own RuleChain.
+</p>
+</subsection>
+
+<subsection name="How it Works">
+<p>
+<ol>
+ <li>You write a rules configuration file containing various
+rules and redirection locations.</li>
+ <li>You define the balancer filter in your web.xml, mapping
+it as desired (/* is a common use-case) and configuring it
+with your rules configuration file.</li>
+ <li>The server is started, initializing the filter.</li>
+ <li>A request comes into the server. The filter consults
+its rule chain to determine where to redirect the request. Rules
+are consulted in the order in which they are defined in the rules
+configuration file. The first matching rule will stop the
+evaluation and cause the request to be redirected.</li>
+</ol>
+</p>
+
+</subsection>
+
+<subsection name="Comments">
+<p>
+Please direct questions, comments, suggestions, etc. to the
+tomcat-user mailing list. Thank you.
+</p>
+</subsection>
+
+</section>
+
+</body>
+
+</document>
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/balancer-howto.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/tc6.0.x/trunk/webapps/docs/build.xml
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/build.xml?rev=420006&view=auto
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/build.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/build.xml Fri Jul 7 15:40:04 2006
@@ -0,0 +1,240 @@
+<project name="tomcat-docs" default="build-main" basedir=".">
+
+
+ <!-- ===================== Initialize Property Values =================== -->
+
+ <!-- See "build.properties.sample" in the top level directory for all -->
+ <!-- property values you must customize for successful building!!! -->
+ <property file="build.properties"/>
+ <property file="../build.properties"/>
+ <property file="../../build.properties"/>
+ <property file="${user.home}/build.properties"/>
+
+ <property name="build.compiler" value="modern"/>
+ <property name="webapps.build" value="../build"/>
+ <property name="webapps.dist" value="../dist"/>
+ <property name="webapp.name" value="tomcat-docs"/>
+
+
+ <!-- =================== BUILD: Create Directories ====================== -->
+ <target name="build-prepare">
+ <mkdir dir="${webapps.build}"/>
+ <mkdir dir="${webapps.build}/${webapp.name}"/>
+ </target>
+
+
+ <!-- ================ BUILD: Copy Static Files ========================== -->
+ <target name="build-static" depends="build-prepare">
+
+ <!-- Top Level Static Files -->
+ <copy todir="${webapps.build}/${webapp.name}">
+ <fileset dir="../..">
+ <include name="BUILDING.txt"/>
+ <include name="README.txt"/>
+ <include name="RUNNING.txt"/>
+ </fileset>
+ </copy>
+ <copy todir="${webapps.build}/${webapp.name}">
+ <fileset dir="." includes="**/*.html"/>
+ </copy>
+
+ <!-- WEB-INF Static Files -->
+ <copy todir="${webapps.build}/${webapp.name}/WEB-INF">
+ <fileset dir="WEB-INF"/>
+ </copy>
+
+ <!-- Application Developer's Guide Examples -->
+ <copy todir="${webapps.build}/${webapp.name}/appdev">
+ <fileset dir="appdev" includes="*.txt"/>
+ </copy>
+
+ <!-- This copy includes a binary file (sample.war) so it should not have a filter token -->
+ <!-- See Bugzilla 36318: http://issues.apache.org/bugzilla/show_bug.cgi?id=36318 -->
+ <copy todir="${webapps.build}/${webapp.name}/appdev/sample">
+ <fileset dir="appdev/sample"/>
+ </copy>
+
+ <copy tofile="${webapps.build}/${webapp.name}/appdev/sample/build.xml"
+ file="appdev/build.xml.txt"/>
+
+ <!-- Catalina Functional Specifications -->
+ <mkdir dir="${webapps.build}/${webapp.name}/catalina/funcspecs"/>
+
+ <!-- Architecture -->
+ <copy todir="${webapps.build}/${webapp.name}/architecture">
+ <fileset dir="architecture" excludes="*.xml"/>
+ </copy>
+
+ <!-- Images Subdirectory -->
+ <mkdir dir="${webapps.build}/${webapp.name}/images"/>
+ <copy todir="${webapps.build}/${webapp.name}/images">
+ <fileset dir="images"/>
+ </copy>
+
+ <mkdir dir="${webapps.build}/${webapp.name}/printer"/>
+ <!-- Top Level Static Files -->
+ <copy todir="${webapps.build}/${webapp.name}/printer">
+ <fileset dir="../..">
+ <include name="BUILDING.txt"/>
+ <include name="README.txt"/>
+ <include name="RUNNING.txt"/>
+ </fileset>
+ </copy>
+ <style basedir="."
+ destdir="${webapps.build}/${webapp.name}/printer"
+ extension=".html"
+ style="tomcat-docs.xsl"
+ excludes="build.xml project.xml"
+ includes="*.xml">
+ <param name="relative-path" expression="./.."/>
+ <param name="project-menu" expression="nomenu"/>
+ </style>
+
+ <!-- WEB-INF Subdirectory -->
+ <mkdir dir="${webapps.build}/${webapp.name}/WEB-INF"/>
+ <copy todir="${webapps.build}/${webapp.name}/WEB-INF">
+ <fileset dir="WEB-INF"/>
+ </copy>
+
+ </target>
+
+
+ <!-- ================= BUILD: XML-HTML Generation ======================= -->
+ <target name="build-main" depends="build-static">
+
+ <!-- Top Level Directory -->
+ <style basedir="."
+ destdir="${webapps.build}/${webapp.name}"
+ extension=".html"
+ style="tomcat-docs.xsl"
+ excludes="build.xml project.xml"
+ includes="*.xml">
+ <param name="relative-path" expression="."/>
+ </style>
+
+ <!-- Application Developer's Guide -->
+ <style basedir="appdev"
+ destdir="${webapps.build}/${webapp.name}/appdev"
+ extension=".html"
+ style="tomcat-docs.xsl"
+ excludes="project.xml"
+ includes="*.xml">
+ <param name="relative-path" expression=".."/>
+ </style>
+ <mkdir dir="${webapps.build}/${webapp.name}/appdev/printer"/>
+ <!-- Application Developer's Guide Examples -->
+ <copy todir="${webapps.build}/${webapp.name}/appdev/printer">
+ <fileset dir="appdev" includes="*.txt"/>
+ </copy>
+ <style basedir="appdev"
+ destdir="${webapps.build}/${webapp.name}/appdev/printer"
+ extension=".html"
+ style="tomcat-docs.xsl"
+ excludes="project.xml"
+ includes="*.xml">
+ <param name="relative-path" expression="../.."/>
+ <param name="project-menu" expression="nomenu"/>
+ </style>
+
+ <!-- Catalina Functional Specifications -->
+ <mkdir dir="${webapps.build}/${webapp.name}/catalina"/>
+ <mkdir dir="${webapps.build}/${webapp.name}/catalina/funcspecs"/>
+ <style basedir="funcspecs"
+ destdir="${webapps.build}/${webapp.name}/catalina/funcspecs"
+ extension=".html"
+ style="tomcat-docs.xsl"
+ excludes="project.xml"
+ includes="*.xml">
+ <param name="relative-path" expression="../.."/>
+ </style>
+ <mkdir dir="${webapps.build}/${webapp.name}/catalina/funcspecs/printer"/>
+ <style basedir="funcspecs"
+ destdir="${webapps.build}/${webapp.name}/catalina/funcspecs/printer"
+ extension=".html"
+ style="tomcat-docs.xsl"
+ excludes="project.xml"
+ includes="*.xml">
+ <param name="relative-path" expression="../../.."/>
+ <param name="project-menu" expression="nomenu"/>
+ </style>
+
+ <!-- Server Configuration Reference -->
+ <style basedir="config"
+ destdir="${webapps.build}/${webapp.name}/config"
+ extension=".html"
+ style="tomcat-docs.xsl"
+ excludes="project.xml"
+ includes="*.xml">
+ <param name="relative-path" expression=".."/>
+ </style>
+ <mkdir dir="${webapps.build}/${webapp.name}/config/printer"/>
+ <style basedir="config"
+ destdir="${webapps.build}/${webapp.name}/config/printer"
+ extension=".html"
+ style="tomcat-docs.xsl"
+ excludes="project.xml"
+ includes="*.xml">
+ <param name="relative-path" expression="../.."/>
+ <param name="project-menu" expression="nomenu"/>
+ </style>
+
+ <!-- Server Architecture -->
+ <style basedir="architecture"
+ destdir="${webapps.build}/${webapp.name}/architecture"
+ extension=".html"
+ style="tomcat-docs.xsl"
+ excludes="project.xml"
+ includes="*.xml">
+ <param name="relative-path" expression=".."/>
+ </style>
+ <mkdir dir="${webapps.build}/${webapp.name}/architecture/printer"/>
+ <style basedir="architecture"
+ destdir="${webapps.build}/${webapp.name}/architecture/printer"
+ extension=".html"
+ style="tomcat-docs.xsl"
+ excludes="project.xml"
+ includes="*.xml">
+ <param name="relative-path" expression="../.."/>
+ <param name="project-menu" expression="nomenu"/>
+ </style>
+
+ </target>
+
+
+ <!-- ==================== BUILD: Rebuild Everything ===================== -->
+ <target name="all" depends="build-clean,build-main"
+ description="Clean and build documentation webapp"/>
+
+
+ <!-- ======================= BUILD: Clean Directory ===================== -->
+ <target name="build-clean">
+ <delete dir="${webapps.build}/${webapp.name}"/>
+ </target>
+
+
+ <!-- ======================= DIST: Create Directories =================== -->
+ <target name="dist-prepare">
+ <mkdir dir="${webapps.dist}"/>
+ </target>
+
+
+ <!-- ======================= DIST: Create Distribution Files ============ -->
+ <target name="dist" depends="build-main,dist-prepare"
+ description="Create documentation webapp binary distribution">
+ <jar jarfile="${webapps.dist}/${webapp.name}.war"
+ basedir="${webapps.build}/${webapp.name}" includes="**"/>
+ </target>
+
+
+ <!-- ======================= DIST: Clean Directory ====================== -->
+ <target name="dist-clean">
+ <delete dir="${webapps.dist}/${webapp.name}"/>
+ </target>
+
+
+ <!-- ====================== Convenient Synonyms ========================= -->
+ <target name="clean" depends="build-clean,dist-clean"
+ description="Clean build and dist directories"/>
+
+
+</project>
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/build.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/tc6.0.x/trunk/webapps/docs/building.xml
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/building.xml?rev=420006&view=auto
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/building.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/building.xml Fri Jul 7 15:40:04 2006
@@ -0,0 +1,231 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document>
+
+ &project;
+
+ <properties>
+ <author>Remy Maucherat</author>
+ <title>Building Tomcat</title>
+ </properties>
+
+<body>
+
+<section name="Introduction">
+
+<p>
+Building Tomcat from SVN is very easy, and is the first step to contributing to
+Tomcat. The following is a step by step TODO list.
+</p>
+
+</section>
+
+<section name="Download and install a Java Development Kit 1.4.x or later">
+
+<p>
+The default distribution of Tomcat 5.5.x requires a 5.0 or later JDK. Tomcat
+can be built using a 1.4.x JDK but you will need to copy the contents of the
+compat directory (created by the build process) to your build directory before
+Tomcat will start.
+</p>
+
+<p>
+The Sun JDK can be downloaded <a href="http://java.sun.com/j2se/">here</a>.
+</p>
+
+<p>
+<b>IMPORTANT</b>: Set an environment variable JAVA_HOME to the pathname of the
+directory into which you installed the JDK release.
+</p>
+
+</section>
+
+<section name="Install Apache Ant 1.6.2 or later">
+
+<p>
+Download a binary distribution of Ant 1.6.2 or later from
+<a href="http://ant.apache.org/bindownload.cgi">here</a>.
+</p>
+
+<p>
+Unpack the binary distribution into a convenient location so that the
+Ant release resides in its own directory (conventionally named
+"apache-ant-1.6.x"). For the purposes of the remainder of this document,
+the symbolic name "${ant.home}" is used to refer to the full pathname of
+ the release directory.
+</p>
+
+<p>
+Create an ANT_HOME environment variable to point the directory ${ant.home},
+and modify the PATH environment variable to include directory
+"${ant.home}/bin" in its list. This makes the "ant" command line script
+available, which will be used to actually perform the build.
+</p>
+
+</section>
+
+<section name="Building Tomcat">
+
+<p>
+Download the main build.xml script from <a href="build.xml">here</a>.
+</p>
+
+<p>
+Create a new directory, and copy the newly download build.xml to it. This
+ directory will be referred to as the ${tomcat.source} directory in the rest
+ of this document.
+</p>
+
+<p>
+Go to that directory, and do:
+<code><br/>
+ cd ${tomcat.source}<br/>
+ ant<br/>
+</code>
+</p>
+
+<p>
+NOTE: Users accessing the Internet through a proxy must use a properties
+ file to indicate to Ant the proxy configuration. Read below.
+</p>
+
+<p>
+WARNING: Running this command will checkout the Tomcat 5 sources from SVN, as
+ well as download binaries to the <code>/usr/share/java</code> directory.
+ Make sure this is appropriate to do so on your computer. On Windows,
+ this usually corresponds to the <code>C:\usr\share\java</code> directory,
+ unless Cygwin is used. Read below to customize the directory used
+ to download the binaries.
+</p>
+
+<p>
+The build can be controlled by creating a ${tomcat.source}/build.properties
+ file, and adding the following content to it:
+<code><br/>
+ # ----- Proxy setup -----<br/>
+ # Uncomment if using a proxy server.<br/>
+ #proxy.host=proxy.domain<br/>
+ #proxy.port=8080<br/>
+ #proxy.use=on<br/>
+<br/>
+ # ----- Default Base Path for Dependent Packages -----<br/>
+ # Replace this path with the directory path where<br/>
+ # dependencies binaries should be downloaded.<br/>
+ base.path=/usr/share/java<br/>
+</code>
+</p>
+
+</section>
+
+<section name="Updating and rebuilding Tomcat sources">
+
+<p>
+It is recommended to regularly update the downloaded Tomcat 5 sources.
+To do this, execute the following commands:
+
+<code><br/>
+ cd ${tomcat.source}<br/>
+ ant checkout<br/>
+</code>
+</p>
+
+<p>
+For a quick rebuild of only modified code you can use:
+<code><br/>
+ cd ${tomcat.source}<br/>
+ ant build<br/>
+</code>
+
+</p>
+
+</section>
+
+<section name="Building with Eclipse">
+
+<p>
+<b>Important:</b>
+This is not a supported means of building Tomcat; this information is
+provided without warranty :-).
+The only supported means of building Tomcat is with the "ant build"
+described above.
+However, some developers like to work on Java code with a Java IDE,
+and the following steps have been used by some developers.
+</p>
+
+<p>
+Note that you <b>must</b> complete all the above steps to fetch
+the repositories and build some JAR files the first time.
+After you have completed the above steps, you can set up a
+series of Eclipse 4 projects.
+<b>Note</b> that this will not let you build everything under Eclipse;
+the build process requires use of Ant for the many stages that aren't
+simple Java compilations.
+However, it will allow you to view and edit the Java code,
+get warnings, reformat code, perform refactorings, run Tomcat
+under the IDE, and so on.
+</p>
+
+<p>
+Use Windows->Preferences and then Java->Build Path->Classpath
+Variables to add two new Classpath variables:
+</p>
+
+<p>
+<table border="1">
+ <tr><td>TOMCAT_LIBS_BASE</td><td>the base path where the binary dependencies have been downloaded</td></tr>
+ <tr><td>ANT_HOME</td><td>the base path of Ant 1.6.2 or later</td></tr>
+</table>
+</p>
+
+<p>
+Use File->New Project to create a new Java project
+for each of the binaries repository (e.g., /usr/share/java),
+container, connectors, jasper, servletapi.
+Unless you thought ahead to make the ${tomcat.source} directory be under
+your Workspace folder, tell Eclipse the external location using "Import/Export...",
+General->Existing Project into Workspace.
+</p>
+
+<p>
+Eclipse .project and .classpath files are provided in each of these
+directories so Eclipse should find all source trees and jars, and
+hopefully compile without problems. <b>Note</b> that these
+files assume you are using Eclipse with a 5.0 or later JDK; also, the
+connectors module must be built with a compiler compliance level of 5.0.
+</p>
+
+<p>
+To run Tomcat without a special IDE plug-in, you can simply use Run->Run...
+enter "org.apache.catalina.startup.Catalina" as the main class,
+"start" as program arguments, and
+"-Dcatalina.home=..." (with the name of your build directory)
+as VM arguments.
+</p>
+
+<p>
+Note also that due to the way the Tomcat source is assembled
+from several SVN projects, you may not be able to use the Eclipse
+SVN client to update (nor to commit, if you are a committer).
+Use the external SVN client of your choice, then use the
+Eclipse PackageExplorer or Navigator "Refresh" context menu item
+to tell Eclipse that you've updated the files.
+</p>
+
+</section>
+
+<section name="Building with other IDEs">
+<p>
+The same caveats apply as for Eclipse, above.
+</p>
+
+<p>
+The same general idea should work in most IDEs; it has been reported
+to work in Idea, for example.
+</p>
+
+</section>
+
+</body>
+</document>
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/building.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/tc6.0.x/trunk/webapps/docs/cgi-howto.xml
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/cgi-howto.xml?rev=420006&view=auto
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/cgi-howto.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/cgi-howto.xml Fri Jul 7 15:40:04 2006
@@ -0,0 +1,76 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="cgi-howto.html">
+
+ &project;
+
+ <properties>
+ <author email="glenn@apache.org">Glenn L. Nielsen</author>
+ <title>CGI How To</title>
+ </properties>
+
+<body>
+
+<section name="Introduction">
+
+<p>The CGI (Common Gateway Interface) defines a way for a web server to
+interact with external content-generating programs, which are often
+referred to as CGI programs or CGI scripts.
+</p>
+
+<p>Within Tomcat, CGI support can be added when you are using Tomcat as your
+HTTP server and require CGI support. Typically this is done
+during development when you don't want to run a web server like
+Apache httpd.
+Tomcat's CGI support is largely compatible with Apache httpd's,
+but there are some limitations (e.g., only one cgi-bin directory).
+</p>
+
+<p>CGI support is implemented using the servlet class
+<code>org.apache.catalina.servlets.CGIServlet</code>. Traditionally,
+this servlet is mapped to the URL pattern "/cgi-bin/*".</p>
+
+<p>By default CGI support is disabled in Tomcat.</p>
+</section>
+
+<section name="Installation">
+
+<p><strong>CAUTION</strong> - CGI scripts are used to execute programs
+external to the Tomcat JVM. If you are using the Java SecurityManager this
+will bypass your security policy configuration in <code>catalina.policy.</code></p>
+
+<p>Rename <code>$CATALINA_BASE/server/lib/servlets-cgi.renametojar</code>
+to <code>$CATALINA_BASE/server/lib/servlets-cgi.jar</code>.</p>
+
+<p>Remove the XML comments from around the CGI servlet and servlet-mapping
+configuration in <code>$CATALINA_BASE/conf/web.xml</code>.</p>
+</section>
+
+<section name="Configuration">
+
+<p>There are several servlet init parameters which can be used to
+configure the behaviour of the CGI servlet.
+<ul>
+<li><strong>cgiPathPrefix</strong> - The CGI search path will start at
+the web application root directory + File.separator + this prefix.
+The default cgiPathPrefix is <code>WEB-INF/cgi</code></li>
+<li><strong>debug</strong> - Debugging detail level for messages logged
+by this servlet. Default 0.</li>
+<li><strong>executable</strong> - The of the executable to be used to
+run the script. Default is <code>perl</code>.</li>
+<li><strong>parameterEncoding</strong> - Name of the parameter encoding
+to be used with the GCI servlet. Default is
+<code>System.getProperty("file.encoding","UTF-8")</code>.</li>
+<li><strong>passShellEnvironment</strong> - Should the shell environment
+variables (if any) be passed to the CGI script? Default is
+<code>false</code>.</li>
+</ul>
+</p>
+
+</section>
+
+</body>
+
+</document>
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/cgi-howto.xml
------------------------------------------------------------------------------
svn:eol-style = native
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org