Home > Programming Guide > Migrating to Appweb 3

Quick Nav

See Also

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 2013 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.

Changed Capabilities

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

Removed Capabilities

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.

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);

Migrating ESP Applications to Ejscript

The upgrade to Ejscript from ESP is the single biggest change in Appweb 3. ESP was a minimal subset of the JavaScript language with a trivial embedding in HTML pages. Ejscript supports these capabilities, but adds many upgrades and a complete web framework. The bigger changes in Ejscript vs ESP are:

Appweb 3 and Ejscript supports two modes of operation for web pages:

Appweb 2 only supported stand-alone web pages. Appweb 3 continues this support, however the Ejscript HTTP API has changed significantly.

The request object has different properties and the headers, server, cookies, files, and local objects have been removed. Appweb 3 has a more ordered set of objects and properties. A http object stores information about the server, the request object stores request information and the response object contains response related information. The form object has been renamed params.

Here is a section from an Appweb 2 web page:

if (request["REQUEST_METHOD"] == "POST") {
    var ok = form["ok"];
    if (ok == "Cancel") {
        redirect(request["HTTP_REFERRER"]);
    } else if (ok == "New Session") {
        destroySession();
        createSession(120);
    } else if (ok == "Ok") {
        session["name"] = form["name"];
        session["address"] = form["address"];
        application["appData1"] = form["appData1"];
    }
}
write("Using session: " + request['SESSION_ID']);

And here is the same section for an Appweb 3 web page:

if (request.method == "POST") {
    var ok = params["ok"]
    if (ok == "Cancel") {
        redirect(request.referrer)
    } else if (ok == "New Session") {
        destroySession()
        createSession(120)
    } else if (ok == "Ok") {
        session["name"] = params.name
        session["address"] = params.address
    }
}
write("Using session: " + request.sessionID)

Post Back

In Appweb 2, a common paradigm was to POST form data back to the same web page. This was called "Post-Back" and was popularized with the Microsoft ASP.NET framework. However, it has become clear that Post-Back mingles application logic with web views in a very unscalable way. Appweb 3 and Ejscript offer a Model / View / Controller framework that is vastly superior to Post-Back. Post-Back is still supported, but not encouraged.

More Information

For more details, please read

© Embedthis Software LLC, 2003-2013. All rights reserved. Embedthis, Appweb, ESP, Ejscript and Embedthis GoAhead are trademarks of Embedthis Software LLC.