How apache/roller works
1. Overall shape
Apache Roller is a single Java web application with a layered monolithic architecture. The main runtime is the app module, which packages the webapp, business services, persistence mappings, templates, and UI actions. It is typically deployed to a servlet container such as Tomcat, with a relational database behind it.
2. Top-level Maven modules
The repo is organized into a few clearly separated projects: app for the product runtime, assembly-release for distribution packaging, docs for user/install/template documentation, it-selenium for browser-level integration tests, and db-utils for Derby test support. The root pom.xml ties these together.
3. Request entry points
HTTP traffic enters through web.xml and is split across several interfaces:
• the main blog rendering pipeline under ui/rendering/servlets
• the admin/editor UI under Struts2 actions in ui/struts2
• public APIs under webservices such as AtomPub, XML-RPC, OAuth, OpenSearch, and tag data
• auxiliary endpoints for media, comments, trackbacks, previews, and feeds
4. Web UI composition
The application has two major presentation styles:
• Struts2-backed admin/editor screens for managing users, weblogs, entries, templates, media, comments, and configuration
• Velocity-driven public site rendering for weblog pages, feeds, and themes
The UI layer is heavy on JSPs, Tiles layouts, Velocity templates, and UI-specific action beans/interceptors.
5. Core domain and service layer
Most application logic sits in weblogger/business and planet/business. These packages define managers and service interfaces for users, weblogs, entries, bookmarks, media files, comments, themes, properties, search, pinging, threads, and OAuth. The WebloggerFactory/WebloggerImpl and PlanetManager are the main access points to these subsystems.
6. Persistence boundary
The application uses JPA for most persistent state, with implementation classes under business/jpa and ORM metadata in resources/org/apache/roller/.../*.orm.xml. This is where entities such as users, weblogs, entries, comments, permissions, ping queues, media files, and theme/template records are stored. The database is an external dependency and the codebase includes SQL scripts for multiple vendors.
7. Content rendering pipeline
Public weblog requests are parsed into request objects, mapped to the correct page/feed/resource model, then rendered by Velocity. The rendering layer includes request mappers, model loaders, pagers, and Velocity resource loaders. Themes and templates are first-class runtime assets, so page rendering depends on both database-stored template metadata and filesystem/theme resources.
8. Background work and scheduling
Roller performs several asynchronous or scheduled jobs in business/runnable and tasks. These include hit-count processing, scheduled entries, cache warmup, ping queue processing, planet refresh tasks, and static planet generation. The task system uses worker threads and leasing/locking to avoid duplicate execution across nodes.
9. Search and indexing
Search is handled as a separate subsystem under business/search/lucene. Weblog entries are indexed into Lucene, and search requests flow through dedicated models and servlet endpoints. Index updates are triggered by content changes, while search results are rendered as pages or feeds.
10. Caching and performance
There is an explicit caching layer in util/cache and rendering-side caches for pages, feeds, salt values, site-wide content, and planet data. This boundary sits between request handling and the underlying database/templates to reduce repeated rendering and lookup costs. Cache warmup is also part of the scheduled job set.
11. Planet subsystem
The planet packages implement blog aggregation: fetching external feeds, persisting subscriptions/groups, and generating combined planet pages/feeds. It is integrated into the main Roller app through specialized tasks, UI screens, and feed rendering models. Feed fetching uses Rome-based infrastructure.
12. External integrations
Several features cross system boundaries:
• outbound blog pings and auto-pings
• feed fetching from remote sites
• comment spam and validation hooks, including Akismet-style validation
• email notifications via mail utilities
• OAuth and legacy blogging APIs for client integrations
These integrations are service-layer concerns, not UI concerns.
13. Security and startup
Startup and authentication are handled early in the request lifecycle. Filters initialize the app, manage persistence sessions, load security salts, enforce security, and support OpenID/role assignment. There is also a startup/database-install path for first-run setup and schema creation.
14. Static assets and runtime resources
Themes, templates, SQL scripts, localization bundles, logging config, and web resources are all packaged with the app. The runtime therefore depends on both database state and filesystem/classpath assets. The app/src/main/webapp/themes tree is especially important because it defines the visible site output.
15. Testing and deployment
Unit tests cover business logic, utilities, UI helpers, and search. Integration tests are split between DB-related tests and Selenium browser tests. Docker and Docker Compose provide a reproducible demo/runtime path, while the release assembly module creates the official distributable artifacts.
Main entry points: business Business layer · pom.xml Root POM · web.xml Web entry · rendering Rendering
Components 21
Repository
Top-level Maven modules and supporting assets
- Root POM · Coordinates the multi-module build
pom.xml - App module · Main Java web application runtime
app/pom.xml - Release assembly · Builds distributable release artifacts
assembly-release/pom.xml - Docs · User, install, and example documentation
docs/README.md - Selenium ITs · Browser-level integration test suite
it-selenium/pom.xml - DB utils · Derby lifecycle and database test helpers
db-utils/pom.xml
App runtime
Main Roller web application and its internal architecture
- Web entry · Request routing and filter/servlet wiring
app/src/main/webapp/WEB-INF/web.xml - Core UI · Startup filters, security, and UI session handling
app/src/main/java/org/apache/roller/weblogger/ui/core - Struts2 UI · Admin and editor actions, beans, and interceptors
app/src/main/java/org/apache/roller/weblogger/ui/struts2 - Rendering · Request mapping, models, pagers, and Velocity rendering
app/src/main/java/org/apache/roller/weblogger/ui/rendering - Web services · AtomPub, XML-RPC, OAuth, OpenSearch, and tag data
app/src/main/java/org/apache/roller/weblogger/webservices - Business layer · Managers and domain services for Roller
app/src/main/java/org/apache/roller/weblogger/business - JPA persistence · JPA-backed managers and ORM-mapped domain state
app/src/main/java/org/apache/roller/weblogger/business/jpa - Lucene search · Indexing and search operations for weblog content
app/src/main/java/org/apache/roller/weblogger/business/search/lucene - Planet · Feed aggregation, subscriptions, and planet rendering
app/src/main/java/org/apache/roller/planet - Background tasks · Scheduled jobs, leasing, and worker threads
app/src/main/java/org/apache/roller/weblogger/business/runnable - Caches · Application and rendering caches
app/src/main/java/org/apache/roller/weblogger/util/cache - Runtime assets · Themes, Velocity templates, SQL scripts, i18n, and config resources
app/src/main/resources - Web assets · JSPs, static assets, themes, and web.xml runtime resources
app/src/main/webapp
Support
Packaging, tests, docs, and utilities
- Database · Relational database used for application persistence
- Servlet container · Host runtime such as Tomcat or similar servlet engine
Connections 27
- Root POM → App module: builds · Aggregates the main application module
- Root POM → Release assembly: builds · Includes release packaging
- Root POM → Docs: includes · Carries documentation and examples
- Root POM → Selenium ITs: builds · Runs browser integration tests
- Root POM → DB utils: builds · Provides DB test support utilities
- App module → Web entry: starts at · Servlet and filter entry wiring
- Web entry → Core UI: routes to · Initialization, security, and session filters
- Web entry → Struts2 UI: routes to · Admin/editor Struts2 actions
- Web entry → Rendering: routes to · Public weblog rendering pipeline
- Web entry → Web services: routes to · API endpoints and protocol handlers
- Core UI → Business layer: uses · Delegates to managers and services
- Struts2 UI → Business layer: uses · Admin/editor actions call service layer
- Rendering → Business layer: loads from · Fetches weblog, theme, and content data
- Rendering → Caches: accelerates · Caches pages, feeds, and shared data
- Rendering → Runtime assets: renders with · Velocity templates and theme resources
- Business layer → JPA persistence: persists via · JPA manager implementations back the domain model
- Business layer → Lucene search: indexes via · Updates and queries Lucene indexes
- Business layer → Background tasks: schedules · Background jobs and worker execution
- Business layer → Caches: uses · Business-side caching and warmup
- Business layer → Planet: integrates · Planet aggregation hooks into the core app
- JPA persistence → Database: stores in · Relational persistence backend
- Background tasks → Database: coordinates · Uses locking and scheduled work against stored state
- Web services → Business layer: calls · Protocol handlers delegate into managers
- Web services → Database: reads/writes · API operations ultimately reach persisted state
- App module → Servlet container: deploys to · Packaged as a servlet webapp
- Runtime assets → Web assets: shapes · Templates and runtime assets drive the visible site
- Planet → Runtime assets: uses · Feed and theme configuration resources