tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject cvs commit: jakarta-tomcat-catalina/webapps/docs balancer-howto.xml
Date Tue, 25 Nov 2003 18:22:30 GMT
yoavs       2003/11/25 10:22:30

  Added:       webapps/docs balancer-howto.xml
  Added initial version of balancer document.
  Revision  Changes    Path
  1.1                  jakarta-tomcat-catalina/webapps/docs/balancer-howto.xml
  Index: balancer-howto.xml
  <?xml version="1.0"?>
  <!DOCTYPE document [
    <!ENTITY project SYSTEM "project.xml">
  <document url="balancer-howto.html">
          <author email="">Yoav Shapira</author>
          <title>Load Balancer HOW-TO</title>
  <section name="Overview">
  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.
  <section name="Sample Configuration">
  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:
    <li>Redirect requests with News in the URL to</li>
    <li>Redirect requests with a parameter named paramName whose
  value is paramValue to</li>
    <li>Redirect all other requests to</li>
  Therefore, when you install tomcat, start it, and point your
  browser to http://localhost:8080/balancer, you will be redirected
  to  If you point your browser to
  http://localhost:8080/balancer/News you will be redirected to  The request for 
  http://localhost:8080/balancer/BlahBlah?paramName=paramValue will
  be redirected to
  <section name="Balancer Rules">
  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.
  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 mailist list regarding
  the availability of rules of the inclusion of your rules
  in the distribution.
  Rules are assembled into RuleChains.  Each BalancerFilter
  (or Servlet/JSP) refers to one RuleChain when making its
  redirection decisions.  Not that you are not restricted
  to having one filter mapped to /*, as is the default 
  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.
  <section name="How it Works">
  Here is the flow of events in the balancer:
    <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>

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message