# $Id: README,v 1.2 2002/05/31 10:44:52 helge Exp $

What is ApacheAPI ?
===================

ApacheAPI is a toolkit to write dynamically loadable Apache modules
in Objective-C with a Foundation library like libFoundation or gstep-base.

The intention is not to add another abstraction layer on top of Apache
but only to provide a convenient interface for Objective-C programmers.
The kit provides almost the complete Apache API in the form of Objective-C
classes.

So you can:
- write Apache callbacks using an Objective-C method
- write Apache handlers using an Objective-C method
- write Apache config commands using an Objective-C method
- directly use objects for per-server and per-directory configurations
- use Objective-C wrappers around Apache structures

More abstractions and richer page generation API is left to other 
frameworks which might be build around this kit.

General Procedure
=================

ApacheAPI adds another plain-C module called mod_gsbundle. This module
provides a single configuration function called "LoadApacheBundle" which is
used to load Foundation library NSBundle objects.
Each ApacheAPI modules needs to be implemented as a NSBundle.

After mod_gsbundle loaded the bundle, it instantiates a singleton object
of the principal class of the bundle (set using the Bundle_PRINCIPAL_CLASS
gstep-make macro). 
An object is used instead of the class object itself so that one can easily
use instance variables and because it better supports the reload-semantics
of the Apache config process (this object is recreated for each configure
run !)

Using config files stored inside of the bundle gsbundle now automagically
creates the Apache module, handler and command structures for the bundle
principal object. As soon this auto-generated module is registered with
Apache this object will receive Objective-C messages from Apache.

Apache Specialities
===================

The implementation of an Objective-C module is mostly tricky because
Apache makes use of module *unloading* during it's configuration process.
This easily confuses the Objective-C runtime which currently isn't
prepared to unload objects (neither the NeXT/Apple runtime nor the GNU
runtime).
ApacheAPI solves this problem by the help of another small stub library
which implements the module itself.

Another problem is that the Apache API callbacks mostly lose their 
"identity" after module setup (the callback functions do not receive
a "backpointer" to their module structure). This is worked around by the
kit by providing a stub-generation shell script. The generated code
contains Apache module stubs and a module Objective-C class which is 
used to dispatch the callbacks to Objective-C.

Last but not least, Apache configuration. As mentioned above Apache 
unloads all modules at least once while starting up (and again if a
HUP signal is send). This is because Apache executes the configuration
process *twice*, as Scott Hess says:
---snip---
The standard sequence is:

parent runs through the entire config process.
parent unwinds the entire config process.
parent runs through the entire config process.
parent creates the listen socket(s).
parent forks.
children accept connections.

-X only changes the last two items.  The parent no longer forks, and it
goes into the accept loop itself.  But the config passes are all the same.  
The config passes are the way they are so that when you send a reconfig
type signal, you already know that the parent can unwind the current
config correctly.  Think of it as building up a good config, and then
_immediately_ doing a reconfig.
---snap---
So, don't be confused if your configuration callbacks are called multiple
times :-)

Coredumps of Apache when restarting: This is usually if you installed a
freshly compiled bundle without stopping Apache (I guess because the
bundle is memory-mapped into Apache).

TODO
====

- resolve mem-leaks created by handler and command tables
