Achieve — High Level Logic Project. Creating a new meta design pattern.

Friendly in development. Fast in production. Just build your apps. Let Achieve do the rest.

← Back to documentation index

Introduction to Servlets

A servlet is a server program that achieve invokes in response to a request. It is the entry point to your backend processes. The term is well known in the Java web server world. JavaScript Servlets (JSS) use the same basic idea, with the servlet written in JavaScript.

Achieve servlets are rather unique and unconventional in that achieve handles more of the routine tasks such as error checking, returning the response to the client, and in development mode reloading backend code when it’s been changed. This lets you focus more on developing the logic needed by your application. At the same time, it does not restrict you from building whatever you need to build, any way you wish to build it.

Servlet file names have required extensions. CommonJS servlets end with .jss or .jss.cjs. ESM servlets use .jss.mjs. The .jss marker identifies backend JavaScript that achieve executes but does not serve as source.

Requests to run a servlet are routed in the same way as static resources. For example, when the application space is set in the startup file with achieve.setAppPath("c:/appspace/myapp/"), and a client requests /run/servlet.jss, achieve looks for the servlet on the computer at c:/appspace/myapp/run/servlet.jss. See also custom routing.

A servlet must export a function named servlet. achieve calls the function and provides a session object that links the servlet to the current request and the achieve environment. See the Session Object reference for more details.

These examples will return the “Hello World!” text with Content-Type text/plain (default) with response status 200.

CommonJS:

exports.servlet = function(session) {
    return "Hello World!";
}

ESM:

export function servlet(session) {
    return "Hello World!";
}

Async servlets work the same way when the servlet waits for the asynchronous process before returning its result.

exports.servlet = async function(session) {
    let response = await nextCall();
    return response;
}

(If the application will complete the response after the servlet returns, set session.autoEnd to false. See below.)

In development mode (default), you can edit and rerun without restarting the server.

exports.servlet = function(session) {
    let response = "Hello Great Big World!"; // achieve detects change and reloads the servlet
    return response;
}

Achieve handles errors.

exports.servlet = function(session) {
    let response = "Hello Great Big Wo   // ← error
    return response;
}

The server does not crash (both development and production modes). The servlet above returns error code 500 and message: “Failed to load module: SyntaxError: Invalid or unexpected token test.jss:2”.

Using GET in a form, for example, you can use pre-parsed data from the session object.

exports.servlet = function(session) {
    return "Hello, " + session.params.name;
}

In order to have achieve treat additional modules like servlets, load them using session.load(). They will then receive the same automatic reloading and error handling. In production mode, error handling is still on, but for the sake of performance, changed modules are not automatically reloaded.

let mod = session.load("second.jss");

When processing large data sets or streams, you should avoid pre-parsing by achieve. (See Servlet reference for details.) Instead, let the servlet use the request stream directly. See the Session Object reference for details on avoiding pre-parsing.

exports.servlet = function(session) {
    myStreamProcess(session.request); // process the stream directly
}

You can take responsibility for completing the HTTP response by setting session.autoEnd to false. This is required when the servlet returns before an asynchronous process has completed. After the servlet returns, your application is responsible for completing the response and handling errors in the continuing asynchronous work.

exports.servlet = function(session) {
    session.autoEnd = false;

    // async code with callback.

} // servlet returns before process is complete

Response types

The servlet has access to the complete Node.js response object through session.response. For example, application code can set the response type:

export function servlet(session) {

    session.response.setHeader("Content-Type", "application/json; charset=utf-8");
    return JSON.stringify({message:"Hello World!"});
}