This page describes work in progress on providing a WCM Services Layer. It is made up of content that is highly speculative and undergoing rapid revision! We would welcome your comments as this layer is being built.
The following design notes are a work-in-progress. The detailed design, implementation, testing and delivery of WCM services will be scoped according to WCM requirements and priorities. The initial refactor of WCM services will be phased. The following list is indicative, and is subject to change:
Currently WCM assets are stored as a collection of different types of fundamental Alfresco asset types (DM spaces and nodes, AVM stores and nodes, aspects, etc.), which makes interacting with WCM assets time consuming and error prone. The WCM Services Layer will instead surface these objects via a unified POJO domain model, with Java interfaces representing each of the major types of WCM asset. Operations on that domain model (CRUD operations on Web Projects, sandbox-centric operations, etc.) will follow the same 'in-process SOA' architecture used elsewhere in the Alfresco APIs - ie. these operations will not be defined in the domain POJOs themselves, but will instead be defined in one or more stateless Services.
All of the new services defined as part of the WCM Services Layer will be implemented in a test friendly fashion - the code will be amenable not just to unit tests but also to benchmark / scalability tests. For the first release, as much as possible of the code will be validated by unit tests, while a WCM test suite will be added incrementally over time, as a secondary goal.
Except where it makes sense, the new APIs will not duplicate methods that already exist in the AVM APIs, but if this becomes necessary, the methods in the WCM Services Layer will simply delegate to the underlying APIs. Note that at this stage, the only place where duplication might make sense is for basic content operations (read file / write file) in the WebContentService.
The API set is defined in a WCM Asset Service interface that, like other Alfresco Services, will be retrievable via the ServiceRegistry (getAssetService).
This service provides features for adding content to a WCM web project. It provides access to the AVM store in the context of a WCM web project and exposes methods which are friendly to web script/REST interfaces.
This service also provides bulk import to efficiently import large quantities of content.
bulk import (add multiple folders and files, eg. via zip file)
Is this service required at all? For non-Web-Form-backed content I'm not sure that there's much value in providing a higher level API over and above what the AVM already provides. That said, there is some value in having a single 'go to' API for all WCM content access and manipulation needs. Thoughts anyone? Do we need an abstraction layer over the AVM store? Does this service take onboard the XForms stuff ?
The API set will be defined in a WCM Deployment Service interface that, like other Alfresco Services, will be retrievable via the ServiceRegistry. This interface will provide:
Provides CRUD operations on configuring the deployment targets for a web project.
Provides access to deployment reports.
Provides a facade to the existing repo deployment service, to reduce the complexity and make the interface amenable to web scripts.
WCM deployment targets, will include the following properties (note: this list is indicative, not definitive):
* name * display name * hostname * port number * username * password * test server flag * target (FSRs only) * transport adapter
Interface inheritance will be used to differentiate ASRs and FSRs.
Web Project deployment target operations:
enumerate deployment targets, with several variants (eg. findByTargetHostname, listASRs, listFSRs, etc.)
deploy, with several variants (eg. deployCurrentSnapshotToLiveTargets, deploySnapshotNToTargetsXYZ, deployUserSandboxToTestTargetsXYZ, etc.)
Web Project deployment report operations:
enumerate deployment reports, with several variants (eg. findDeploymentReportsByDate, findDeploymentReportsByVersionNumber, findDeploymentReportsByDeploymentTarget, etc.)
enumerate available transports.
Add new service. WebDeploymentService and WebDeploymentServiceImpl
Keep existing DeploymentService
Re-factor code out of org.alfresco.web.ui.wcm.component.UIDeploymentServers
Re-factor code out of org.alfresco.web.bean.wcm.DeploymentUtil;
Re-factor code out of org.alfresco.web.bean.wcm.AVMUtil;
Deployment is async at the moment. Is there any requirement for a blocking deployment?
How do we identify deployments in progress, where do we store the equivalent of a deployment status which (on the JSF client) is a session scoped bean which is only persisted to the database AFTER deployment is complete? Answer, we can't have the equivalent of a session scoped bean so will have to store it on the action. Will have to add API to poll the action service. Will need to refactor the action service and deployment to expose the deployment report.
is a deployment report a html formatted document or a data transfer object ? - Answer the repository/api scripts provides a JSON representation. Then if a futher web studio web script wishes to transform it to HTML so be it. But that's not code in the repository that does that.
just to clarify the deployToNtargets functionailty won't be a single transaction.
The following features are not essential, but are worthy of consideration.
get formatted deployment report
TODO: is this necessary? Will Web Studio require the ability to manipulate Web Forms from day one?
The 'WebForm' domain object will include all of the properties defined for Web Forms, including the following (note: this list is indicative, not definitive):
The API set will be defined in a 'WebFormService' interface that, like other Alfresco Services, will be retrievable via the ServiceRegistry. This interface will provide:
Forms Definition operations (see also new Forms Service)
Form CRUD operations
enumerate all Forms available (to all Web Projects)
Web Form operations:
associate Form with Web Project
enumerate Web Forms associated with a Web Project
update Web Form (ie. with applicable overrides) within context of a Web Project
disassociate Web Form from Web Project
enumerate all content using the Web Form, across all Web Projects
regenerate all renditions for a given Web Form, across all Web Projects
Web Form (XML) Content
TODO: should this be extended to all WCM content, or just Web-Form-backed content?
The 'WebFormContent' domain object will include all of the properties defined for Web Form (XML) content, including the following (note: this list is indicative, not definitive):
* StoreRef (for accessing the content and aspects / properties etc.) * name * author * creation date * modification date * parent Web Project * originating Web Form (represented as a NodeRef to the DM space containing the Web Form)
The API set will be defined in a single 'WebFormContentService' interface that, like other Alfresco Services, will be retrievable via the ServiceRegistry. This interface will provide:
Web Form Content operations:
retrieve Web Form content, with several variants (eg. getByFilePath, getByStoreRef, etc.)
enumerate Web Form content, with several variants (eg. findByType, listByFolderPath, etc.)
query / search for Web Form content
add Web Form content
modify Web Form content
delete Web Form content
Web Form Content rendition operations:
enumerate renditions for Web Form content
regenerate renditions for Web Form content
Miscellaneous Web Form content operations:
'guess' the most appropriate Web Form, given a raw XML document
Note that this API will be fully sandbox aware ie. all operations will require a sandbox context to operate in. TODO: this poses issues for query / search, since that's currently only supported for staging sandboxes.
TODO: is this necessary? Will Web Studio require the ability to manipulate WCM workflows from day one?
The 'WCMWorkflow' domain object will include all of the properties defined for WCM Workflows, including the following (note: this list is indicative, not definitive):
The API set will be defined in a single 'WCMWorkflowService' interface that, like other Alfresco Services, will be retrievable via the ServiceRegistry. This interface will provide:
WCM Workflow operations:
WCM Workflow CRUD operations
enumerate configured workflows for a Web Project (represented as [workflow reference, selection rule] pairs)
retrieve active WCM workflow instances for a Web Project (TBD - is this necessary? - - redundant with new workflow querying capabilities in 3.0?)
associate workflow to Web Project (TBD)
disassociate workflow from Web Project (TBD)
manage workflow association precedence (ie. to allow workflows to be reordered) (TBD)