You are on page 1of 14

Getting Started with the Alfresco Maven SDK

Jeff Potts, Metaversant Group
April, 2015

License
Introduction
Important Concepts
Apache Maven
Alfresco Module Package (AMP)
Alfresco Maven SDK
What About the Old Ant­based SDK?
Your First Project
Let's Run It
What Just Happened?
Other Commands for Invoking the Build
Logging
Working With Your Project in an IDE
Understanding the Project Structure
Creating a Project for Share Tier Customizations
Share project dependencies
Target WAR
Try It: Create a Share Project Using the Archetype
Understanding the Share Project Folder Structure
Running an Integration Test with Share
Dependency Management
Other Topics to Explore on Your Own
Where to Find More Information

License
This work is licensed under the Creative Commons Attribution­ShareAlike 3.0 Unported License. To view a copy
of this license, visit http://creativecommons.org/licenses/by­sa/3.0/ or send a letter to Creative Commons, 444
Castro Street, Suite 900, Mountain View, California, 94041, USA.

Introduction
This tutorial is for people who have been handed a project that requires you to customize Alfresco in some way
and you're thinking, "Now what?". By the end, you'll know:
How to create a new Alfresco project using the Alfresco Maven SDK
What goes where depending on the type of customization you are doing
How to create and run tests
How to produce an artifact suitable for deploying to your environment or sharing with the community.

 Maven can then retrieve and cache those dependencies for you. behaviors. Alfresco. so in that case you will create two AMPs. But if you intend to write code that runs within either of those web applications. or web scripts. The sample projects used Ant­ based builds. I'm going to take you through the most direct. advanced workflows. you'll have to use the old Ant­ based SDK for versions older than 4. JavaDocs. It requires Alfresco 5. There was nothing wrong with this approach. Apache Maven Apache Maven is essentially a build management tool. Before we jump in. Later. but the primary time­saving feature is its ability to understand the dependencies your project relies on (and the dependencies of those dependencies and so on). If you've ever spent time chasing down JAR file after JAR file. What About the Old Ant­based SDK? Alfresco has provided a downloadable SDK since the early­days. if you decide you want to change things up or explore other paths. The SDK consisted of a ZIP that contained compile­time dependencies. that's great. the value of such a tool will be immediately obvious. If you are using a version older than 4.0.1. Important Concepts You don't need to know much about Maven. a quick disclaimer: There are almost always multiple routes to a given solution.This tutorial should be considered a pre­requisite before moving on to more detailed tutorials on things like content modeling. ready­to­run project the next. Alfresco Maven SDK Today's developers are used to rails­like frameworks where you have an empty directory one moment and a fully instantiated. If your project is about making customizations to the Share tier (the /share web application) you will create a "share" AMP. AMP files are used to make it easy to share and deploy customizations to the Alfresco platform. A quick word about versions. If you are using Alfresco 4. the Ant­based SDK failed to evolve with . Why should Alfresco developers settle for anything less? With the Alfresco Maven SDK you don't have to. but as the platform evolved. custom actions. It is quite common for a project to require changes in both tiers. It has many features. The goal of the Maven­based SDK is to make it extremely easy for you to get started with Alfresco development. and sample Eclipse projects. so let me take you through those three concepts quickly. or why this SDK exists before jumping in but it kind of helps set the scene. If you are writing your own custom application that is separate from the Alfresco and Share WARs you don't need the Alfresco Maven SDK. source code.x you must use an older version of this tutorial which covers Alfresco Maven SDK 1.0. the Alfresco Maven SDK is where you need to start. Alfresco Module Package (AMP) An AMP is a ZIP file with a folder structure that follows a specific convention.x). safest route that will get you up­and­going quickly. If your project is about making customizations to the repository tier (the /alfresco web application) you will create a "repo" AMP. This tutorial assumes you are using Alfresco Maven SDK 2. In this tutorial. It consists of a project template (an "archetype" in Maven parlance) and some built­in smarts that make Maven understand how to create AMPs and deploy them to Alfresco.x you should upgrade already! (But seriously.

it. You should also append the string "­repo" to your artifactId because this module is intended to be deployed to the repository tier. Specify what makes sense in your case and hit enter. Maven will do some work and eventually ask you to choose an "archetype". There are three available: 1. alfresco­amp­archetype 3. Today. 6. 4. My examples always assume I am working at a fictitious company called SomeCo. and advanced workflows using Activiti.1 which is the 7th option in the list. alfresco­allinone­archetype 2. a new set of web scripts.1. We're going to be creating some additional directories in here shortly. Aside from its out­of­date examples. so I will specify "com. for example. Now let's create a new project. Currently. Create an empty directory. At this point Maven will show you the values you entered plus some others that were defaulted and ask you to confirm your choices. you don't even have to download anything yourself­­you just create your project and start coding. Next is the artifactId. You should be thinking "Java package". With the Alfresco Maven SDK. 7. It will also be the ID of your AMP so make it something unique. the latest version is 2.someco" here. For now. It's time to see them in action. Type 2 and hit enter. Before I start I'm going to assume you have JDK 1. It doesn't really matter. 1. I'll refer to it as $TUTORIAL_HOME. Web Scripts. It doesn't matter where it is or what you call it. Now you have a high­level understanding of Apache Maven. You don't need to download anything else. If you want to change something you can specify "N" and then make changes or you can . Seriously.alfresco: 3. the old Ant­based SDK required developers to do too much work. so type 7 and hit enter. and the Alfresco Maven SDK. change directories to $TUTORIAL_HOME. Now Maven is asking you to specify the version of the archetype you want to base your project on.8 installed as well as Apache Maven 3. 5. it contains examples for parts of the product that have fallen out­of­favor (the native Web Services API. Maven now asks for a groupId. 2. To create the new project. share­amp­archetype Our goal is to create an AMP that can be deployed to Alfresco so the second one is the one we want. AMPs. some custom rule actions. Your First Project Let me show you how easy it can be to get started with Alfresco development using the Alfresco Maven SDK. then run this command: mvn archetype:generate ‐Dfilter=org. let's assume you want to create something that you will deploy to the Alfresco repository tier such as a custom content model. I'm going to specify "someco­mvn­tutorial­repo" for mine followed by enter. or some Activiti business processes. Not even Alfresco. You can think of this as what you want your project to be called. or the Alfresco Explorer user interface) and lacks examples for hugely important pieces of the product such as CMIS. You're basically selecting from a library of template projects.

0.d this would be the Alfresco Explorer login page. Try this: cd someco‐mvn‐tutorial‐repo  mvn integration‐test ‐Pamp‐to‐war If you watch the output.ModuleServiceImpl] [localhost‐startStop‐1] Found 1 module(s). If you want to verify that you can log in.xml and change it before you proceed.module.AbstractProtocol start INFO: Starting ProtocolHandler ["http‐bio‐8080"] You should be able to go to: http://localhost:8080/alfresco And you will see the "Welcome to Alfresco' page. All you've done is tell Maven to create a project based on a template.d" as the Alfresco version. Let's Run It You haven't downloaded anything.apache. creating an AMP. go to the Alfresco web script console. Log in using "admin" and "admin".339  INFO  [repo.0.enter "Y" to continue. I can always change these values later if needed. and starting the server up. deploying the AMP to the Alfresco WAR. Now Maven is going to do some work. Eventually you'll see: 2014‐01‐15 18:01:19. which is: http://localhost:8080/alfresco/s/index .ModuleServiceImpl] [localhost‐startStop‐1] Installing module 'someco‐mvn‐tutorial‐repo' version Which means that the module your project generated was recognized by the Alfresco server. When it is done you will have: A project structure organized exactly how it needs to be to support your Alfresco development Default configuration files Minimal Java code and an accompanying unit test just to verify that everything works Configuration required to run a local instance of Alfresco suitable for testing A default POM (Project Object Model) XML file that tells Maven what your project depends on The SDK defaults to "5. If you need to run on a different version. You haven't edited anything.  2014‐01‐15 18:01:19.module.480  INFO  [repo. you might want to edit someco­mvn­tutorial­repo/pom. In versions prior to 5. deploying the Alfresco WAR to the embedded Tomcat server.coyote. Once you see: Jan 16. so I'm going to specify "Y" followed by enter. But the cool thing is this: Your project is runnable right now. you'll see that Maven is downloading everything it needs to compile the project. 2014 8:38:20 AM org.

 Maven will automatically run the unit tests in your project. you can run: mvn package If you want to install the AMP into your local Maven repository you can run: mvn install You may have noticed that the default project includes a simple unit test. You can see this happening in the output: ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐   T E S T S  ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐  Running org. If you go look in the target directory you'll see the AMP that was produced and subsequently deployed to the Alfresco WAR. If you just want to build the project. go back to the window where you ran your Maven command and type ctrl­c to shutdown the server. run the unit tests. I have mine set to: ‐Xmx1024M ‐XX:MaxPermSize=512m With MAVEN_OPTS set you should not see any out­of­memory errors.alfresco. Many organizations run CI (Continuous Integration) tools that depend on this being the case.amp". For example. Other Commands for Invoking the Build You may not always need to start up the Alfresco server and leave it running. One way to do that is by setting the MAVEN_OPTS environment variable. deployed as an AMP to a fresh Alfresco WAR. This causes the project to be built.test.When you are done poking around. and run on the embedded Tomcat server.DemoComponentTest It's a good practice to make sure that your project always includes unit tests and to run them every time you build. If you get an out­of­memory error when you run the integration test. Once it started up. If you don't want to run tests for some reason you can skip them. By default. What Just Happened? You asked maven to run the "integration­test" goal using the "amp­to­war" profile. you may need to pass some JVM memory parameters to Maven. and package the AMP. This file is what you would give to your IT team if you were ready to deploy your repository tier changes to a real Alfresco server. In my case it is called "someco­mvn­tutorial­repo. you were able to log in to the old Alfresco Explorer client and work with the repository to test your module. like this: mvn install ‐DskipTests=true .demoamp.

level=DEBUG Or you can edit the pom.level> If you change the pom. Select File. . and subsequently. To open the project we created earlier in Eclipse. It comes with built­in Maven support. you'll learn about working with your new project in an IDE and you'll get a tour of the default project structure. then the AMP that gets produced will include that setting.xml.logger. Working With Your Project in an IDE Althought it isn't required. like this: <module.level} You'll probably want to replace that with settings that match your package structure. Any IDE will do. Alfresco content store.level you can either do it when you run Maven. it's probably best to set it using the command­line so it doesn't accidentally get set in your AMP.DemoComponent=${module.alfresco.If you want to delete all of the compiled artifacts that Maven created and start fresh you can run: mvn clean If you also want to delete the embedded database.properties file that exists in the module directory.log.log. If you aren't sure.log. Import. Logging In the log4j.demoamp. I'll be using the Luna version of Eclipse Java EE IDE for Web Developers. Click Next. Existing Maven Projects.log. do this: 1. Maven. Next up. This may or may not be what you want. To set the module. the WAR the AMP gets deployed to will write log statements accordingly. but the most popular one is Eclipse so let's see how that works.org. like this: mvn install ‐Dmodule.properties file includes log4j. the log4j. indexes.xml and add it to the properties. most people prefer to work in an IDE when developing Alfresco customizations.log. and log files that were created by running the test Alfresco server.level>DEBUG</module. you can run: mvn clean ‐Ppurge Now you know how to create a new Alfresco project from an archetype and the fundamentals of running builds with and without unit tests.

Understanding the Project Structure . the project is imported into your Eclipse workspace. After clicking Finish. then click Next. Make sure the checkbox next to the project name is checked.G itH ub n  e  o rk  m Fo 2. Specify the directory that contains the someco­mvn­tutorial­repo folder. Eclipse will inspect that folder and show your project in the projects list.

 let's take a look at the Share tier. those don't reside under the module directory. Java­based controllers for web scripts go here.2. src/test Everything under src/test is about running unit tests. and user interface configuration.properties file tells Alfresco what it needs to know about this AMP such as its ID. there are tutorials available here. You will want to configure your source code control client to ignore the target directory and the alf_data_dev directory. For example. Those go in src/main/amp/web in directories such as css. As part of that I'll show you another option for creating projects without leaving Eclipse. This tells Maven everything it needs to know about your project. pom. From an Alfresco Maven SDK perspective. These files will ultimately be placed in a JAR. This will cause the demo component and its associated test class to fail to . Now that you understand how to create a project for repository tier customizations. For now. In fact. content model XML files. Things like custom action executer classes. Let's see what we've got. Your module may include client­side resources that need to be deployed to the root of the web application. Any resources those classes need go in src/test/resources. If you wanted to work with a different version. don't worry. the minimum and maximum version of Alfresco required to run the AMP. src/main/amp Everything else goes somewhere in this part of the project. many Share projects don't use any Java at all. I prefer separate sub­directories for each of these things. jsp.xml and remove the alfresco­repository dependency. Instead. Let me just point out the highlights: The module. If you don't know what those are. edit the pom. You should check this entire project into source code control. As you'll see in later tutorials. scripts. version. version 1. Share project dependencies We'll talk more about dependency management in a minute. The unit tests themselves go in src/test/java. there are two things different about a Share project: The project's dependencies and the WAR the AMP will be deployed to.The folder structure of your project is a bit more pleasant to explore in your IDE. the archetype configures the project's pom. Fo src/main/java This is where you should create your own packages to organize your Java code.properties file. Creating a Project for Share Tier Customizations The first thing you should realize is that the structure for a project that creates repo tier customizations is exactly the same as one that targets Share tier customizations. In src/test/properties/local you'll see an alfresco­ global. those would go under config/alfresco/extension/templates/webscripts and config/alfresco/extension/workflows. the JAR will be placed under WEB­INF/lib. In this case. Remember those settings you specified when you created the project from the archetype? You can make changes to those settings here. and images.1. Share projects have no such dependency. When the AMP is installed into the Alfresco WAR.xml In the root of the project directory you'll see pom. If your module includes web scripts or workflows. it is only used when running the embedded Alfresco server for testing purposes. The structure of an AMP is well­ documented so I don't want to duplicate that here.xml to have a dependency on the alfresco­repository artifact. If you are already know something about Alfresco you know that this is used to configure Alfresco.1 of the archetype assumes you are G itH ub working with Alfresco Community Edition 4.xml. you would rk  m e  o n  simply change those properties and then tell Maven to update and it will take care of the rest. and any other AMPs on which this one depends.e. For now realize that. The config/alfresco/module/someco­mvn­tutorial­repo directory is the heart of the AMP. by default. custom behaviors. This is where you place Spring config XML files.

 You could go into the command line and run the exact same archetype command you ran earlier.xml. Target WAR The other thing that is different about a Share project is the WAR the AMP will be deployed to.client. For Share projects it should be set to "share".compile. If you are not using Eclipse. By default it is set to "alfresco". 3.war property in rk  m Fo Try It: Create a Share Project Using the Archetype e  o n  G itH ub pom. 1. New Maven Project. then click next. selecting the "share­amp­archetype" and specifying a new artifactId. Let's create a new project for Share customizations. They can be deleted. Let's do that. Click Configure so we can add Alfresco's catalog to the list. This is configured in the alfresco. 2. go ahead and do that now. Specify the directory that contains the repo project directory. then skip the next section. Another option is to configure Eclipse so you can create new Alfresco projects using the Alfresco Maven SDK without leaving the IDE. Instead of the alfresco WAR it needs to be deployed to the share WAR. . File.

xml" as the Catalog File. click OK and OK again to close the Preferences panel.maven.G itH ub n  e  o rk  m Fo 4. 8.maven. Specify "http://repo. Click Add Remote Catalog 5. Specify "Alfresco Archetypes" as the description.archetype" in the filter and you'll see the same three archetypes that were presented to you as options on the command line at the start of the tutorial. Select the share­amp­archetype and click Next. 6.alfresco. 7. . Now select "Alfresco Archetypes" in the catalog and you'll see a bunch of archetypes show up in the list. Specify "org. Then.org/maven2/archetype­catalog.apache.

 The next time you create a new project using the archetype.someco" for the groupId and "someco­mvn­tutorial­share" as the artifactId.d". I changed my alfresco_target_version from "5.G itH ub n  e  o rk  m Fo 9. The only difference worth mentioning is that in the repo project. Understanding the Share Project Folder Structure As I mentioned earlier. Then click Finish. Similar to the command line step. the structure of this project is exactly the same as the one we created for our repo project. those go in . In a Share project. things like web scripts went into src/main/amp/config/alfresco/extension/templates/webscripts. Now your Share customization project is in your workspace. it will be a few less steps because you won't have to add the catalog. Specify "com.0.0.c" to "5.

 the Alfresco Maven SDK will create the base dependencies for your project. Web scripts can run in either the repository tier or the share tier. But what if I wanted to put some Alfresco Java in my Share project. All you need to do is tell Maven about them by configuring your pom. Your Share rk  m mvn integration‐test ‐Pamp‐to‐war Fo cd someco‐mvn‐tutorial‐repo  e  o n  G itH ub tier needs an Alfresco repository to talk to. As I mentioned earlier. Dependency Management The cool thing about Apache Maven is that it manages your projects dependencies for you. like maybe a Java­based web script? In that case. By default. we'll need to adjust the dependencies. you can go to http://localhost:8081/share and log in to test your module. for example. Running an Integration Test with Share Often you will work on both repo tier customizations and share tier customizations at the same time. If you write a Java­based web script in your repository project the class will compile because that project depends on the alfresco­repository artifact which in turn depends on the spring­webscripts artifact. They depend on share and spring­surf­api.port=8081 Once both servers come up.xml file: .xml.tomcat. typically.src/main/amp/config/alfresco/web­extension/site­webscripts. Your repo­tier project depends on alfresco­repository. Alfresco Share projects don't depend on the Alfresco repository. You can see this if you go to the Dependency Hierarchy tab in Eclipse in your pom. so the SDK sets those dependencies up for you. One way to do that is to tell Maven to start your repo project using: And then start your Share project using: cd someco‐mvn‐tutorial‐share  mvn integration‐test ‐Pamp‐to‐war ‐Dmaven.

com. I hope you agree it is really easy to boostrap a project to get started.0. If you are an old hand at Alfresco but are still using the old SDK I hope this has motivated you to switch to the new SDK to produce your AMPs. you can see the hierarchy by running: mvn dependency:list So.alfresco. You can do a search for a class and it will show you all of the artifacts that contain it. You might be wondering how you were supposed to know that the DeclarativeWebScript class was included in the spring­webscripts artifact.d</version>    <scope>provided</scope>  </dependency> Now a Java­based web script will be able to find its parent class. I'll leave you to explore those on your own.G itH ub n  e  o rk  m Fo Depency hierarchy shown in Eclipse Alternatively. DeclarativeWebScript. to add a Java­based web script to our share tier project. we'd need to add spring­webscripts as a dependency.xml. You can do this by editing the pom. Here are a few: The Alfresco Maven SDK supports dynamic class reloading when used in conjunction with a tool called JRebel. If you are new to Alfresco development. One way to find out is to go to http://artifacts.extensions.springframework. like this: <dependency>    <groupId>org. There are many topics that weren't covered in this tutorial.surf</groupId>    <artifactId>spring‐webscripts</artifactId>    <version>5. Other Topics to Explore on Your Own You now know how to use the Alfresco Maven SDK to create projects for both your Alfresco repository customizations and your Alfresco Share customizations. .

 But the Alfresco Maven SDK includes another archetype called All­ in­One. rk  m e  o n  Where to Find More Information Gab's Alfresco Summit presentation on Test­Driven. Fo The official documentation on the Alfresco Maven SDK is on http://docs. actions. Gethin James' Getting Started with Alfresco Development presentation from Alfresco Summit The Alfresco Developer Series on ECM Architect has free tutorials on custom content models. . contact Alfresco Support. That archetype gives you a complete Alfresco installation including SOLR. ECM Architect Creative Commons License This work is licensed under a Creative Commons Attribution­ShareAlike 3.com. workflows. Rapid Development.0 Unported License. and web scripts. If you need help accessing G itH ub the Enterprise Edition artifacts. and Continuous Delivery of Alfresco Solutions The Instant Apache Maven Starter book by Maurizio Turatti and Maurizio Pillitu might be a good resource if you are interested in learning more about Apache Maven.See Gab's Alfresco Summit 2013 presentation linked to in the More Information section. This tutorial covered the AMP archetype. behaviors. The Alfresco Maven SDK supports both Community Edition and Enterprise Edition.alfresco.