locomotive.org


The Locomotive Developer's Guide

Introduction

The Locomotive is a product which allows you to create dynamic Web pages that are customized for individual users to use in continuous sessions. The Locomotive is written entirely in Java, and so it comes with the advantages of being a multi-platform, object-oriented, multi-threaded programming environment. The Locomotive sits between the web server and the SQL database server, and interacts with both of them. It is the part of the system which allows you to create dynamic HTML content customized for each user, for different situations.

One powerful component of the Locomotive is the Steam command language, which is embedded within HTML document templates and executed dynamically every time a Web page is viewed. The Steam language is easy to learn, so it allows non-programmers to customize the behavior of Web pages easily, with quick turnaround, without a big learning curve. The Locomotive product also has utilities for handling HTML form submissions, logging statistics each time a page is viewed, and converting the results of SQL queries into HTML Tables.

Intended Audience

This manual is intended to be read by developers who wish to implement dynamic website features by writing new modules for the Locomotive. It assumes that you are somewhat familiar with SQL relational databases and the SQL language; the Java programming language and the JDBC Java-to-database API; and HTML. If you are not familiar with any of these topics, we've listed some good books on these topics in Appendix A. However, if you have a ninja's mastery of SQL, Java, JDBC, and HTML, then we suggest that you skim each of the sections below (to acquaint yourself with some common Locomotive API), and then look at some of the example code we provide in src/java/org/locomotive/module/.

Layout of this Manual

This manual is designed to be a detailed tutorial. It is intended to be read easily. It is not a reference book in the format of a dictionary or encyclopedia. However, we have cross-referenced each section in the table of contents and in the index, so that you can quickly refer to the examples when writing your own code. We hope that this manual can jump-start you on your way to writing Locomotive modules. When you start to use more advanced tools, then you can start delving into the Locomotive Java API to learn about all the power tools in the Locomotive world.

This manual is divided into eight chapters:

  1. In the first chapter, we explain where the Locomotive fits in your total web site system -- that is, between your web server and your database server. The Locomotive communicates with both of them. Then, we introduce both modules and services. Modules are the code you right to handle requests, and Services are types of modules. Right now you can use two different services with the Locomotive- Handlers and Servlets; we introduce both. We also discuss how the Locomotive uses a Service Routing Table (like the file "hrt.conf") to route web requests to different modules. Finally, we discuss the GenericHandler class, which is a standard implementation of the Handler class that contains many useful methods, and the analogous LocoServlet class.
  2. In the second chapter, we give a simple example of a GenericHandler, called DisplayPageHandler, which takes a URL and converts it into the file path of a document to display. We see how the "h_uri" local variable of the Handler class is used. We also see how to display a page. Though we don't talk about Servlets, the things you'll learn in this chapter are easily applicable to Servlets you write for the Locomotive.
  3. In the third chapter, we discuss the steps involved in writing a typical module, and we give some suggestions for a plan of attack. We also talk about the positive and negatives of both Servlets and Handlers, so you can make an informed decision about which one you want to implement when you develop your module
  4. In the fourth chapter, we give a more complicated example of a GenericHandler subclass, called LoginHandler, which allows a user to log into the Locomotive system. In this example, we encounter the Steam language, which is embedded within HTML documents to generate dynamic text or HTML. We also see how to use the User class and the Session class, and give you some background information about how the Locomotive handles Session. We also talk abou how to log statistics about each page that is viewed with logEvent(); and how to get data out of an HTML form which a user has submitted.
  5. In the fifth chapter, we look at an example of a module which interacts with the database -- the Graffiti Wall. First, we explain the SQL statements that create a new table in the database. We talk about how to read and write data to the database. We touch on the subject of creating rows for HTML tables. We also discuss the differences between "update" SQL statements vs. "insert" and "delete" statements. Finally, we discuss the advantages and disadvantages of PreparedStatements vs. Statements.
  6. The sixth chapter talks about different methods we've used to debug module code in the past; hopefully these will come in handy as you develop your module.
  7. The seventh chapter introduces the Permissions API. We talk about the objects you can use to create access control for parts of your module, and we describe how we used the Permissions API in Discussion sample module to control access to its administration interface.
  8. In the eighth chapter, we describe some advanced features for getting maximum performance from the Locomotive. "Virtual sessions" is the name of the facility that assigns a user to a particular Locomotive instance for the duration of the user's session. This makes it possible to cache user information in the Locomotive itself, obviating potentially expensive database queries. We discuss one available mechanism for doing this, the Global Cache.