Embedthis Appweb 4.3.4
Home > Programming Guide > Migrating to Appweb 3

## Quick Nav

- Appweb 2 Compatibility
- Appweb 2 and Appweb 3 Support
- Appweb 3 Changes
- Migrating Config Files
- Migrating Modules
- Migrating Handlers
- Migrating CGI Programs
- Migrating EGI Programs
- Migrating ESP

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

- 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.
- Added new Ejscript Web Framework.
- 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 Ejscript Web Framework replaces Embedded Server Pages.
- 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);

## 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:

- Full ECMAScript-262 language support instead of just a subset of JavaScript
- High performance VM based design
- Stand-alone or integrated JavaScript compiler
- Caching of pre-compiled scripts and web pages
- Model / View / Controller framework
- Integrated SQLite database
- Ajax library support
- Extensive class library
- Web page templating engine
- Extended HTTP integration with Appweb
- E4X XML parsing support
- Much higher performance
- Smaller memory footprint (no need to compile script at run-time)
- Better scaling for larger JavaScript applications

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

- Stand-alone web pages
- MVC Web applications

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

- Appweb Change Log
- Using Ejscript
- Ejscript Documentation

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