Erinors Liweb Documentation

for version 0.1.0

Written by Norbert Sándor

Introduction

Erinors Liweb is a suite of software components allowing compiled Java code to be executed in modern web browsers using the browser's Javascript infrastructure.

The Liweb suite consists of the following main components:

• Maven archetypes
  Maven archetypes for generating Maven and Eclipse projects.

• BCE Core
  The core BCE system which implements the bytecode emulation and the web browser integration.

• BCE Demo
  Various demo applications demonstrating the features of the Liweb suite.

• BCE console
  Client side console and monitoring tool which allows developers to monintor the currently running BCE application.

• Liweb Core
  High level web application development framework, with main focus on the user interface.

BCE

Introduction to BCE

Getting started with BCE

Setting up the development environment

In this chapter we set up a development environment which allows us to create, develop, run and debug BCE applications. This is the preferred and recommended infrastructure but of course other build tools or integrated development environments may be used as well.

In this book we use Windows XP as operating system but any other operating system will do if it supports Java 6.

Downloading necessary software

The following softwares are needed to be allow to develop BCE applications:

• Java Runtime Environment 6 (the current Liweb version supports only Sun's JRE 6)
  http://java.sun.com/javase/downloads/

• Maven 2.0.8
  http://maven.apache.org/download.html

• Apache Tomcat 5.5.25
  http://tomcat.apache.org/download-55.cgi

• Eclipse 3.4
  http://download.eclipse.org/eclipse/downloads/

• Sysdeo/SQLI Eclipse Tomcat Launcher plugin 3.2.1 (it doesn't have an update site)
  http://www.eclipsetotale.com/tomcatPlugin.html

• Firefox 3 beta 2 (you can use Firefox 2 as well but Firefox 3 seems to have a more stable and faster scripting engine)
  http://www.mozilla.com/en-US/firefox/all-beta.html

Installing the downloaded softwares

You can install the downloaded softwares to any location you want, although it is recommended to use directory and file names without space and special characters.

Installing the Java Runtime Environment

Installation of the JDK is trivial, just run the installer and follow the instructions.

After completion set the environment variable JAVA_HOME to the directory of the JDK. This is a requirement of Maven.

You can test the Java installation by executing “java -version” from the command line:

Installing Maven

Follow the instructions on the download page: http://maven.apache.org/download.html#Installation

You can test the Maven installation by executing “mvn -v”:

Installing Tomcat

Follow these steps:

1. Unzip the Tomcat archive to a directory (this directory is referred to as TOMCAT_HOME).

2. Extract all files from the com.sysdeo.eclipse.tomcat_3.2.1\DevLoader.zip archive to the %TOMCAT_HOME%\server\classes directory.

Tomcat should start without errors by executing the following commands:

1. cd %TOMCAT_HOME%\bin

2. startup.bat

Stop Tomcat by closing the console window.

Installing Eclipse

Eclipse is distributed in an archive file, it doesn't have an installer so it is ready to be used after unpacking.

After unpacking Eclipse, extract the contents of the Sysdeo/SQLI Eclipse Tomcat Launcher plugin archive to the plugins directory of your Eclipse installation.

Start Eclipse by executing eclipse.exe and selecting your workspace location (it is referred to as WORKSPACE_HOME hereafter).

After Eclipse is started, install the TestNG plugin:

• Select Help / Software Updates / Find and Install...:

• 
  Select Search for new features to install:

• 
  Click New Remote Site..., enter TestNG as name and http://beust.com/eclipse as URL, then click Finish.

• 
  Click Finish and select the plugin.

• 
  Follow the further instructions.

The next task is to configure the Tomcat plugin. Select Window / Preferences / Tomcat and set Tomcat version and Tomcat home:

Finally, configure your newly created workspace with Maven by executing mvn eclipse:add-maven-repo -Declipse.workspace=%WORKSPACE_HOME% then restart Eclipse.

Creating your first BCE application

Creating a “quick-start” application is relatively simple using Maven archetypes. Execute the following commands from the command line:

1. cd %WORKSPACE_HOME%

2. mvn archetype:create -DarchetypeGroupId=com.erinors.bce -DarchetypeArtifactId=erinors-bce-archetype -DarchetypeVersion=0.1.0 -DremoteRepositories=http://www.erinors.com/developer/maven2 -DgroupId=com.erinors.liweb.book -DartifactId=liwebbook-firstapp

3. cd liwebbook-firstapp

4. mvn compile

5. mvn eclipse:eclipse

If nothing went wrong then your first application is generated and it is ready to be imported to Eclipse. Choose File / Import then General / Existing Projects into Workspace:

Browse your workspace directory and click Finish:

The imported project appears in the Package Explorer:

Running your first BCE application

First register your application in Tomcat by selecting the project's Tomcat Project / Update context definition context menu:

Then start Tomcat with the Start Tomcat button in the toolbar:

Tomcat should start successfully in a few seconds. Open and try the application in Firefox by entering the http://localhost:8080/liwebbook-firstapp/ URL. Among others there is a trivial “Hello World” example, let's try it:

Modify the text if you would like then click the button “say hello”. A text box appears with the usual hello message:

When you click the “say hello” button, the compiled version of the following method is executed by the web browser - purely in Javascript:

public static void sayHello(final String name)
{
JsObjects.getGlobal().callMember("alert", "Hello " + name + "!");
}

Debugging your first BCE application

BCE distinguishes between production and development mode. When you have run the application in the previous section, it was running in production mode, which means the client side part of the application was executed purely in Javascript. In development mode client side code is executed on the server using a real (not an emulated) Java runtime environment which makes easy debugging possible.

Switching between production and development mode is only a matter of configuration, there is a configuration property indicating which mode should be used.

Let's run first application in development mode. First stop Tomcat using the Stop Tomcat toolbar button:

Then open the web.xml file:

Then change the com.erinors.bce.devMode property to true:

When you start Tomcat again, you can notice the following text on the console: INFO: DevServer started, localhost:1099. It means that BCE is ready to debug your application. Let's add a breakpoint at the Utils.sayHello() method:

Now start the application in Firefox exactly the same way as before (you may have to trust the application because currently it is signed with a generated private key). There is one difference, an image appears at the top right corner of the page:

This is the BCE development mode applet which acts as a gateway between the web browser and the application's code running on the server.

If you click the “say hello” button, the debugger will suspend the execution of the application at the breakpoint:

Configuring BCE

Java-Javascript interaction

Javascript to Java interaction

Calling Java methods from Javascript

Javascript to Java conversion rules

Java to Javascript interaction

Accessing the global Javascript scope

Java to Javascript conversion rules

When a Java object is passed to Javascript (either as a function argument or as a property value) the following rules apply: