Servlets - Types and Uses

An Action

is the most primitive servlet. It's used to give a command to the server when no response is expected - or when the response is processed externally. All servlets implement ActionInterface - defining the execute() method that's called by the connection manager. An action saves references to the request, response and parameter information blocks then calls process() - an Action inherits from this class and must implement the process() method.

The base Adept system includes one Action StopServer that, when given the correct password, will stop the server from the browser/client. The Action includes a go() method that can be used for invoking methods other than the default based on the _action parameter or a dot in the name (see above). If go() is used, the class can implement setup() and teardown methods to wrap common code around the action method called for.

CGI

is a method for Adept to run normal operating system dependant programs as CGI. A CGI program is independent. Anything output from is expected to be able to be rendered by the browser. Scripting languages such as Perl and Python have CGI libraries, but an program can generate a HTTP string and produce a valid display. If the script has an extension of cgi, the you don't need to explicitly mention the CGI servlet as in /mytest.cgi?param1=one. CGI programs of other names can be run if the servlet is explicit - /CGI?mytest.bat?param1=one. In all cases, in true CGI tradition, the output to the console is redirected to the browser.

Batch

is an extension of CGI for normal command-line programs that aren't browser aware. A batch builds up a valid HTTP stream and wraps the program output in <pre> tags so that they'll display as they would on a local terminal.

Exec

is designed for GUI applications where the browser and server are on the same machine. It will execute an operating system program then complete without waiting for interactions. With the Exec class you can create a program launcher using HTML on a web page.

A Service

encompasses the next level of sophistication over an action. It is designed to send information to the server where the responses will be JavaScript commands. It does use go() to call methods other than the default respond method. It is an abstract class, and respond() must be implemented. It contains a protected JavaScript instance for building JavaScript commands to give the browser. It has convenience methods to display a message on the status line and to pop up an alert box.

The Page

consists of a class file of the specified name in the package path and a HTML template file of the form className.template.html. First the target for all operations is set to the calling context/panel. Next, go() is called and if a non-default method is called, Page acts like any other Service. If the default is called, the template is sent, forms are activated and initialise called to continue class-specific initialisation. The JavaScript object allows scripts to be sent both before and after the HTML template. While the class is called Page, it's more often posted to the hidden service window where the HTML contains templates used to change the look and feel of an existing panel.

Processing a HTTP Request

The process has been touched on in The Adept Server Model. Here I'ill document the raw and specific data.

• Each request has complete ownership of their own thread until they respond again to the server.
• You can turn request logs on so that each request is written to the log in full before processing.
• In debug mode, no request is cached in either the browser or the server, so you can change files and see the results immediately.
• If the request URL ends in a slash (/), the default actions are explored immediately; otherwise an action is looked for as:
  • If the file type is registered against a servlet by the server, that servlet is run. The standard system registeres js for Javascript and cgi for CGI; or
  • If the file type is registed by the browser (as part of the request as a mime type) the file is sent directly to the browser for processing. Examples of these are html, gif and jpg; or
  • The request of for a servlet. If the request includes a stop (.), it is considered a defined method in the servlet class, otherwise, the default execute() method is called. Typically an application will use the default execute() for loading the page and defined methods as responses to links and form posts. The servlet method to call can optionally be set with an _action parameter instead.
• If no action is found so far the default actions are explored, treating the URL as a directory or path.
  • A servlet called Index in the package specified by the path. The execute() method is called.
  • A script or program called index.cgi. For unix based systems it will be marked executable. For Windows, cgi needs to be associated with an interpreter.
  • A static html document called index.html
  • A static html document called index.htm

The Adept Server Model

The Adept Development System has as its goal the use of corporate skills and technology to produce shrink-wrap software. One of the core design decisions was to use a DHTML-enabled browser as the GUI. This means that the Adept server is a web/application server in the same family as Tomcat. There are differences: Adept has been developed from the ground up to serve a DHTML client, not a Java Server Pages intermediate.

The Server

At the core there is a Server class that runs in its own thread until it's asked to be closed. The main thread normally just waits for the server thread to complete. The separate threading is mostly a convenience for testing, where the test methods want to spawn a server and send it stuff to test. So the server class has the simple function of waiting for client connections, then spawning off a new Connection object to service them. Some servers attempt to minimise the expense of starting a new thread for each connection by pooling connections, but I considered this a case of the benefit not being enough to cover the risks. Modern HTTP 1.1 protocols keep the same connection for use for as long as they can - typically minutes but often for much longer. And on the other side of the coin, starting a clean thread for each new connection ensures that data won't accidentally survive to be used by another thread. This model is inherently multi-user.

The Connection

Each connection also runs in its own thread. This allows the same server to service multiple connections from the same or different clients. As a standard, most browsers make 2 concurrent connections to the server. A connection survives until the client closes the socket or until it is unused for the timeout period of 5 minutes. The browser will at times close the connection and ask for a fresh one using internal rules of it's own.

The Request

The connection then waits for a request from the client. The first thing a request does is attempt to associate a session. The URL of the request is then parsed. If the command ends in slash(/), the default action is looked for. If a normal action cannot be associated a slash is added and the default action attempted again.

For an action, default or no, the request will first look at the file type of the request - being everything before the ? or end of request back to the last full stop. If a servlet is registered against a file type (as with .js), it is used. Otherwise, if it's one that the client has registered it's sent as-is to the browser. If neither of these occur, the request looks for a Java class that extends from ActionInterface. If all else fails, it's sent back to the client to see if it can be rendered as-is.

The Session

A request looks for a specific browser cookie for the session ID. If there is no cookie a new one is created to send as part of the response. In the disconnected client/server environment, this is the way we keep data for the session - by associating it with a unique cookie. By default this cookie is called AdeptSession - although it can be changed by setting a property called session.cookie.

The session name can be either an automatically generated name for anonymous connections, or the user name once the user has logged in. The anonymous name is a persistent cookie so that related data is kept permanently. If a user logs in this cookie is overridden by a browser session cookie that will be lost when the browser is closed or the user logs off. It's possible to make this cookie persistent for secure machines.

Default Actions

If default actions are given a path only, the server will look for a default action to run - being either a servlet called Index, an external program called index.cgi, or html documents called index.html or index.htm. In general it's better to specify the full action rather than ask the system to search for it.

Registered Servlets

Normally any file with an extension is sent to the browser/client for rendering. This be anything from documents to text files, images, style sheets or JavaScript. Occassionally it will be useful for server classes to know about or filter the information. Currently the only existing example within adept is in loading JavaScript classes. They are registered against a servlet called LoadJavaScript that adds a call to a JavaScript._afterLoad(), which Adept uses to sequence loads and initialisation of Javascript.

Each class is registered in server code using LoadJavaScript.Server.register(), giving it the file extension and a class with an ActionInterface to do the work.

Running a Servlet

A servlet is a class with a com.marringtons.adept.action.ActionInterface interface. Its execute method is called wrapped in a transaction. Any exception will cause a rollback, while a clean return will trigger a commit.