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!"});
}