Creating a Web Application

by Andrew Taylor <andy@benow.ca>

The BeNOW Web API is a light and powerful dynamic web application framework, which hopes to make web application development as easy as possible, while being high performance and easy on system resources. This tutorial will demonstrate the creation of a new web application. Once the web application has been created it will be ready to have pages added, services provided, etc.

Contents

Creating a New Web Application
Command Line Arguments
Starting in an IDE

Creating a New Web Application

To begin this tutorial, you'll need to grab benow-launch.jar. Save it into a new directory created for the project. Open a terminal/command line and do java -jar benow-launch.jar ProjectMaker --with web. This will fetch, extract and configure a new web project. The created directory structure is as follows:

bin - scripts for launching the application, including bin/web.sh or bin/web.bat
build/java - location for compiled java
docs - documentation
etc - configuration information
html - root for files which may be accessed, including html, pages, images, css, etc
html/admin - administration pages
html/css - css styles used in html/pages
html/css/page.css - css for site style across pages
html/images - images used within pages/html
html/images/logo.png - logo used across pages
html/js - javascript libraries
lib/java - java libraries
lib/xsl - xsl libraries
src/java - java source
var - miscellaneous project resources
var/site - site page look and feel includes

Your basic web application is now ready for customization. You can launch the web application in it's basic form by doing bin/web.sh (un*x) or bin/web.bat (windows) from the project directory within a terminal/command window. This will start the basic web framework. You will be prompted to provide a password for the admin user. Database tables, users, and initial configuration will be created and the web server will start at http://localhost:8080/. Check it out with a browser, and see the sample index page, which provides links for administering the application. The application can be stopped by hitting control-c in the terminal. You're now ready to customize your web application.

Command Line Arguments

The standard web service is started by the class org.benow.web.WebService. It provides several switches to guide behavior. By passing --help to bin/web[.sh|.bat] the following options can be seen:

org.benow.web.WebService [-h val] [-p val] [--ssl] [--ssl-port val] [--ssl-keystore val]
 [--ssl-keystore-password val] [-s val] [-n val] [-b val] [-k] [-t] [--admin-pass] [--help]
Runs a servlet using jetty.
  -h,--html-base:  Directory from which static html content is served. (default: html)
  -p,--port:  Port on which the web-app is to listen. (java.lang.Integer,default: 8080)
  --ssl:  Also create ssl connector
  --ssl-port:  Port on which the web-app is to listen (by default is --port value + 2 (ie 8082).  If --port 
               is 80 and --ssl is provided, default ssl port is set to 443). (java.lang.Integer,default: 8082)
  --ssl-keystore:  Keystore file for ssl cert 
               (http://jetty.mortbay.org/jetty5/faq/faq_s_400-Security_t_ssl.html) (default: etc/ssl/keystore)
  --ssl-keystore-password:  Password for ssl keystore
  -s,--servlet:  Servlet class. (java.lang.Class,default: org.benow.web.WebServiceServlet)
  -n,--name:  Servlet name (default: /)
  -b,--bind:  Host or Interface IP to bind to (defaults to all)
  -k:  Start kill monitor, allowing the start of other instances to kill this one. (Useful for debugging).
  -t:  Terminate existing instance and exit
  --admin-pass:  Set admin password
  --help:  Show help

With these options, it's possible to change the port, start ssl, bind to an ip, etc. The -k argument is quite useful. When provided, an old instance of the application will terminate when another instance is started. This allows for quick cycling of the application and helps to make for speedy development. Arguments can be passed directly to the [.sh|.bat], added to the [.sh|.bat] file or by editing bin/web.env, adding an args=[args...] line and regenerating the .sh|.bat with ant setup. Further customization can be had by creating a WebService descendant.

Starting in an IDE

The basic or custom web service can easily be started in an IDE, such as Eclipse. One of the original reasons for the design of the Web framework was to simplify debugging. There is no deployment descriptor, no app server or other support pieces to have in place in order to have things done. Add a task which has org.benow.web.WebService or your custom descendant as the main class and include all jars within lib/java, and it will spark up. You can then place breakpoints within services and other code to validate functionality. When starting in an IDE, the -k argument is quite useful. By using it application turnaround can be very quick. There is no need to terminate previous instances, as old instances will be stopped automatically, and the new code can be used immediately.

Take note that when starting in an IDE, the benow jars should be on the classpath, as the packager mechanism depends on loading files from the jar.

Once the web service is started, login with a web browser (the default address is http://localhost:8080/) and you will be prompted to set the password for the 'admin' user. Once this is set, you will be logged in as the administrator and have full access to customise your web application. Until the admin password is changed, there will be no access to the rest of the application. Ensure to do this immediately after first startup, as anyone can change the admin password at this time (the admin pass, if changed or forgotten, can be reset via the --adminPass command line argument). Be sure to choose a good password, as the admin user has full control over the site.

The BeNOW tutorials are a work in progress. If you have any comments or suggestions, please email <andy@benow.ca>.