How Healdan Extends LogicalDOC

Healdan is a fork of LogicalDOC Community Edition 9.3.1. It goes its own way, but still merges upstream’s fixes, so its own work stays out of upstream’s files wherever it can.

LogicalDOC’s Modules

• logicaldoc-util is at the bottom, and logicaldoc-core builds on it.
• The feature modules build on core: logicaldoc-webservice (SOAP through CXF, and REST), logicaldoc-webdav, logicaldoc-cmis, logicaldoc-dropbox, logicaldoc-android and logicaldoc-ios.
• logicaldoc-webapp is the WAR that bundles everything. logicaldoc-gui is the GWT client, and depends only on util. logicaldoc-i18n holds the message bundles.

Plugins

Almost every module is a JPF plugin, and a plugin takes four pieces:

1. src/main/resources/plugin.xml declares its id, what it needs, and the extensions it adds.
2. A class extending com.logicaldoc.util.plugin.LogicalDOCPlugin can register servlets, scheduled tasks and loggers when the plugin installs.
3. src/main/assembly/assemblyplugin.xml packages a *-plugin.zip.
4. An artifactItem in logicaldoc-webapp/pom.xml copies the zip into the WAR. Without it, the plugin isn’t shipped.

Core’s plugin.xml defines the extension points other plugins hook into, such as DbInit, DocumentListener, FolderListener, Task, Feature and SystemInfo. logicaldoc-dropbox is the smallest complete plugin to learn from.

Spring and Hibernate

• web.xml starts com.logicaldoc.util.spring.MainContext. It scans com.logicaldoc for @PluginContext classes and imports the webapp’s context.xml, which defines the datasource, the session factory and transactions.
• Entities are JPA-annotated @Entity classes. DAOs follow one pattern: an interface XxxDAO and an implementation HibernateXxxDAO.
• Both Spring and Hibernate scan only com.logicaldoc, so code in any other package isn’t found.

Healdan’s Code

• healdan-core is Healdan’s plugin. It holds Healdan’s server rules and all its data, under com.logicaldoc.healdan, where the scans find it with no edits.
  • Its GUI code is in logicaldoc-gui, under com.logicaldoc.gui.frontend.client.healdan, reached from one-line hooks in upstream’s GUI classes.
  • Its servlets register with @WebServlet. Its RPC paths are /frontend/healdan* and its data paths /data/healdan*.
  • Its listeners enforce Healdan’s rules on every route into the server: the web UI, the API, WebDAV and CMIS.
• Its own tables. Flyway owns the tables whose names start hd_, and only those. A change ships as a new script under healdan-core/src/main/resources/healdan/db/migration/, never as an edit to one that has shipped. Healdan never changes the structure of LogicalDOC’s ld_ tables.
• One-time setup steps in com.logicaldoc.healdan.seed create what Healdan needs inside LogicalDOC, such as the Everyone group and the Healdan profile. Each records that it ran in hd_setting, and never runs again, so a new default ships as a new step.
• HealdanHooks in logicaldoc-core lets the few places in LogicalDOC that write without telling its listeners ask Healdan first. Every refusal throws HealdanVetoException, which the document and folder DAOs roll back on.
• Upstream edits are kept small, and each milestone’s design spec lists every upstream file it edits, with the reason.