Alfresco DevCon 2010 (Paris and New York)
This session starts by giving an overview of components of an Alfresco content model. We then examine the various forms of call-backs and hook-points available to the developer and give some examples of how these can be used to enforce custom business logic and model consistency.
3. • About me
• I’ve been with Alfresco since early 2007
• primarily working in the core repository team
• worked for various companies in UK & California
• I enjoy flying hot-air balloons ;-)
• Spelling
3
• to be consistent I’ll stick with the British spelling
• Modelling <=> Modeling
• Behaviour <=> Behavior
• About you
• Modelling vs Behaviours … how much time (50/50) ?
• I’d like to allow enough time for
• Q & A and general feedback (your experience)
4. How many of you have … ?
• attended training course
• DevCon JumpStart course
• Intensive Developers course
• and/or read
• Professional Alfresco book (chapter 5)
• Jeff Pott’s Alfresco Developer Guide (chapters 3 & 4)
• Alfresco wiki (“Data Dictionary” and related pages)
• and/or hands-on experience
4
• followed examples (eg. Books and/or Alfresco SDK)
• developed your own custom content model & app’
5. Modelling
5
• [something] used as an
example to follow or imitate
• to make [something] conform
to a chosen standard
Behaviour
• the way in which [something]
behaves in response to a
particular situation or
stimulus
6. Embeds a storage engine Domain
• which enables storage of a
potentially arbitrary
network of entity data
6
• content entities
• “metadata” (about the
entities)
• relationships (between the
entities)
• Stores
• store ref(erence)
• root node
• Nodes
• unique node ref(erence)
• Properties
• on nodes
• (Peer) Associations
• from source to target node
• Child associations
• between parent & child node
• primary & secondary
7. Model / domain consistency can be maintained via …
• Content Model + Integrity Checker
• formal model definition
• including built-in constraints
• option to also write & plug-in custom constraints (not specifically
covered here)
• Behaviours
• custom business logic bound to policies
• Rules & Actions
7
• not covered here … see separate session
8. 8
• [something] used as an example to follow or imitate
• to make [something] conform to a chosen standard
9. • Content models
9
• are all about metadata (data that describes data)
• constrain otherwise arbitrary nodes, properties and associations
• are named and define one or more namespaces
• can import namespaces in order to allow references to other models
• must be configured and loaded in dependent order
• “bootstrap” models are statically loaded from the filesystem
(“extensions” classpath) when repo starts
• “dynamic” models are dynamically loaded from the repo
(“Models” space) when models are added or changed
• integrity checks fire when transaction commits
• mandatory can be enforced (else node is marked as incomplete)
10. Dictionary Service
• Get def’ (or all QNames)
• model
• types / aspect
• property
• datatype
• constraint
• association
• also: is sub-class ?
• Also refers to
10
• QName
• NamespaceService (prefix
resolver)
Node Service
• Nodes
• create, move, delete, restore
• Properties
• set, get, remove
• Associations
• create, remove,
• get sources, get targets
• Child Associations
• get children, get parents
• get primary parent
11. 11
Type Aspect
Class
Property
Association
Child
Association
Data Type
Constraint
13. • Node
13
• must be of a given type when created
• can also setType (ie. specialise / change type)
• may have zero or more aspects attached
• either from type or at runtime
• may have a set of properties
• defined by type & aspects (including inherited types & aspects)
• may be associated with other nodes
• defined by type & aspects (including inherited types & aspects)
14. • Property
14
• must be named
• must be of a given datatype
• may be single-valued (default) or multi-valued
• may have zero or more constraints (inline or referenced)
• may be mandatory
• either: enforced
• or: relaxed (if missing, node marked with incomplete aspect)
• may have default value
• may be “residual”
• in this case there is no associated property definition
• can be overridden in terms of inheritance
• to a limited extent – mandatory, default, constraints
15. • Built-in constraint types:
15
• LIST (“ListOfValuesConstraint)
• LENGTH (“StringLengthConstraint”)
• MINMAX (“NumericRangeConstraint”)
• REGEXP (“RegexConstraint”)
• Other examples, eg. RM caveats use:
• “RMListOfValuesConstraint” (extends “ListOfValuesConstraint”)
• You can hook in your own constraint implementations
• implement “Constraint” interface
• typically extend “AbstractConstraint”
• must have default constructor (as it’s used to instantiate it)
• in model, define constraint with “type” attribute set to fully-qualified class name
• make sure you unit test your constraint (it is performance sensitive)
• Constraints execute
• as part of integrity checks prior to commit (ie. at the end of a server transaction)
16. • (Peer) Association
16
• association type is named
• source node may be associated with zero or more target nodes
• may be mandatory
• enforced or relaxed (missing => node marked with incomplete
aspect)
• cardinality can be defined via many / mandatory
• 0 or 1(mandatory = false, many = false)
• 1 (mandatory = true, many = false)
• 0 or more (mandatory = false, many = true)
• 1 or more (mandatory = true, many = true)
17. • Child Association
17
• defined in same way as peer association with extra features
• parent node may be associated with zero or more child nodes
• affects certain operations, eg. delete will cascade
• also defines if child name can be duplicated or unique within parent
• a node can have one primary child association
• a node may have one or more secondary child associations
18. • Don’t forget “the Node Browser is your friend !”
18
• in theory never lies …
• … although be careful with browser back button (JSF issue)
19. • Dynamic models
19
• since 3.0
• reduces need for server restart, also enables multi-tenancy option
• CMIS mapping
• CMIS type, CMIS property, CMIS relationship (peer assoc)
• CMIS document (cm:content), CMIS folder (cm:folder)
• Constraints support title & description (needed by RM)
• since 3.2
• Tightened validation check for content models
• since 3.4
• unfortunately, due to a long standing bug, it has always been possible to define
new model elements using a namespace that wasn't defined by the containing
model (eg. using an imported namespace)
• with the recent bug fix, it is now only possible to create model elements whose
namespace is also defined by the containing model
• “DataModel” split out from “Repository”
• since 3.4
• split into separate JAR / Eclipse project – for future SOLR integration
25. • Many examples “out-of-the-box”
• Search for “*Model.xml” across the Alfresco source tree
• Core model files (with defined namespaces) include:
25
• dictionaryModel.xml
• http://www.alfresco.org (alf)
• http://www.alfresco.org/model/dictionary/1.0 (d)
• http://www.alfresco.org/view/repository/1.0 (view)
• systemModel.xml
• http://www.alfresco.org/model/system/1.0 (sys)
• http://www.alfresco.org/system/registry/1.0 (reg)
• http://www.alfresco.org/system/modules/1.0 (module)
• contentModel.xml
• http://www.alfresco.org/model/content/1.0 (cm)
• http://www.alfresco.org/model/rendition/1.0 (rn)
• http://www.alfresco.org/model/exif/1.0 (exif)
26. • Alfresco modules also provide some great examples, eg.
26
• Records Management (RM / DOD5015)
• dod5015Model.xml
• http://www.alfresco.org/model/dod5015/1.0 (dod)
• recordsCustomModel.xml (dynamically managed)
• http://www.alfresco.org/model/rmcustom/1.0 (rmc)
• Web Quick Start (WQS)
• webSiteModel.xml
• http://www.alfresco.org/model/website/1.0 (ws)
27. 27
• the way in which [something] behaves in response to a particular
situation or stimulus
28. • Policies provide hook points to which you can bind
behaviours to events based on class or association
• behaviours are (policy) handlers that execute specific business logic
• behaviours can be implemented in Java and/or JavaScript
• Behaviours can be bound to a type or aspect
28
• node in the content repository must be of a single type
• node may have one or more aspects attached
• aspects are either inherited from its type (defined by the model)
• or can be attached (or detached) at runtime …
• allowing a node to dynamically inherit features and capabilities
• aspects can be interpreted by the repository to change behaviour
• eg. by the presence of an aspect (even with no properties)
29. • From JavaDoc (org.alfresco.repo.policy) …
The Policy Component manages Policies and Behaviours. It provides the
ability to:
a) Register policies
b) Bind behaviours to policies
c) Invoke policy behaviours
A behaviour may be bound to a Policy before the Policy is registered. In
this case, the behaviour is not validated (i.e. checked to determine if it
Supports the policy interface) until the Policy is registered. Otherwise,
the behaviour is validated at bind-time.
Policies may be selectively "turned off" by the Behaviour Filter.
29
31. • Policy
31
• ClassPolicy (type or aspect)
• AssociationPolicy (peer or parent-child)
• PropertyPolicy (not used)
32. • Search for “*Policies.java” across the Alfresco source tree
• Examples include:
32
• NodeServicePolicies
• before/onCreateNode,
• beforeDeleteNode (don’t use “on”)
• before/onUpdateNode
• onUpdateProperties
• before/onAddAspect
• before/onRemoveAspect
• before/onCreateChildAssociation
• before/onDeleteChildAssocation
• onCreateAssociation
• onDeleteAssociation
• ….
• ContentServicePolicies
• onContentUpdate
• onContentPropertyUpdate
33. 33
• CopyServicePolicies
• before/onCopy
• onCopyComplete
• CheckOutCheckInServicePolicies
• before/OnCheckOut
• before/OnCheckIn
• before/OnCancelCheckOut
• And more …
• VersionServicePolicies
• StoreSelectorPolicies
• AsynchronousActionExecutionQueuePolicies
• RecordsManagementPolicies
• Note: you can define, register and invoke you own custom policies, eg.
• RecordsManagementPolicies <= RecordsManagementActionServiceImpl
34. public interface NodeServicePolicies!
{ !!
!public interface OnAddAspectPolicy extends ClassPolicy!
!{!
! !public static final QName QNAME = QName.createQName(NamespaceService.ALFRESCO_URI, "onAddAspect");!
!
! !// Called after an <b>aspect</b> has been added to a node!
! !public void onAddAspect(NodeRef nodeRef, QName aspectTypeQName);!
!}!
}!
!
public abstract class AbstractNodeServiceImpl implements NodeService!
{!
!// note: policyComponent is injected … (not shown here)!
!
!public void init()!
!{!
! !// Register the policy!
! !onAddAspectDelegate = policyComponent.registerClassPolicy ! ! ! ! ! ! !!
! ! ! ! ! ! ! ! !(NodeServicePolicies.OnAddAspectPolicy.class);!
!}!
!
!protected void invokeOnAddAspect(NodeRef nodeRef, QName aspectTypeQName)!
!{ ! !!
! !NodeServicePolicies.OnAddAspectPolicy policy = onAddAspectDelegate.get(nodeRef, aspectTypeQName);!
! !policy.onAddAspect(nodeRef, aspectTypeQName);!
!}!
}!
!
!
34
35. public class XyzAspect implements NodeServicePolicies.OnAddAspectPolicy, ...!
{!
!// note: policyComponent is injected … (not shown here)!
!
!public void init()!
!{!
! !// bind to the policy!
! !policyComponent.bindClassBehaviour(!
! ! !OnAddAspectPolicy.QNAME,!
! ! !ContentModel.ASPECT_XYZ,!
! ! !new JavaBehaviour(this, "onAddAspect”, ! ! ! ! ! ! ! !
! ! ! !Behaviour.NotificationFrequency.TRANSACTION_COMMIT));!
!}!
!
!public void onAddAspect(NodeRef nodeRef, QName aspectTypeQName)!
!{!
! !// implement behaviour here … (for when aspect XYZ is added)!
!}!
}!
!
35
36. …!
!
//!
// note: usually try to bind on specific class (type/aspect) rather than service method!
//!
!
// class binding – specific type or aspect!
policyComponent.bindClassBehaviour(!
! !NodeServicePolicies.OnUpdatePropertiesPolicy.QNAME,!
! !ContentModel.TYPE_PERSON, !
! !new JavaBehaviour(this, !
! ! ! ! ! !"onUpdateProperties”,!
! ! ! ! ! !Behaviour.NotificationFrequency.EVERY_EVENT));!
!
// service binding – all types/aspects!
policyComponent.bindClassBehaviour( !
! !NodeServicePolicies.OnUpdatePropertiesPolicy.QNAME,!
! !this,!
! !new JavaBehaviour(this, !
! ! ! ! ! ! "onUpdateProperties”,!
! ! ! ! ! ! Behaviour.NotificationFrequency.EVERY_EVENT));!
… !
36
37. • Notification Frequency
• behaviours can be defined with a notification frequency – “every
event” (default), “first event”, “transaction commit”
• consider that during a given transaction, certain policies may fire
multiple times (ie. “every event”)
• can set notification frequency to “first event” or “transaction commit”
• Using Transactional Resource
37
• option to execute logic immediately or queue (eg. via transactional
resource) until commit (beforeCommit and/or afterCommit)
• AlfrescoTransactionSupport.bindResource(K, V)
• V = AlfrescoTransactionSupport.getResource(K)
38. • Behaviours can be temporarily disabled
38
• BehaviourFilter interface
• for current transaction only
• for “class” (type or aspect) or “node + class”
• disableBehaviour
• enableBehaviour
• isEnabled
• for “node”
• enableBehaviours
• for “all”
• disableAllBehaviours
• enableAllBehaviours
• isActivated
• Behaviour interface
• for current thread only
• disable / enable, eg. in try / finally block
• Examples – importer, transfer – disable behaviours
39. • From the perspective of the custom behaviour
• delete is delete (you should not need to care whether it is archived)
• create is create (even if it is restored from the archive)
• Bind to beforeDeleteNode (not onDeleteNode)
• note: will fire for parent and recursively for each of it’s cascade
deleted children (if any)
• Don’t rely (or be dependent) on the archive store
• deleted node may not be archived
• archived node may never be restored
• you should not need to check for archive store
• One exception is peer associations
39
• assocs to “archived” nodes may remain (pending ALF-4119 for 3.4+)
40. “live” store
40
“archive” store
archive://SpacesStore
deleteNode deleteNode
(purgeArchivedNode)
restoreNode
version://version2Store
workspace://SpacesStore
“version” store
deleteNode
createVersion deleteVersion
deleteVersionHistory
41. • More than one handler can be registered for a given policy
• since 3.0
• We now also trigger policies through the type hierarchy
• since 3.4
• if you use earlier Alfresco and yet to upgrade then workaround is to
bind to service bind and use “isSubClassOf” to check type
• You should not need to check for archive store
41
• since 3.3
• operations on archive store no longer fire polices
• also applies to version store
42. • Search through the code for policy bindings or use Eclipse
to find call hierarchy for
• bindClassBehaviour (x2)
• bindAssociationBehaviour (x3)
• Many examples both in core services as well as module
extensions such as
42
• Web Quick Start
• http://wiki.alfresco.com/wiki/
Web_Quick_Start_Developer_Guide#Behaviours
• DOD 5015 (Records Management)
• You can refer to the SDK for a simple example
• Also, for JavaScript Behaviours, refer to *old* RM module
43. • Modelling
• consider using dynamic models during dev & test cycles
• beware of deep class hierarchies
• consider performance of any custom registered constraints
• Behaviours
• consider notification frequency
• add debug logging
• don’t rely on archive store
• can temporarily disable/re-enable (thread or transaction)
• General
43
• start with the SDK and if needed move to complete SVN source tree
• write unit tests (+ve & -ve) to exercise custom models & behaviours
• run existing regression tests (eg. “ant test-repository” or continuous)
• develop and package as an AMP (Alfresco Module Package)
44. • Modelling
44
• integrity checks do not apply to version store
• data model has been split off (eg. for future SOLR integration)
• now only possible to create model elements whose namespace is also
defined by the containing model
• composite content (anticipated for Project “Swift”)
• major model enhancement
• will also impact various foundation services
• see wiki for more details (early draft - subject to change)
• Behaviours
• more than one handler can be registered for a policy
• policies do not fire for archive store & version store
• policies are now triggered through the type hierarchy
• maybe some consolidation & rationalisation
• also potentially new policies (to hook into)
45. • Alfresco wiki / forums
• Books
• Professional Alfresco (Wrox)
• Alfresco Developer Guide (Packt Publishing)
• Alfresco Training courses
• Intensive Developers Course (5 day)
• Fundamentals (2 day) – new
• Advanced Content Modelling – TBC
• and obviously the source code itself J
45
• including modules, such as RM (DOD 5015)
Other foundation services include Content Service, Search Service …
Other higher-level services include FileFolderService, CheckoutCheckInService, VersionService, CopyService …
ALF-680 - Previously valid content models now fail with CMISAbstractDictionaryService$DictionaryRegistry exception (r20488)
CHK-8823 - Dictionary/Constraint improvements (required by MOB-1276) (r15913)
ALF-955 - Deletion of dynamic custom model (Ent 3.2.1 / Com 3.3)
ALF-4119 - NodeService: beforeDeleteNode archiving (WIP – targeted for Com 3.4b)
ALF-3885 - Allow multiple policies through type hierarchy (r21253) (Com 3.4.a / Ent 3.4.0)
CHK-2720 - Fixed AR-401 Can only have one policy handler (r8698)