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.
The jk_config object abstracts the persistent repository of 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 ( by directly calling the object method or setting the field ), or
via jk_config, making it persistent.
The config API can be accessed using AJP14 messages, using a simple worker
( like the status worker ) or by any other mean.
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.
The current protocol is called AJP13. It supports marshalling/unmarshalling
of strings and ints, with minimal overhead.
The current API is also called ajp13. It consist of 5 methods:
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.
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" )
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.
Jk_env is not completed, but it'll support basic exception handling (
JNI style ), a local pool, etc.
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.
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.
It is assumed that all 'top level' objects will be long-lived ( including
endpoints ).
Jk2 uses a config file ( jk2.conf ) in the style of a .properties or ini
file. It can be configured to use any other backend that provides similar
capabilities.
The default 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.
The default configuration format . . 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.
2 formats are supported:
TYPE:NAME.PROPERTY=VALUE
and
[TYPE:NAME]
PROPERTY=VALUE
In addition to the configuration file, properties can be set from the
main server config file - but those will not be modifiable.
Properties with no type prefix will be stored as 'global' properties.
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 ).
Each component will do the best effort to detect it's environment and
set default values, to minimze the user effort.
On startup, jk2 will set few global settings:
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.
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.