Modules
The functionality of the Roxen Challenger web server is implemented as
modules. There are no difference between a module delivered with Roxen
Challenger and a module made by a third-party. All parts of the Roxen
API are available to any module.
A module is a .pike file, with appropriate methods
implementing the module API. It must contain contain a
register_module() method, that returns information
about the module such as what type of module it is. The module type
determines all further interactions between Challenger and the module.
Almost all modules contain configuration variables, that can be
changed in Challenger's configuration interface. These variables are
defined by calling the defvar() method, usually from
the constructor (the create() method).
In order to get the necessary prototypes and methods for the Roxen
API, modules needs to include module.h and inherit
module. Most modules also inherit roxenlib to get
access to the library methods. Thus most modules begin with:
#include <module.h>
inherit "module";
inherit "roxenlib";
Loading and reloading
Modules are loaded by adding them to a virtual server, with the
Add Module button in the configuration interface. Once a
module has been enabled and configured it will by loaded automatically
when the server restarts.
If you have created or installed a new module you will need to do a
reload on the Add Module page, in order to get it to show
up. If there are any compilation errors the module will not show up,
and the errors will be reported in the Event Log or the
debug log file.
Modules are identified by their file name only. Thus you may not
call your module the same as an existing module, even if it is placed
in a different directory.
If you have changed the a module and want to try the new version
you need to reload it. This is done by pressing the Reload
Module button on the appropriate module in the configuration
interface.
In case there were any compilation errors they will show up
directly when you try to reload the module. The reload will fail and
the old version of the module will keep running while you fix the
errors in the new version.
API methods
The API methods that are available to be called from the module are:
- defvar()
-
is used to register a configuration variable. It is usually called
from the constructor (create() method).
- query()
-
returns the value of a configuration variable.
- set()
-
sets the value of a configuration variable.
- query_internal_location()
-
gives the path to this modules own unique internal mount path.
API methods that the module can implements are:
- checkvar()
-
checks the intended value of a configuration variable when the user
changes it. If the value is not valid an error message can be returned.
- info()
-
shall return a the description of the module, which then overrides the
description given in the register_module module.
- query_name()
-
shall return the name of the module, which then overrides the name
given in the register_module module.
- register_module()
-
returns information about the module, such as which type of module it
is. register_module must be implemented in all
modules.
- start()
-
is called when the module is started, each time a configuration
variable is changed as well as when the module is unloaded.
- status()
-
returns a status message that will be displayed in the configuration
interface.
- stop()
-
is called when the module is disabled or reloaded as well as when the
server is restarted or shut down.
- find_internal()
-
is called when a file is requested from this modules internal mount
path.
Errors
Since Pike is an interpreted language a programming error cannot crash
the program. Instead the Pike interpreter catches and handles
errors. Challenger takes advantage of this by providing error messages
with a full Pike backtrace, making it easy to pinpoint the
problem. The error will be reported sent to the browser as well as
being written in the debug and event log.
That error messages, complete with a Pike backtrace, are written to
the browser is great for programmers debugging their applications. It
might however scare rather than help the average user of a web
site. Therefore it is recommended to turn of such error messages on
production servers, by setting the Global Variables/Show the internals
variable to No.
|