You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by co...@apache.org on 2002/03/22 21:49:53 UTC
cvs commit: jakarta-tomcat-connectors/jk/doc/jk2 config.html jk2.html
costin 02/03/22 12:49:53
Added: jk/doc/jk2 config.html jk2.html
Log:
Added an initial documentation for the new jk2 design and an initial
documentation for the default config.
PLEASE, REVIEW !
Revision Changes Path
1.1 jakarta-tomcat-connectors/jk/doc/jk2/config.html
Index: config.html
===================================================================
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title></title>
</head>
<body>
<h3>Config options<br>
</h3>
<br>
<table cellpadding="2" cellspacing="2" border="1"
style="text-align: left; width: 100%;">
<tbody>
<tr>
<th valign="top">Property name<br>
</th>
<th valign="top">Default<br>
</th>
<th valign="top">Description<br>
</th>
</tr>
<tr>
</tr>
<tr>
<td valign="top" colspan="2" style="font-weight: bold;"> logger.file<br>
</td>
<td valign="top">Log jk messages to a file. <br>
Name: 'logger'<br>
</td>
</tr>
<tr>
</tr>
<tr>
<td valign="top">level<br>
</td>
<td valign="top">INFO<br>
</td>
<td valign="top">Log level. Supported: ERROR, INFO, DEBUG<br>
</td>
</tr>
<tr>
<td valign="top">file<br>
</td>
<td valign="top">$(server.root)/logs/jk2.log</td>
<td valign="top">Log file. <br>
XXX you may be able to change this at runtime, to implement rolling<br>
</td>
</tr>
<tr>
<td valign="top" colspan="2"><span style="font-weight: bold;">logger.apache2</span><br>
</td>
<td valign="top"><br>
</td>
</tr>
<tr>
<td valign="top">level<br>
</td>
<td valign="top">INFO<br>
</td>
<td valign="top">see logger.file<br>
</td>
</tr>
<tr>
<td valign="top" colspan="2"><span style="font-weight: bold;">channel.socket</span><br>
</td>
<td valign="top">A communication transport to a remote Engine<br>
<span style="font-weight: bold;">Magic: </span>The local part of the
name will be the Engine name, to use when defining the uri mappings. For
example channel.socket.local_9009 will automatically define an engine named
local_9009, and if no other setting is set ajp13/ajp13 will be used for communication.<br>
<span style="font-weight: bold;">Magic: </span> If no channel is defined
in the config, a default channel will be constructed with port=8009, engine=DEFAULT,
worker=ajp13 - named 'channel.socket.DEFAULT<br>
</td>
</tr>
<tr>
<td valign="top">port<br>
</td>
<td valign="top">8009<br>
</td>
<td valign="top">Port where tomcat is listening<br>
</td>
</tr>
<tr>
<td valign="top">host<br>
</td>
<td valign="top">localhost<br>
</td>
<td valign="top">Remote host<br>
</td>
</tr>
<tr>
<td valign="top">protocol<br>
</td>
<td valign="top">ajp13<br>
</td>
<td valign="top">the protocol to be used to forward the requests.
No other value is supported at this moment.<br>
</td>
</tr>
<tr>
<td valign="top">api<br>
</td>
<td valign="top">ajp13<br>
</td>
<td valign="top">API to be used when forwarding the requests. No
other value is supported at this moment, ajp14 will be used to indicate that
the Engine supports additional API methods like autoconfig<br>
</td>
</tr>
<tr>
<td valign="top">secretkey<br>
</td>
<td valign="top">NULL<br>
</td>
<td valign="top"><span style="font-weight: bold;">Magic:</span> the
secret key will be set automatically on the associated worker<br>
</td>
</tr>
<tr>
<td valign="top">lbfactor<br>
</td>
<td valign="top">1<br>
</td>
<td valign="top">Load balancing factor to use. At this moment, it'll
be set on the worker, but in future it<br>
should be possible to use lb on a channel level.<br>
</td>
</tr>
<tr>
<td valign="top" colspan="2"><span style="font-weight: bold;">worker.ajp13</span><br>
<br>
</td>
<td valign="top">The forwarding worker using the ajp13 RPC
protocol. It supports the basic ajp13 API and may support additional functions/APIs
in future like ajp14 API<br>
</td>
</tr>
<tr>
<td valign="top">secretkey<br>
</td>
<td valign="top">NULL<br>
</td>
<td valign="top">XXX deprecated - set it on channel ( socket needs
it, jni doesn't, with unix we can use smarter things ).<br>
Special attribute to be sent with the first request, used to authenticate.
Supported by Tomcat3.3 and tomcat4.x if the authentication is configured,
leave it NULL for tomcat3.2<br>
</td>
</tr>
<tr>
<td valign="top">lbfactor<br>
</td>
<td valign="top">1<br>
</td>
<td valign="top">XXX deprecated - set it on channel. <br>
Load balancing factor to use when <br>
</td>
</tr>
<tr>
<td valign="top"><br>
</td>
<td valign="top"><br>
</td>
<td valign="top"><br>
</td>
</tr>
</tbody>
</table>
<h3>Example</h3>
<pre>logger.level=DEBUG<br># That's created by default if no other channel is defined<br>channel.socket.DEFAULT.port=8009<br>channel.socket.local_9009.port=9009<br><br># that defines automatically a worker named<br># 'tomcat1' and an 'engine' named tomcat1<br>channel.socket.tomcat1.host=host1.my.com<br>channel.socket.tomcat1.lbfactor=0.5<br><br>[uri:/examples/*]<br># Automatically define the lb worker and sets balanced_workers<br># for this particular uri.<br>engine=DEFAULT,tomcat1<br><br>[uri:/examples2/*]<br># the /examples2 is only available on tomcat2<br>engine=tomcat1<br><br></pre>
<h3>Alternatives</h3>
<pre>logger.level=DEBUG<br><br>[channel.socket:tomcat1]<br>host=host1.foo.com<br>port=8009<br>lbfactor=0.5<br><br>[channel.socket:DEFAULT]<br># no property here, but the channel will be constructed<br># with the default properties<br><br><br><br><br></pre>
</body>
</html>
1.1 jakarta-tomcat-connectors/jk/doc/jk2/jk2.html
Index: jk2.html
===================================================================
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title></title>
</head>
<body>
<h2>Jk2 architecture</h2>
<br>
<h3>Definitions</h3>
<ol>
<li>Engine. This is a tomcat instance, running in a java process. Each
engine must have a unique ID, and can be reached by multiple protocols over
multiple transports</li>
<li>Worker. A worker is the object serving ( processing ) the request.
It can either forward it to a servlet Engine, to another worker or generate
content itself ( status ). The important worker is "ajp13" implementing a
simple/fast RPC mechanism. </li>
<li>Channel. A channel represents a transport protocol, connecting 2 sides
for RPC communication. The most common and standard is the tcp socket. Other
important channels are unix socket and jni, which are not yet fully supported. </li>
<li>Endpoint. An endpoint represents an established connection between
the web server and the java engine. The connection is reused, and multiple
endpoints can exist and be active at the same time for one server/engine
pair. </li>
<li>Logger. The logger reports jk errors and debug statements. The goal
is to use the native server logging whenever possible. At this moment there
is a single logger, in future we may be able to associate loggers with individual
webapps. </li>
<li>Config. The config stores and manipulates parameters for each jk object. </li>
<li>Uri ( XXX is it a good name ? ). A uri stores a pattern that is used
to match requests, and asociated properties. </li>
<li>UriMapper. This implements the matching of requests against uri patterns. </li>
<li>WorkerEnv. The central controller, it controls global properties and
provides access to all other objects. </li>
</ol>
<h3>Configuration architecture </h3>
<p>Jk2 is using a mechanism similar with JMX to manage all its configurable
objects. Each component is controled by a "jk_bean" structure, containing
pointers to the setAttribute/getAttribute functions.</p>
<p>The config object abstracts the persistent repository for config informations.
Most components/properties can be configured at runtime. A runtime change
can be made either directly on the object, affecting the running instance
only, or to the config object, making it persistent. <br>
</p>
<p>The status worker provids a basic interface for setting/getting runtime
config information, similar with the manager app in tomcat or the jmx web
interface. Other workers could provide enhanced functionality ( like the ajp14
extensions ). <br>
</p>
<h3>Communication protocol</h3>
<p> Jk2 supports multiple communication protocols ( RPC-style ) and multiple
transports. In addition, each communication protocol supports multiple "APIs",
or sets of functions that are supported. <br>
</p>
<p>The current protocol is called AJP13. It supports marshalling/unmarshalling
of strings and ints, with minimal overhead. <br>
</p>
<p>The current API is also called ajp13. It consist of 5 methods:<br>
</p>
<ul>
<li> (oneway) forwardRequest (2): the marshaled request is encoded as parameter. </li>
<li> (oneway) sendBodyChunk (3): sends the output of a request </li>
<li> (oneway) sendHeaders (4): sends the marshaled headers </li>
<li>(oneway) endResponse (5): marks the end of the response </li>
<li> (req/resp) getBodyChunk (6): get the POST body.</li>
</ul>
<p> It is desirable to migrate to a standard protocol for encoding and RPC
( CDR, XDR, etc ), and to support additional protcols ( like WARP ). However
the AJP13 protocol is stable and shouldn't change in future. <br>
</p>
<p>The ajp13 API is also stable and frozen. In future, what will be called
'ajp14' may provide additional functions. ( using the same name for API
and protocol is very confusing, but that's what we have. We should at least
call them consistently "ajp13 protocol" and "ajp13 api" ) <br>
</p>
<h3>Low level components </h3>
<p>Jk2 uses a object oriented style, allowing multiple implementations for
each object. The model is based on the style used in JNI ( and a bit Corba
C bindings). Each function takes as parameter a pointer to an execution context
( jk_env ), a pointer to its own object structure, and the normal parameters.
<br>
</p>
<p>Jk_env is not completed, but it'll support basic exception handling (
JNI style ), a local pool, etc. <br>
</p>
<p>In addition, each configurable component has as the first member a jk_bean
pointer, pointing to the JMX-like dynamic configurator. The jk_env stores
a table with all the known 'types', and a constructor for each.<br>
</p>
<p> Each object has a name, either specified explicitely or generated from
it's type. The object name has the type as prefix. Jk_env also stores a
table with all existing 'instances', by name. <br>
</p>
<p>It is assumed that all 'top level' objects will be long-lived ( including
endpoints ). <br>
</p>
<h3>Default configuration</h3>
<p>Jk2 uses a config file ( jk2.conf ) in the style of a .properties or ini
file. It can be configured to use any other backed that provides similar
capabilities.<br>
</p>
<p> The config file is user editable, but mod_jk will persist the changes
requested by protocol. If you manually change the file while jk is working,
your changes will be lost. The config file supports no comments at this
moment. We'll allow a limited form of comments that can be persisted. <br>
</p>
<p>The configuration defines properties for each configurable component.
A simple form of substitution is used, where $(property) will be replaced
with a previously defined setting. Each setting consists of an object name
and a property, with the associated value. The property name is a simple
string, with no '.' in it. The name can be anything, but it must have a known
'type' as prefix. <br>
</p>
<p>2 formats are supported: <br>
</p>
<pre>NAME.PROPERTY=VALUE <br>and<br>[NAME]
PROPERTY=VALUE
<br></pre>
<p>In addition to the configuration file, properties can be set from the
main server config file - but those will not be modifiable. <br>
</p>
<p>Properties with no type prefix will be stored as 'global' properties.
<br>
</p>
<p>The first time a name is found, the object will be created using the type
prefix ( by looking for the longest match on all known types ). <br>
</p>
<h3>Default values / guessing</h3>
<p>Each component will do the best effort to detect it's environment and
set default values, to minimze the user effort. <br>
</p>
<p>On startup, jk2 will set few global settings: <br>
</p>
<ul>
<li>fs = file separator, / on unix, \ on windows</li>
<li>ps = path separator, : on unix, ; on windows</li>
<li>so = plaftorm extension for libraries ( .so, .dll, .nlm )</li>
<li>(TODO) arch = system architecture</li>
<li>(TODO) server.root = base directory for the server ( same as ServerRoot
for apache )</li>
</ul>
<p>All those are either compile time or extracted from the running server,
and can be used to construct other settings. A separate document defines
all the supported properties and 'magic' that is used to automatically configure
the object and simplify the config.<br>
</p>
<h3> Source code structure </h3>
<p>Each interface "foo" is defined in a file include/jk_foo.h. If the interface
has a single ( or base ) implementation, it'll be called common/jk_foo.c.
If it has multiple implementations, the files will be named jk_foo_bar.c.
All server-specific files are in server/[SERVER] ( server/apache2, etc
). The apache13 objects should be used as a basis for new servers, apache2
has a number of extra fancy features to be used as model for 'deeper' integration.
The default set of types is defined in common/jk_registry.c, common/jk_registry.h.
Additional types can be defined at runtime in the server adapter or various
other components. </p>
</body>
</html>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>