Recently I had the pleasure of going up to NYC to speak with Alfresco customers and prospects about architecting Alfresco solutions and how to align that with efforts around digital transformation. Part of that talk was a slide that discussed a few “do’s and don’ts” of designing Alfresco extensions. Somebody suggested that I write down my thoughts on that slide and share it with the community. So… Here you go!
Stick with documented public APIs and extension points.
Leverage the Alfresco SDK to build your deployment artifacts
During my time in the field I saw some customers and Alfresco developers roll their own toolchain for building Alfresco extensions using Ant, Gradle, Maven or in some cases a series of shell scripts. This isn’t generally recommended these days, as the Alfresco SDK covers almost all of these cases. Take advantage of all of the work Alfresco has done on the SDK and use it to build your AMPs / JARs and create your Alfresco / Share WAR file. The SDK has some powerful features, and can create a complete skeleton project in a few commands using Alfresco archetypes. Starting Alfresco with the extension included is just as simple.
Use module JARs where possible, AMPs where not
For most of Alfresco’s history, the proper way to build an extension was to package it as an AMP (Alfresco Module Package). AMPs (mostly) act like overlays for the Alfresco WAR, putting components in the right places so that Alfresco knows where to find them. Module JARs were first added in Alfresco 4.2 and have undergone significant improvements since introduction and are now referred to as “Simple Modules” in the documentation. Generally, if your extension does not require a third party JAR, using a Simple Module is a much cleaner, easier way to package and deploy an extension to Alfresco.
This should go without saying, but it’s worth saying anyway. In the long run unit testing will save time. The Alfresco SDK has pretty good support for unit tests, and projects built using the All-In-One Archetype have an example unit test class included.
Be aware of your tree, depth and degree matter
At its core, the Alfresco repository is a big node tree. Files and folders are represented by nodes, and the relationships between these things are modeled as parent-child or peer relationships between nodes. The depth of this tree can affect application design and performance, as can the degree, or number of child nodes. In short, it’s not usually a best practice to have a single folder that contains a huge number of children. Not only can this make navigation difficult if using the Alfresco API, but it can also create performance troubles if an API call tries to list all of the children in a gigantic folder. In the new REST APIs the results are automatically paged which mitigates this problem.
Use the Alfresco ServiceRegistry instead of injecting individual services
When using the Alfresco Java API and adding new Spring beans there are two ways to inject Alfresco services such as NodeService, PermissionService, etc. You can inject the individual services that you need, or you can inject the ServiceRegistry that allows access to all services. On the one hand, injecting individual services makes it easy to see from the bean definition exactly what services are used without going to the code. On the other hand, if you need another service you need to explicitly inject it. My preference is to simply inject the registry. A second reason to inject the registry is that you’ll always get the right version of the service. Alfresco has two versions of each service. The first is the “raw” service, which has a naming convention that starts with a lower case letter. An example is nodeService. These services aren’t recommended for extensions. Instead, Alfresco provides an AoP proxy that follows a naming convention that starts with an upper case letter, such as NodeService. This is the service that is recommended and is the one that will be returned by the service registry.
Modify core Alfresco classes, web scripts, or Spring beans
Directly access the Alfresco / Activiti database from other applications
Alfresco and Activiti both have an underlying database. In general, it is not a best practice to access this database directly. Doing so can exhaust connection pools on the DB side or cause unexpected locking behavior. This typically manifests as performance problems but other types of issues are possible, especially if you are modifying the data. If you need to update things in Alfresco or Activiti, do so through the APIs.
Perform operations that will create extremely large transactions
When Alfresco is building its index, it pulls transaction from the API to determine what has changed, and what needs to be indexed. This works well in almost all cases. The one case where it may become an issue is if an extension or import process has created a single transaction which contains an enormous change set. The Alfresco Bulk Filesystem Import Tool breaks down imports into chunks, and each chunk is treated as a transaction. Older Alfresco import / export functionality such as ACP did not do this, so importing a very large ACP file may create a large transaction. When Alfresco attempts to index this transaction, it can take a long time to complete and in some cases it can time out. This is something of an edge case, but if you are writing an extension that may update a large number of nodes, take care to break those updates down into smaller parts.
Code yourself into a corner with extensions that can’t upgrade
Any time you are building an extension for Alfresco or Activiti, pay close attention to how it will be upgraded. Alfresco makes certain commitments to API stability, what will and will not change between versions. Be aware of these things and design with that in mind. If you stick with the public APIs in all of their forms, use the Alfresco SDK and package / deploy your extensions in a supported manner, most of the potential upgrade hurdles will already be dealt with.
Muck around with the exploded WAR file.
This one should go without saying, but it is a bad practice to modify an exploded Java WAR file. Depending on which application server you use and how it is configured, the changes you make in the exploded WAR may be overwritten by a WAR redeployment at the most inopportune time. Instead of modifying the exploded WAR, create a proper extension and deploy that. The SDK makes this quick and easy, and you’ll save yourself a lot of pain down the road.
This list is by no means comprehensive, just a few things that I’ve jotted down over many years of developing Alfresco extensions and helping my peers and customers manage their Alfresco platform. Do you have other best practices? Share them in the comments!