Routing
achieve automatically routes requests to resources within your application. The directory tree containing those resources is the application space.
Security
The application space is also the boundary for resources accessible through HTTP requests. Achieve restricts HTTP request path resolution to resources within the application space.
Servlets are not restricted to the application space. They can access resources elsewhere on the server using normal Node.js file-system operations.
let private = path.resolve(session.appPath, "../private");
Application space
Default routing is established with mandatory setAppPath(). setAppPath() sets the location of the application space. It can be located anywhere accessible to the server.
For example, using forward slashes as a portable convention (not an achieve requirement):
achieve.setAppPath("C:/projects/myApplication/");
After this call, C:/projects/myApplication/ is the root of the application space and request paths are resolved within that directory.
Request URL /hello/hello.htm maps to C:/projects/myApplication/hello/hello.htm
TIP: To create a refactoring-friendly private area, reached only from your servlets, use the session.appPath parameter in the servlet.
let private = path.resolve(session.appPath, "../private");
Custom Routing
achieve provides three levels of control over routing: the location of the application space, individual asset mappings, and subtree mappings. Custom routing is configured in the server startup file using setAppPath(), setRouteMap(), and setPathMap().
Exact asset route mapping
An exact route map can give an individual resource a different public URL. You can include multiple mappings in one object or make additional calls to setRouteMap().
achieve.setRouteMap({
"/products": "/services/catalog/list.jss"
});
Only the exact public path is mapped. Other request paths continue to use normal automatic routing unless another mapping applies.
Subtree mapping
setPathMap() maps a public path prefix to another directory subtree in the application space.
achieve.setPathMap({
"/docs/": "/internal/documentation/"
});
The part of the request path following the mapped prefix is preserved and appended to the mapped application-space path.
/docs/start.htm
/docs/reference/http.htm
are translated to:
/internal/documentation/start.htm
/internal/documentation/reference/http.htm
Overlapping path mappings
If more than one path mapping matches a request, the most specific matching prefix is used.
achieve.setPathMap({
"/public/": "/content/",
"/public/docs/": "/documentation/"
});
A request for:
/public/docs/start.htm
uses the /public/docs/ mapping because it is the longer matching prefix.
The order in which the mappings are defined does not determine which one wins.
Routing order
achieve checks routing in this order:
- exact route mapping
- path/subtree mapping
- automatic application routing
An exact mapping therefore takes precedence over a path mapping. If neither applies, achieve uses normal automatic routing within the application space.
Routing changes location, not processing
A routing map translates a public request path to a resource in the application space. After the translation, achieve processes that resource in the normal way.
The mapped resource may be a static file, JavaScript Servlet, or another resource type supported by achieve. Routing does not require a different application programming model.
The original request URL remains the public URL requested by the client. Application code can therefore continue to use the request information supplied through session.request.