Inside Liferay's Request Lifecycle
When a browser hits a Liferay page, it feels like one atomic thing happens: HTML comes back. In reality the request travels through a long, well-defined pipeline of servlet filters, portal-level dispatch, layout resolution, and multiple portlet lifecycle phases. Most Liferay bugs that feel mysterious - a filter not firing, a portlet rendering stale data, a redirect looping - are simply stages of this pipeline behaving exactly as designed. Once you can name the stages, you can reason about where things go wrong.
It starts with servlet filters
Before Liferay's own code runs, the request passes through a chain of servlet filters. These handle concerns like GZIP compression, character encoding, caching headers, single sign-on, and security. Filters run in a defined order and each one can short-circuit the request, modify headers, or wrap the request and response objects. If a request never seems to reach your code, a filter earlier in the chain is often the reason.
- Filters are ordered - a filter registered with a lower ordering runs first and can decide the request never continues.
- Filters wrap the request and response, so downstream code may be reading a modified version of what the browser actually sent.
- Auth and SSO filters commonly redirect before the portal servlet ever sees the request, which is why login loops live here.
The Main Servlet takes over
After the filter chain, the request reaches Liferay's central servlet. This is where the portal identifies the company (virtual host), resolves the current user, sets up the thread-local context, and determines which layout - the Liferay term for a page - the URL maps to. A great deal of the 'invisible' state that portlets rely on later is established right here.
This stage is also where the permission checker is bound to the thread. If you have ever wondered where the permission decisions that later govern rendering actually originate, this is the point at which the current user's identity becomes available to everything downstream.
Layout and theme resolution
Once the target layout is known, Liferay resolves the theme, the layout template (the structural grid of the page), and the set of portlets placed in each column. The theme decides the outer HTML shell; the layout template decides the arrangement; the portlets provide the actual content. This separation is why the same portlet can look completely different across two sites - the surrounding theme and template changed, not the portlet.
The two-phase portlet lifecycle
Portlets do not simply render. They follow a two-phase model borrowed from the portlet specification: an action phase and a render phase. This distinction is the single most important thing to internalize about Liferay request processing.
| Phase | When it runs | Purpose |
|---|---|---|
| Action | Once, on form submits or action URLs | Change state: save data, process input, set render parameters |
| Render | Possibly many times per page | Produce markup from current state; must be side-effect free |
The rule that follows from this is strict: never mutate data in the render phase. Render can be triggered multiple times - for the portlet itself and again when other portlets on the page cause a re-render. If you write to the database during render, you will get duplicate writes and race conditions that are nearly impossible to reproduce.
@ProcessAction(name = "saveEntry")
public void saveEntry(ActionRequest request, ActionResponse response) {
// Correct place to mutate state.
String title = ParamUtil.getString(request, "title");
_entryService.addEntry(title);
// Pass data to render via render parameters or redirect.
response.setRenderParameter("status", "saved");
}
@Override
public void render(RenderRequest request, RenderResponse response) {
// Read-only. This may run several times per request.
super.render(request, response);
}Resource serving and AJAX
There is a third phase worth knowing: the resource-serving phase. When a portlet needs to return JSON, a file download, or an AJAX fragment without re-rendering the whole page, it uses a resource URL. This bypasses the full page pipeline and lets a single portlet respond directly, which is how most modern interactive portlets talk to the server without a full reload.
Why this matters for debugging
Almost every hard Liferay problem becomes tractable once you locate it on this pipeline. A missing header is a filter issue. A wrong user context is a Main Servlet or authentication issue. Content that looks right on one site but not another is a theme or layout issue. Duplicate saves are a render-phase violation. A slow page is usually one portlet's render phase, not the platform.
The request lifecycle also explains why caching sits where it does. Fragment and portlet caches wrap the render phase precisely because render is meant to be repeatable and side-effect free - a property the two-phase model guarantees.
Conclusion
Liferay's request lifecycle is not magic; it is a predictable sequence of filters, dispatch, resolution, and phased portlet execution. Learn to place any symptom on that sequence and debugging shifts from guessing to tracing. The engineers who move fastest in Liferay are the ones who can point at a bug and say exactly which stage produced it.