tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From craig...@apache.org
Subject cvs commit: jakarta-tomcat-4.0/webapps/tomcat-docs/config engine.xml http11.xml project.xml server.xml service.xml warp.xml
Date Sat, 25 Aug 2001 01:14:13 GMT
craigmcc    01/08/24 18:14:13

  Modified:    webapps/tomcat-docs/config http11.xml project.xml server.xml
                        service.xml warp.xml
  Added:       webapps/tomcat-docs/config engine.xml
  Log:
  Add docs for <Engine> element, and tweak the existing ones slightly.
  
  Revision  Changes    Path
  1.2       +1 -1      jakarta-tomcat-4.0/webapps/tomcat-docs/config/http11.xml
  
  Index: http11.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/config/http11.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- http11.xml	2001/08/21 02:28:21	1.1
  +++ http11.xml	2001/08/25 01:14:13	1.2
  @@ -195,7 +195,7 @@
   </section>
   
   
  -<section name="Nested Elements">
  +<section name="Nested Components">
   
     <p>The only element that may be embedded inside a <strong>Connector</strong>
     element is a <strong>Factory</strong> element, which is used to configure
  
  
  
  1.3       +1 -1      jakarta-tomcat-4.0/webapps/tomcat-docs/config/project.xml
  
  Index: project.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/config/project.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- project.xml	2001/08/05 03:42:28	1.2
  +++ project.xml	2001/08/25 01:14:13	1.3
  @@ -32,7 +32,7 @@
           <item name="Host"                  href="host.html"/>
       </menu>
   
  -    <menu name="Nested Elements">
  +    <menu name="Nested Components">
           <item name="Default Context"       href="defaultcontext.html"/>
           <item name="Loader"                href="loader.html"/>
           <item name="Logger"                href="logger.html"/>
  
  
  
  1.2       +2 -2      jakarta-tomcat-4.0/webapps/tomcat-docs/config/server.xml
  
  Index: server.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/config/server.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- server.xml	2001/08/21 02:28:21	1.1
  +++ server.xml	2001/08/25 01:14:13	1.2
  @@ -65,9 +65,9 @@
   </section>
   
   
  -<section name="Nested Elements">
  +<section name="Nested Components">
   
  -  <p>No nested elements may be embedded inside a <strong>Server</strong>,
  +  <p>No nested components may be embedded inside a <strong>Server</strong>,
     element, except for one or more <a href="service.html">Service</a> elements.
     </p>
   
  
  
  
  1.2       +2 -2      jakarta-tomcat-4.0/webapps/tomcat-docs/config/service.xml
  
  Index: service.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/config/service.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- service.xml	2001/08/21 02:28:21	1.1
  +++ service.xml	2001/08/25 01:14:13	1.2
  @@ -64,9 +64,9 @@
   </section>
   
   
  -<section name="Nested Elements">
  +<section name="Nested Components">
   
  -  <p>No nested elements may be embedded inside a <strong>Server</strong>,
  +  <p>No nested components may be embedded inside a <strong>Server</strong>,
     element, except for one or more <strong>Connector</strong> elements
     followed by a single <a href="engine.html">Engine</a> element.
     </p>
  
  
  
  1.2       +1 -1      jakarta-tomcat-4.0/webapps/tomcat-docs/config/warp.xml
  
  Index: warp.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/config/warp.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- warp.xml	2001/08/21 02:28:21	1.1
  +++ warp.xml	2001/08/25 01:14:13	1.2
  @@ -106,7 +106,7 @@
   </section>
   
   
  -<section name="Nested Elements">
  +<section name="Nested Components">
   
     <p><strong>FIXME</strong> - Document any use of a nested <code>Factory</code>
     element for communicating with <code>mod_webapp</code> over SSL.</p>
  
  
  
  1.1                  jakarta-tomcat-4.0/webapps/tomcat-docs/config/engine.xml
  
  Index: engine.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE document [
    <!ENTITY project SYSTEM "project.xml">
  ]>
  <document>
  
    &project;
  
    <properties>
      <author email="craigmcc@apache.org">Craig R. McClanahan</author>
      <title>The Engine Container</title>
    </properties>
  
  <body>
  
  
  <section name="Introduction">
  
    <p>The <strong>Engine</strong> element represents the entire request
    processing machinery associated with a particular Catalina
    <a href="service.html">Service</a>.  It receives and processes
    <em>all</em> requests from one or more <strong>Connectors</strong>,
    and returns the completed response to the Connector for ultimate
    transmission back to the client.</p>
  
    <p>Exactly one <strong>Engine</strong> element MUST be nested inside
    a <a href="service.html">Service</a> element, following all of the
    corresponding Connector elements associated with this Service.</p>
  
  </section>
  
  
  <section name="Attributes">
  
    <subsection name="Common Attributes">
  
      <p>All implementations of <strong>Engine</strong>
      support the following attributes:</p>
  
      <attributes>
  
        <attribute name="className" required="false">
          <p>Java class name of the implementation to use.  This class must
          implement the <code>org.apache.catalina.Engine</code> interface.
          If not specified, the standard value (defined below) will be used.</p>
        </attribute>
  
        <attribute name="defaultHost" required="true">
          <p>The default host name, which identifies the
          <a href="host.html">Host</a> that will process requests directed
          to host names on this server, but which are not configured in
          this configuration file.  This name MUST match the <code>name</code>
          attributes of one of the <a href="host.html">Host</a> elements
          nested immediately inside.</p>
        </attribute>
  
        <attribute name="name" required="true">
          <p>Logical name of this Engine, used in log and error messages.</p>
        </attribute>
  
      </attributes>
  
    </subsection>
  
  
    <subsection name="Standard Implementation">
  
      <p>The standard implementation of <strong>Engine</strong> is
      <strong>org.apache.catalina.core.StandardEngine</strong>.
      It supports the following additional attributes (in addition to the
      common attributes listed above):</p>
  
      <attributes>
  
        <attribute name="debug" required="false">
          <p>The level of debugging detail logged by this <strong>Engine</strong>
          to the associated <a href="logger.html">Logger</a>.  Higher numbers
          generate more detailed output.  If not specified, the default
          debugging detail level is zero (0).</p>
        </attribute>
  
      </attributes>
  
    </subsection>
  
  
  </section>
  
  
  <section name="Nested Components">
  
    <p>You can nest one or more <a href="host.html">Host</a> elements inside
    this <strong>Engine</strong> element, each representing a different virtual
    host associated with this server.  At least one <a href="host.html">Host</a>
    is required, and one of the nested <a href="host.html">Hosts</a> MUST
    have a name that matches the name specified for the
    <code>defaultHost</code> attribute, listed above.</p>
  
    <p>You can nest at most one instance of the following utility components
    by nesting a corresponding element inside your <strong>Engine</strong>
    element:</p>
    <ul>
    <li><a href="logger.html"><strong>Logger</strong></a> -
        Configure a logger that will receive
        and process all log messages for this <strong>Engine</strong>, plus
        messages from <strong>Connectors</strong> associated with this Engine
        in the surrounding Service.  In addition, this Logger will log messages
        from subordinate <a href="host.html">Hosts</a> and
        <a href="context.html">Contexts</a>, unless overridden by a
        <a href="logger.html">Logger</a> configuration at a lower level.</li>
    <li><a href="realm.html"><strong>Realm</strong></a> -
        Configure a realm that will allow its
        database of users, and their associated roles, to be shared across all
        <a href="host.html">Hosts</a> and <a href="context.html">Contexts</a>
        nested inside this Engine, unless overridden by a
        <a href="realm.html">Realm</a> configuration at a lower level.</li>
    </ul>
  
  </section>
  
  
  <section name="Special Features">
  
  
    <subsection name="Access Logs">
  
      <p>When you run a web server, one of the output files normally generated
      is an <em>access log</em>, which generates one line of information for
      each request processed by the server, in a standard format.  Catalina
      includes an optional <a href="valve.html">Valve</a> implementation that
      can create access logs in the same standard format created by web servers,
      or in any number of custom formats.</p>
  
      <p>You can ask Catalina to create an access log for all requests
      processed by an <a href="engine.html">Engine</a>,
      <a href="host.html">Host</a>, or <a href="context.html">Context</a>
      by nesting a <a href="valve.html">Valve</a> element like this:</p>
  
  <source>
  &lt;Engine name="Standalone" ...&gt;
    ...
    &lt;Valve className="org.apache.catalina.valves.AccessLogValve"
           prefix="catalina_access_log." suffix=".txt"
           pattern="common"/&gt;
    ...
  &lt;/Engine&gt;
  </source>
  
      <p>See <a href="valve.html#Access Log Valve">Access Log Valve</a>
      for more information on the configuration attributes that are
      supported.</p>
  
    </subsection>
  
  
    <subsection name="Lifecycle Listeners">
  
      <p>If you have implemented a Java object that needs to know when this
      <strong>Engine</strong> is started or stopped, you can declare it by
      nesting a <strong>Listener</strong> element inside this element.  The
      class name you specify must implement the
      <code>org.apache.catalina.LifecycleListener</code> interface, and
      it will be notified about the occurrence of the coresponding
      lifecycle events.  Configuration of such a listener looks like this:</p>
  
  <source>
  &lt;Engine name="Standalone" ...&gt;
    ...
    &lt;Listener className="com.mycompany.mypackage.MyListener" ... &gt;
    ...
  &lt;/Engine&gt;
  </source>
  
      <p>Note that a Listener can have any number of additional properties
      that may be configured from this element.  Attribute names are matched
      to corresponding JavaBean property names using the standard property
      method naming patterns.</p>
  
    </subsection>
  
  
    <subsection name="Request Filters">
  
      <p>You can ask Catalina to check the IP address, or host name, on every
      incoming request directed to the surrounding
      <a href="engine.html">Engine</a>, <a href="host.html">Host</a>,
or
      <a href="context.htm">Context</a> element.  The remote address or name
      will be checked against a configured list of "accept" and/or "deny"
      filters, which are defined using the Regular Expression syntax supported
      by the <a href="http://jakarta.apache.org/regexp/">Jakarta Regexp</a>
      regular expression library.  Requests that come from locations that are
      not accepted will be rejected with an HTTP "Forbidden" error.
      Example filter declarations:</p>
  
  <source>
  &lt;Engine name="Standalone" ...&gt;
    ...
    &lt;Valve className="org.apache.catalina.valves.RemoteHostValve"
           allow="*.mycompany.com,www.yourcompany.com"/&gt;
    &lt;Valve className="org.apache.catalina.valves.RemoteAddrValve"
           deny="192.168.1.*"/&gt;
    ...
  &lt;/Engine&gt;
  </source>
  
    <p>See <a href="valve.html#Remote Address Filter">Remote Address Filter</a>
    and <a href="valve.html#Remove Host Filter">Remote Host Filter</a> for
    more information about the configuration options that are supported.</p>
  
    </subsection>
  
  
  </section>
  
  
  </body>
  
  
  </document>
  
  
  

Mime
View raw message