Migrating to Appweb 3

Appweb 3 is a major upgrade from Appweb 2. It incorporates an extensive set of new features and upgrades to existing capabilities. It also changes many APIs and interfaces.

Compatibility with Appweb 2

We make every effort to preserve compatibility, but with Appweb 3, we needed to make some important improvements that necessitated breaking compatibility with Appweb 2. Rather than make several ongoing compatibility breaks — we decided to make all the changes in one release. In this way we can ensure that Appweb 3 quickly becomes a stable platform going forward. Please see our Compatibility Policy.

Ongoing Support for Appweb 2

To address the needs of users for whom upgrading to Appweb 3 will take some time, we intend to support Appweb 2 till the end of 2014 and to continue to issue updates and upgrades for Appweb 2 during that period.

Changes in Appweb 3

Appweb 3 provides equivalent functionality to that in Appweb 2 in nearly all cases. While Appweb 3 may have a different interface or API, the capabilities of Appweb 2 have been continued in Appweb 3 — and in many cases, the features have been enhanced.

New Capabilities

The following new capabilities have been added to Appweb 3 for which there is no equivalent in Appweb 2. These additions should not require adjustment for applications developed under Appweb 2.

• Appweb manager program to start, monitor and restart Appweb
• Appweb Monitor program for Windows system tray
• Appweb configuration files support include files
• New request processing pipeline
• New request processing filters. New directives to AddInputFilter and AddOutputFilter
• Added platform support for Mac OS X and FreeBSD
• IPv6 protocol support
• Added Visual Studio projects for building on Windows
• Added PAM based authentication

Changed Capabilities

The following capabilities have been changed and may impact your Appweb 2 applications.

• The core of Appweb is now written in C not C++. This was done for portability to some platforms and to eliminate the C API module.
• Moved Chunk and Ranged request processing into modular filters in the Request Pipeline.
• The stand-alone Appweb command line program is upgraded with all new switches and options.
• Removed the windows winAppweb program. In its place, the Appweb manager (appman) starts the standard Appweb program.
• The build system is upgraded and simplified. New configure options and cross compiling capabilities are added.
• The Http client is upgraded with new switches and options. Also now supports SSL, transfer chunk encoding, transparent redirection and IPv6
• The copyHandler is renamed as the fileHandler and is upgraded to utilize the send connector.
• The CGI handler now uses pipes instead of files to communicate with the server.
• The matrixSSL and openSSL modules are removed. The functionality is now built into the SSL module.

Removed Capabilities

• The capi (C API) module has been removed.
• The gaCompat module for compatibility with the GoAhead web server has been removed.
• The adminHandler is no longer supported and has been removed.

Changed APIs

Most of the internal APIs in Appweb 3 have been changed. This is due to moving the Appweb core to the "C" language from "C++". The Appweb 2 APIs have been converted on a function by function basis to equivalent C APIs. For each Appweb 2 API, there is an equivalent Appweb 3 API. These have very similar names to the previous counterpart. When converting applications written for Appweb 2, you should be able to modify your code on a line-by-line basis.

Other Changes

Appweb 3 includes a few other changes worth noting here.

• Module files are renamed mod_NAME and are stored under /usr/lib/appweb/modules. On Windows, they are stored under a "modules" subdirectory.
• New MPR Memory allocator

Appweb 3 provides a high performance memory allocator that provides slab and arena based allocations. When memory is allocated, it is connected to a parent memory block, thus forming a tree of blocks. When a block is freed, all children blocks are automatically freed. Appweb uses this so that when a request completes, one free operation releases all memory allocated by the request. This virtually eliminates memory leaks.

The memory allocation APIs are changed to always take another memory block as the first parameter. This block becomes the parent block for the new allocation. See the Portable Runtime API for more details.

Migrating Appweb Configuration Files

The Appweb 3 configuration file is substantially the same. It does support conditional directive blocks which were introduced in Appweb 2.4. It also supports included configuration files which should not be an issue migrating forward.

Inheriting from Outer Blocks

Appweb 3 makes one change in how directives are inherited by inner blocks. If a Directory, Location or Virtual Host block is defined, it will now inherit the settings from outer blocks. In Appweb 2 the inheritance was not consistent. This is most noticeable when configuring handlers. In Appweb 3, the pipeline and handler configuration will be inherited and this greatly simplifies defining Virtual Hosts or Location blocks. You need to use the Reset pipeline directive to clear inherited pipeline configuration.

See Configuring Appweb and Configuration Directives for more details.

Directory Module

In Appweb 2, the directory module provided directory listings and processed directory redirections when a request was made for a directory URL. This has been problematic for users not wanting directory listings, but still requiring directory redirections.

In Appweb 3, directory redirections are performed by the HTTP core and do not require the directory handler.

Migrating Modules

Modules in Appweb 3 have a different API to register themselves with Appweb.

In Appweb 2 a module looked like this:

SimpleModule::SimpleModule(void *handle) :
    MaModule("simpleModule", handle)
{
}
int mprSimpleModuleInit(void *handle)
{
    new SimpleModule(handle);
    return 0;
}

In Appweb 3, the same module looks like this:

MprModule *mprSimpleModuleInit(MaHttp *http)
{
    MprModule   *module;
    module = mprCreateModule(http, "simpleHandler", "1.0.0",
        NULL, NULL, NULL);
    if (module == 0) {
        return 0;
    }
    return module;
}

See the Creating Modules document for more details.

Migrating Handlers

Handlers in Appweb 3 have a different API to the Appweb 2 equivalent. In Appweb 2, you had to create a module, a handler service and a master handler from which to clone instances. In Appweb 3 this is greatly simplified.

In Appweb 2 a handler looked like this:

SimpleHandlerModule::SimpleHandlerModule(void *handle) :
    MaModule("simpleHandler", handle)
{
    simpleService = new SimpleHandlerService();
}
SimpleHandlerModule::~SimpleHandlerModule()
{
}
SimpleHandlerService::SimpleHandlerService() :
    MaHandlerService("simpleHandler")
{
}
int SimpleHandlerService::setup()
{
}
MaHandler *SimpleHandlerService::newHandler(MaServer *server, MaHost *host, char *extensions)
{
    return new SimpleHandler(extensions);
}
SimpleHandler::SimpleHandler(char *extensions) :
    MaHandler("simpleHandler", extensions,
        MPR_HANDLER_GET | MPR_HANDLER_POST | MPR_HANDLER_TERMINAL)
{
}
MaHandler *SimpleHandler::cloneHandler()
{
    return new SimpleHandler(extensions);
}
int SimpleHandler::run(MaRequest *rq)
{
}
int mprSimpleHandlerInit(void *handle)
{
    new SimpleHandlerModule(handle);
    return 0;
}

In Appweb 3 a handler now looks like this:

static void runSimple(MaQueue *q)
{
}
int maOpenSimpleHandler(MaHttp *http)
{
    MaStage     *stage;
    stage = maCreateHandler(http, "simpleHandler",
        MA_STAGE_ALL | MA_STAGE_VIRTUAL);
    if (stage == 0) {
        return MPR_ERR_CANT_CREATE;
    }
    stage->run = runSimple;
    return 0;
}

See the Pipeline Stages document for more details about creating Handlers.

Migrating CGI Programs

CGI programs should migrate unchanged. The CGI handler in Appweb 3 offers much higher performance by using pipes for I/O instead of files.

Migrating EGI Programs

The EGI API has changed very little. Mainly the arguments have changed.

In Appweb 2 an EGI form looked like this:

static void myEgi(MaRequest *rq, char *script, char *uri, char *query, char *postData, int postLen)
{
    maWriteStr(rq, "

\r\n"); } maDefineEgiForm("/myEgi.egi", myEgi);

In Appweb 3 an EGI form looks like this:

static void myEgi(MaQueue *q)
{
}
maDefineEgiForm(http, "/myEgi.egi", myEgi);