The LSP Application Manager

The Lua Server Pages (LSP) Application Manager is designed as a boot loader for loading, starting, and stopping Lua Server Pages Applications in a running system.

The purpose of the application manager is:

There are two LSP Application Manager versions:

The resources required by the browser based editor embedded in the LSP Application Manager occupy considerable amount of read only memory and we have for this reason designed the LSP Application Manager to load resources from realtimelogic.com. This means that when the browser requests static resources, the browser is redirected to the resource files stored at realtimelogic.com. The batch file BuildLspZip.cmd assembles the minimum set of resources required by the LSP Application Manager. The included makefile includes an option for building a full resource file, which does not rely on resources from realtimelogic.com. Note that the LSP Application Manager for the Mako Server is assembled by using the full set of resource files.

Getting Started

The LSP Application Manager is designed to run in anything from deep embedded systems without a file system to high level operating systems such as Windows and Linux. Your Barracuda App Server SDK comes with a pre-compiled LSP Application Manager for your host operating system.

Loading, starting, and stopping LSP applications

Start the server, use a browser and navigate to "New Application". The "New Application" folder makes it possible to load deployed LSP applications and non deployed LSP applications.

Application types: Loading one of our example programs:
  1. Start the pre-compiled WFS server (found in the bin directory) on your host computer if you plan on using the network file system NetIo (net) in the LSP Application Manager.
  2. In the LSP Application Manager, click the "New Application" folder.
  3. Select the "disk" file system or select the "net" network file system if you are running the LSP Application Manager on an embedded system without a native file system.

    The NetIo is similar to a network file system and makes it possible for the server to access resources on another Barracuda server.

    The NetIo is a web file manager client specifically designed to operate a remote HttpResMgr aka the Web File Manager. In other words, the remote HttpResMgr's file system appears as a local file system to the code using an instance of the NetIo.

    You will get a severe performance degradation when using the NetIo since the NetIo generates multiple requests for each resource fetched. The following diagram illustrates a page request using the NetIo:

    Browser        Embedded System         Web File Manager
      |                   |                       |
      |    get page       |                       |
      | --------------->  |                       |
      |                   |  stat (file exists?)  |
      |                   | --------------------> |
      |                   |         yes           |
      |                   | <-------------------  |
      |                   |                       |
      |                   |   get fragment 1      |
      |                   | --------------------> |
      |                   |    fragment 1         |
      |     response      | <-------------------  |
      | <---------------  |                       |
      |                   |                       |
      |                   |   get fragment 2      |
      |                   | --------------------> |
      |                   |    fragment 2         |
      |     response      | <-------------------  |
      | <---------------  |                       |
      |                   |                       |
      |                   |                       |
    

    Opening a ZIP file over a NetIo

    It is possible to open a deployed LSP application over a NetIo, though opening the ZIP file takes time since the Barracuda ZIP File System does multiple disk seeks and read operations for each file inside the ZIP file, when initializing the ZIP File System. The larger the ZIP file, the longer it takes to initializing the ZIP File System. You should not resubmit the request when opening a ZIP file. Simply wait for the operation to complete.

    The NetIo speed is directly proportional to the speed of the TCP/IP stack being used in the embedded system. The faster the TCP/IP stack, the faster the NetIo will respond.

    Configure the net file system as follows:
    1. The bin directory contains a pre-compiled Web File Server. Start bin/wfs.
    2. Make note of to the port number used by the server.
    3. In the LSP Application Manager, select the net file system and click browse.
    4. Enter the path http://hostip:port/fs/, where hostip is your host computer's IP address and port is the port number the wfs executable is listening on.
    5. Press the "Submit" button.
    6. Continue with step 9 below.
  4. Click the "Browse" button and navigate to a new empty directory or create a new directory in the tree view by right clicking on a parent directory.
  5. Click the "Submit" button.
  6. Select an application name.
  7. Click the Submit button.
  8. The application manager automatically navigates to the "Application-List" folder.
  9. Click the start radio button to start the application.
  10. The started application shows up as a link in the "Active LSP Applications" list.
  11. Click the application link to navigate to your new application or click the Edit button next to the application link if you wish to start the integrated development environment.

Block Diagram

The LSP Application Manager includes the Barracuda Embedded Web Server which we will also refer to as the Barracuda Application Server, the Barracuda plugins, C startup code, and the LSP Application Manager. The LSP Application Manager is a Lua application embedded into the executable and is best visualized as LSP firmware. The LSP firmware is a compressed 250Kbyte ZIP file stored inside the executable and made available to the Lua Virtual Machine via the ZipIo -- i.e. the Barracuda ZIP File System.

The LSP Application Manager's Component Diagram:

LSP Application Manager

The LSP Application Manager is shown in red in the top left corner in the above diagram. The LSP Application Manager is loaded, by the Lua VM, at startup from the embedded ZIP file.

The "C startup Code", which can be found in the subdirectory src/lsp.c in the Barracuda App Server SDK, is responsible for assembling an application server. The C code is similar to the code described in the getting started guide. As an example, the C code initializes the Lua Virtual machine and loads the .config Lua script. The .config Lua script, loaded from the embedded ZIP file, initializes the Barracuda Virtual File System for the LSP Application Manager.

The .config and .preload scripts

The .config script is run when the C code initializes the Lua Virtual Machine. The .config script is run only one time at system startup. You do not have access to the .config script in the Application Manager, unless you replace the Application Manager's LSP application or modify the Lua/LSP code. The Application Manager's LSP files can be found in the lsp subdirectory. A new Application Manager executable must be built if you modify this code.

The .preload script is the LSP application's version of the .config script. The .preload script is executed by the LSP Application Manager when the LSP application is started. The optional .preload application script can, for example, be used to configure a database for the application or configure the Virtual File System for the application when the application starts. Many of the LSP applications we provide contain a .preload script for initializing the application.

The Lua environment where the .preload script executes is made available as the "app" table in LSP pages. This means that a global variable such as myConfigData created by the .preload script can later be accessed in an LSP page as app.myConfigData.

The .preload script is useful if you design a device with an application similar to the LSP application manager -- i.e. if you design an application for loading multiple LSP applications. The .preload script is not managed by the Barracuda Application Server, but by the LSP Application Manager.

The following code fragment from lsp/.config shows how the LSP application manager loads and executes the .preload script. You must have a good understanding of Lua environments in order to understand this code.

-- Create a resource reader by using the provided
-- application name and I/O
local resrdr=ba.create.resrdr(
   not rootapp and app.name or nil,app.prio,io)
if resrdr then
   -- Directory must be inserted before ".preload" to make
   -- dir:baseuri work properly when .preload is run.
   if rootapp then
      resrdr:insert()
   else
      lspappmgr.dirs.rootDir:insert(resrdr)
   end
   local ok=true
   local appenv
   if io:stat".preload" then
      local f
      -- The application's "app" environment table
      appenv=setmetatable({io=io,dir=resrdr},{__index=_G})
      appenv.app = appenv
      -- Load the application's preload script
      f,err = io:loadfile(".preload",appenv)
      if f then
         -- Execute the application's preload script
         ok, err = xpcall(f,errh)
         if ok then err=nil end
      end
   else
      print(fmt("Info: %s/.preload not found",path))
   end
   if not err then
      -- Enable LSP in the resource reader
      resrdr:lspfilter(appenv)
      lspappmgr.apps[app.name]=resrdr
      app.running=true
      return true
   end
   resrdr:unlink()
   if not err then
      err= ".preload failed"
   end
else
   err="Cannot create resrdr"
end