Migrating to Appweb 4

Appweb 4 is a major upgrade from Appweb 3. It incorporates many new features and upgrades. It also changes many APIs and interfaces.

Compatibility with Appweb 3

To date, Embedthis has made every effort to preserve compatibility, however, with Appweb 4 we needed to make some important improvements that made this impossible. So, 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 4 quickly becomes a stable platform going forward. Please see our Compatibility Policy.

Legacy Appweb Support

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

Changes in Appweb 4

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

New Capabilities

The following new capabilities have been added to Appweb 4 (and have no equivalent in Appweb 3). These additions should not require adjustment for applications developed under Appweb 3.

• Multi-Language support
• Embedded Server Pages (ESP) web framework
• Routing engine with request routing and rewrite
• Integrated content caching
• Enhanced cross-platform building (via Bit)
• High performance event loop architecture
• Extended security sandbox limits
• Flexible request tracing and logging

Changed Capabilities

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

• The core Appweb Http engine has been extracted, enhanced and is now a separate library. All the APIs have a "http" prefix instead of an "ma" prefix.
• Appweb 4 supports the Ejscript 2.X Web Framework. Is is a major upgrade with new integration APIs.
• The stand-alone Appweb command line program is upgraded with new switches and options.
• The build system is upgraded and simplified. It now uses the Ejscript Bit build system. New configure options and cross compiling capabilities have been added.

Removed Capabilities

• The EGI handler has been removed and deprecated in favor of the ESP handler which has equivalent and extended functionality.

Changed APIs

Many of the internal APIs in Appweb 4 have been changed. This is due to the utilization of a common Http library between Appweb and Ejscript. Appweb 3 APIs have been renamed/converted on a function by function basis to equivalent APIs in Appweb 4. The APIs have very similar names to the previous counterpart.

Memory Allocator

Appweb 4 includes a high performance memory allocator and generational garbage collector. The allocator is a fast and immediate coalescing allocator. It is optimized for frequent allocations of small blocks and uses a background collector for freeing unused memory.

The garbage collector is somewhat unusual in a C program. However, garbage collection is especially well suited for long running applications like a web server since it virtually eliminates memory leaks. Unlike traditional memory allocation where free must be called, Appweb 4 uses the opposite approach where memory that must be retained needs to be actively managed to prevent garbage collection. This means that a managed reference must be held for all active memory. See Memory Allocation for more details.

Migrating Appweb Configuration Files

The Appweb 4 configuration file is substantially the same as the Appweb 3. Include directives can now contain wild cards and there are several new directives supporting Routing, Multi-language support and the Embedded Server Pages web framework. The big change is that Route directives replace the Directory and Location directives.

Routes vs Directory/Location Directives

Appweb 4 uses a more flexible Route directive instead of the Appweb 2/3 Directory and Location directives. The Route directive has more flexibility and allows powerful regular expression URI parsing and routing. In nearly all cases, Location and Directory directives should easily migrate to Route directives.

See Configuring Appweb and Configuration Directives for more details.

Migrating Modules and Handlers

Appweb 4 modules use modified API signatures to initialize with Appweb. In Appweb 4, the MPR module is pre-created and passed into the module. See the Creating Modules document for more details.

In many cases, the new Embedded Server Pages (ESP) web framework provides a simpler and more flexible way to add functionality to Appweb compared with custom handlers and modules. ESP allows the easy binding of "C" language functions to request URIs via powerful Controllers and the Appweb routing engine. See the Using ESP document for more details.

Embedded Server Pages

ESP is the single biggest change in Appweb 4. ESP is a powerful Model/View/Controller web framework that offers:

• Transparent compilation of ESP programs and web pages
• Embedded C code directly in web pages
• Template web pages with layout pages
• Caching of compiled ESP and web pages
• Caching of generated request responses
• Model/View/Controller framework
• Ajax jQuery integration and support
• Native code level performance
• Compact memory footprint

Migrating CGI Programs

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

Migrating EGI Programs

The EGI handler has been deprecated and removed. EGI programs should be migrated to use the ESP web framework.

Ejscript

Ejscript is now a separate product, but the Ejscript handler is fully supported. Ejscript has been upgraded to Ejscript version 2.X.

More Information

For more details, please read

• Appweb Change Log
• Using Ejscript