Introduction
The page publishing service is an OSGi service that provides functionalities to versionize, publish, and archive pages.
The publishing process
There are two user roles in the publishing process:
- Editors: Editors create and edit (draft) versions (of pages).
- Publishers: Publishers review those versions and approve or deny them.
The standard publishing process looks as follows:
- An editor creates and edits a new draft version of a versionable resource (eg. a page)
- After editing the version, the editor sets the status of the version to "proposed"
- At some time in the future a publisher inspects the proposed version and either denies or approves it. The state of a denied version is set back to "draft" (and the process continues at step 2), while the state of an approved version is set to "approved". Before a version can be approved, the publishing start date has to be set. This is the time when the approved page will go live.
- An approved version goes live if:
- its publishing start date is reached
- the method goLive() of the corresponding Version object is invoked (Version.goLive()) - A version stays live until:
- its publishing end date is reached.
- another version of the same versionable resource goes live.
- the method goOffline() of the corresponding Version object is invoked (Version.goOffline())
A live version is no longer modifiable, except its publishing end date. - After the version has gone offline, its status is set to "archived" and is no longer modifiable at all.
PagePublishingService
The org.clerezza.cms.pagepublishing.PagePublishingService is an OSGi service, and is the entry point to the page publishing functionality. It provides methods to get versionable resources and versions.
Versionable resource
A versionable resource is a UriRef resource in the content graph that is backed by the page publishing service. It allows the creation of different versions, which MAY appear under the versionable resource URI in the content graph. A VersionableResource object is retrieved over the PagePublishService.getVersionableResource()-method*,* which takes the versionable resource URI as argument. The returned object provides methods for creating new versions and retrieving existing versions.
Version
A Version object represents a version associated with a VersionableResoure. The object provides methods for accessing and manipulating the version triples, and to configure its page publishing configuration. The page publishing configuration is also saved in form of triples in the same graph as the version triples, therefore triple manipulation should be done cautiously (This should be improved sometime).
The class Version extends GraphNode. Through the GraphNode's methods you gain access to the triples of the version.
The class Version provides the following configuration methods:
| Method |
Description |
|---|---|
| propose() |
Changes the status of this version from DRAFT to PROPOSED. A proposed version is ready to be inspected by a publisher. |
| approve() | Changes the status of the version from PROPOSED to APPROVED. An approved page is ready for publishing. It is published immediately (goes live) if the publishing start date is the current date or lies in the past. The publishing start date has to be set before a version can be approved, but after approval the publishing start date can still be modified as long as the version has not gone live or been archived. |
| deny() |
Changes the status of the version from PROPOSED or APPROVED back to DRAFT. |
| goLive() |
Makes the version a live version. Its status is set to "live". If there was already a live version before, then the publishing end date of that live version is set to current date. If pagePublishingService.automaticallyCreateApproved equals true (default is false), then a new approved version of the old live version is created, with the same publishing start and end date. If pagePublishingService.automaticallyCreateDraft equals true (default is true), then a draft version of this version is created. pagePublishingService.automaticallyCreateApproved and pagePublishingService.automaticallyCreateDraft can be configured over the apache web console or over the OSGi configuration admin. Changes to the version will be committed. |
| goOffline() |
If the version is live then this method removes it from the live graph and sets its status to "archived". Its publishing end date is set to now. If there is an approved version in the proposal graph which could go live now, then it goes live as the successor of this version. If there are serveral possible successors (approved versions whose publishing start date already passed), then the version with the latest publishing start date is used. If pagePublishingService.automaticallyCreateDraft equals true (default is true), then a draft version of the successor version is created. If pagePublishingService.automaticallyCreateApproved equals true (default is false), then a new approved version of the this is created, with the same publishing start and end date. pagePublishingService.automaticallyCreateApproved and pagePublishingService.automaticallyCreateDraft can be configured over the apache web console or over the OSGi configuration admin. |
| setPublishingStart() |
Sets the publishing start time. The publishing start time is the date and time when the version should go live. If the version status is "approved" then calling this method will commit (this will commit all changes on this version, not only the publishing start date). |
| setPublishingEnd() |
Sets publishing end time. The publishing end time is the date and time when the version should go offline. If the version status is "approved" or "live" then calling this method will commit (this will commit all changes on this version, not only the publishing end date). |
After modifying the version, the changes have to be committed to take place.
Copying of Version Triples
The page publishing service uses a simple and unsophisticated way to copy a version, because there is momentarily no way to determine what triples are part of a page or not. Ideally a copy mechanism would consider the ontology of the resource to be copied to determine what triples to be copied, but the page publishing copy mechanism does not. Instead it just copies the sub-graph containing all triples which are reachable through forward traversal starting from resource to be copied.
Versioning of Triples
To prevent conflicts between versions all version triples are versionized.
Versioning triples happen if
- a resource is imported with VersionableResource.importResource() or
- a draft version of an existing version is created with Version.createVersion()
- an approved version is published
This means that to all UriRefs the unique version number is added as the first path segment of the URI: e.g. http://localhost:8080/\[version-number\]/myPage. Furthermore, all BNodes are replaced with new BNodes, otherwise could different versions "melt" together.
It is not always desirable to versionize a UriRef, for example there is no need to versionize the RDF:type property. To prevent the versioning in those cases, there are certain predicates marked to be unversioned. The consequence is that objects of triples with such a predicates will not be versioned. The default unversioned predicates are:
WWF.headerImage, WWF.chosenConcep, WWF.media, WWF.linkedTo ,WWF.download, DIGITALASSETMANAGER.icon, PAGEPUBLISHING.versionOf ,RDF.type, FOAF.mbox ,DC.contributor ,DC.creator
Additional unversioned predicates can be specified over the felix web console or over the OSGi configuration admin (org.clerezza.cms.pagepublishing.PagePublishingServiceImpl with property name "unversionedPredicates").
Page publishing graphs
The page publishing service manages versions in three (actually four) graphs:
- the proposal graph (http://tpf.localhost/proposal.graph): It contains all version that are currently in the publishing process which have one of the states "draft", "proposed", or "approved". The UriRefs of the versions contain a version number. Each version has meta properties (e.g. publishing start and end or the version status) which are used by the publishing service.
- the archive graph (http://tpf.localhost/archive.graph): It contains the version that are currently live (status "live") and all previously published versions (status "archived"). They also have meta properties and their UriRefs are versionized.
- the live graph (http://tpf.localhost/live.a.graph and http://tpf.localhost/live.b.graph): It contains a copy of the versions that are currently live without the version numbers in their UriRefs. Also there are no meta properties. The live graph is a content graph addition, therefore the live versions will appear at their versionable resource's URI. The page publishing service uses two (identical) live graphs to prevent inconsistent states while versions change.