The Servlet Session Object
Every JavaScript Servlet receives a session object.
The session object provides access to the HTTP request and response, parsed request parameters, and achieve services used while processing the request.
The session object provides:
session.request
// complete Node.js HTTP request object
session.response
// complete Node.js HTTP response object
session.params
// request parameters parsed by achieve
session.load()
// loads backend JavaScript modules within achieve's processing mechanisms
session.autoEnd
// controls whether achieve completes normal responses
session.dirPath
// directory containing the current servlet
session.appPath
// root of the application space
session.params
session.params contains request parameters that achieve has parsed for the servlet.
For GET requests, achieve parses parameters from the URL query string into session.params. This includes HTML forms using method="get", which construct the query string from the form data.
For POST requests, achieve parses application/x-www-form-urlencoded form data and application/json into session.params.
For compatibility, a POST request without a Content-Type is treated as application/x-www-form-urlencoded and produces a server warning.
For request data that achieve does not parse, use session.request directly.
session.request
session.request is the complete Node.js HTTP request object for the current request.
Use session.request when application code needs request information or processing beyond achieve's convenience handling.
session.response
session.response is the complete Node.js HTTP response object for the current request.
Use session.response to set headers, status information, or otherwise work directly with the response.
Normally, achieve completes the response after the servlet returns its result. Set session.autoEnd to false when application code needs to take responsibility for completing the response.
session.autoEnd
session.autoEnd is a Boolean property that controls who is responsible for completing a normal HTTP response.
The default is true. Normally, a servlet returns its result and achieve completes the response.
Set session.autoEnd to false when processing must continue after the servlet returns and application code will complete the response itself.
With session.autoEnd set to false, achieve does not automatically inspect the returned value or Promise and does not complete the response when the servlet returns. The application is responsible for eventually completing the response.
Ordinary use of async and await does not require changing autoEnd. If the servlet returns a Promise while autoEnd remains true, achieve waits for it and completes the response from its resolved value.
autoEnd = false does not suppress an error that achieve catches while it can still safely respond. If headers have not been sent, achieve can return its normal 500 response. Once headers have been sent, achieve reports the error and terminates an incomplete response without attempting to replace it with a new 500. Errors in detached asynchronous work after the servlet has returned are the application's responsibility.
exports.servlet = function(session) {
session.autoEnd = false;
session.response.write("Hello ");
session.response.end("World!");
}
session.load()
session.load() loads additional backend JavaScript modules within achieve's servlet processing mechanisms.
CommonJS modules are loaded synchronously. Supported forms include:
session.load("helper.jss");
session.load("helper.jss.cjs");
ESM modules use .jss.mjs. Loading an ESM module returns a Promise and can be awaited:
let mod = await session.load("helper.jss.mjs");
Relative filenames passed to session.load() are resolved from the directory containing the current servlet.
In development mode, modules loaded with session.load() are reloaded when their files change. In production mode, loaded modules are cached for efficient repeated use.
Errors raised while loading or using a module receive achieve's servlet error processing when they propagate through the managed servlet invocation or its returned Promise.
session.dirPath
session.dirPath is the directory containing the currently executing servlet.
Relative filenames passed to session.load() are resolved from this directory.
session.appPath
session.appPath is the root of the application space.
Unlike session.dirPath, it does not change according to the location of the current servlet. It provides a stable reference to the application space configured with setAppPath().
Application code can also use session.appPath when it needs to locate resources deliberately kept outside the HTTP-accessible application space.