Introduction

This tutorial was created for those people who need to, in some way, configure Alfresco on a project. And so at first you think, “What is this?!” But in the end you will learn:

• How to create an Alfresco project from scratch using Alfresco Maven SDK
• What should happen depending on your settings
• How to create and run a test
• How to create an artifact suitable for embedding or sharing with the community

This tutorial should be considered a starting point before you move on to more detailed learning about things like content modeling, customizing actions and behavior, additional workflows, or web scripts.

Before we begin, a short digression: There are almost always many alternative paths to a solution. In this tutorial I will take you in the most simple and direct way, a safe route that will help you figure it out faster. Later you can change some things or explore other routes if you want.

Basic concepts.

You don't need to know too much about Maven, Alfresco, or why this SDK is needed before you start using it, but some knowledge can help in some ways, so let me quickly walk you through the basic concepts.

Apache Maven

Apache Maven is a build management tool. It has many features, but the main one is that it saves time in figuring out which dependencies (and dependencies of dependencies) your project relies on. Maven can retrieve and cache these dependencies for you. If you've ever spent time trying to figure out which JAR file comes after which JAR file, then the usefulness of such a tool is obvious.

Alfresco Modular Packages(AMP)

AMP is a ZIP file with a directory structure following certain conventions. AMP files are used to easily share and deploy settings on the Alfresco platform. If your project needs to create custom settings at the repo level (web app/alfresco) then you create an AMP "repo". If your project needs to create settings at the Share level (web app /share) you create a "share" AMP. It's quite typical for a project that when changes are required at both levels, you create two AMPs.

Alfresco Maven SDK

Today's programmers are accustomed to powerful frameworks in which an empty directory becomes completely filled with files in a minute and the next moment your project is ready to launch. Why should Alfresco developers settle for less?

The goal of the Maven-based SDK is to create the simplest possible conditions for starting development for Alfresco. The SDK consists of a project template (an "archetype" in Maven terminology) and some built-in features that tell Maven how to create AMPs and deploy them to Alfresco.

If you write your own application separately from Alfresco and Share WARs, then you do not need the Alfresco Maven SDK. But if you're going to write code that runs in any of these web applications, the Alfresco Maven SDK is the place to start.

What about the old Ant-based SDK?

Alfresco has provided this downloadable SDK since the beginning. The SDK contained a ZIP container with the necessary dependencies for compilation, source code, documentation, and example Eclipse projects. These examples used an Ant-based builder.

There was nothing wrong with this approach, but development platforms have evolved, and Ant's SDKs have failed to evolve with them. As of today, parts of these examples are outdated (native Web services APIs, for example, or the Alfresco Explorer user interface) and there are not enough examples for extremely important parts such as CMIS, Web scripts, and advanced workflows using Activiti.

In addition to its outdated examples, the old Ant SDK is required. Developers are doing too much work. With Alfresco Maven SDK, you don't even have to download anything - you just create your project and start coding.

You now have a high level of understanding of Apache Maven, AMP, and the Alfresco Maven SDK. It's time to see it all in action

Your First Project

Let me show you how easy it is to start developing for Alfresco using the Alfresco Maven SDK. Before we begin, I must remind you to have JDK 1.7 installed, as well as Apache Maven 3 installed. You do not need to download anything else. Seriously. Even Alfresco.

1. Create an empty directory. We'll be creating some additional directories in it soon.
2. Now let's create an empty project. Let's say you want to create something that you will deploy to the Alfresco repository, for example a custom content model, several custom rule actions, a new set of web scripts, or some Activiti business processes. It really doesn't matter. To create a new project, run the command:

   mvn archetype:generate\
   -DarchetypeCatalog=https://artifacts.alfresco.com/nexus/content/groups/public/archetype-catalog.xml\
   -Dfilter=org.alfresco.maven.archetype:

3. Maven will do some work and eventually ask you to select "archetype". Your basic selection from project template libraries. There are two available here. One is called "alfresco-amp-archetype" and the other "alfresco-allinone-archetype". Our goal is to create an AMP that can be deployed in Alfresco, so the first point is what we need. Type 1 and press Enter.
4. Maven now asks you for a specific version of the template that you are going to base your project on. Currently, the latest version is 1.1.1 which is the fifth option on the list so press 5 and Enter.
5. Maven asks about groupId. It's similar to "Java package". My examples are always based on the fact that I work at a fictitious company called SomeCo, so I'll enter "com.someco" here. Type something that makes sense to you and press Enter.
6. Next is the artifactId. Think of it as the name of your project. This will also become your AMP ID so choose something special. You should also add the line "-repo" to your artifactId because this module will be built into the repository. I'll name mine "someco-mvn-tutorial-repo" and press Enter.

7. At this point, Maven will show you the values ​​you entered, add some other defaults, and ask you to confirm your selection. If you want to change anything, you can select "N" and then make changes or "Y" to continue. You can always change these values ​​later if necessary. Press "Y" and then Enter.

Maven will now do some work. When it finishes you will get the following:

• A project that is structured to support your Alfresco development
• Default configuration files
• Minimal Java code for additional unit tests to check that everything works
• Configuration required to run the local Alfresco instance required for testing
• Default POM (Project Object Model) XML file that tells Maven what dependencies your project has

Let's run it

You haven't uploaded anything yet. You haven't edited anything yet. All you did was tell Maven to create a project based on the template, but I have great news: your project is ready to run right now.

Try this:

cd someco-mvn-tutorial-repo
mvn integration-test -Pamp-to-war

If you look at the output, you will see that Maven downloads everything needed to compile the project, create the AMP, deploy the AMP to the Alfresco WAR, deploy the Alfresco WAR to the embedded Tomcat server, and run it. Eventually you will see something similar to:

2014-01-15 18:01:19,339 INFO [repo.module.ModuleServiceImpl] [localhost-startStop-1] Found 1 module(s).
2014-01-15 18:01:19,480 INFO [repo.module.ModuleServiceImpl] [localhost-startStop-1] Installing module 'someco-mvn-tutorial-repo' version 1.0.1401151758.

Which means that your project modules were generated and recognized by the Alfresco server.

After you see:

Jan 16, 2014 8:38:20 AM org.apache.coyote.AbstractProtocol start INFO: Starting ProtocolHandler ["http-bio-8080"]

You should be able to open:

http://localhost:8080/alfresco

And log in using "admin" and "admin".

When you're done admiring it, go back to the window where you ran your Maven command and press ctrl-c to shut down the server.

If you get an out-of-memory error when running an integration test, you may need to enter some JVM parameters for memory options in Maven. One possible solution is to set the MAVEN_OPTS environment variable. For example, I set my values ​​to:

-Xmx1024M -XX:MaxPermSize=512m

Use MAVEN_OPTS to set it enough so that you don't see memory overflow errors.

What was it?

You have asked Maven to run "integration-test" to use the "amp-to-war" profile. This led to building the project, deploying it as AMP to a fresh Alfresco WAR, and running the embedded Tomcat server. After that, you were able to log in to the old Alfresco Explorer client and work with the repository, testing your module.

If you look in the target directory, you will see AMP that was created and subsequently deployed in Alfresco WAR. In my case it is called "someco-mvn-tutorial-repo.amp". This file is what you should give your IT team if you are ready to apply your repository level changes to the live Alfresco server.

Other Build Commands

You may not always need to start the Alfresco server and leave it running. If you just want to build the project, run a unit test, and package AMP, you can do:

mvn package

If you want to install AMP inside your local Maven repository, run:

mvn install

You may have noticed that the project includes a simple unit test by default. By default, Maven will automatically run unit tests in your project. You can see this in the console output:

-------------------------------------------------- -----
 TESTS
-------------------------------------------------- -----
Running org.alfresco.demoamp.test.DemoComponentTest

It's a good practice to make sure your project always includes unit tests and runs them every time you build. Many organizations use CI (Continuous Integration) tools that depend on these tests. If for some reason you do not want to run testing, you can skip it, something like this:

mvn install -DskipTests=true

If you want to remove all the compiled stuff that Maven creates and start over, you can run:

mvn clean

If you also want to delete the built-in database, saved Alfresco content, indexes, and logs that are always created when running server testing, you can run:

mvn clean -Purge

Now you know how to create a new Alfresco project using a template and have the basics of building with or without tests. The next step is to learn how to work with your project in the IDE.

Logging

The log4j.properties file is located in the modules directory, the log4j.properties file includes

log4j.logger.org.alfresco.demoamp.DemoComponent=${module.log.level}

You will probably want to replace this with your own settings that suit your package structure.

To configure module.log.level you can do this when you start Maven, like this:

mvn install -Dmodule.log.level=DEBUG

Or you can edit pom.xml and add this to the properties, something like this:

<module.log.level>DEBUG</module.log.level>

If you change pom.xml, then AMP will receive these settings when created, and subsequently, the WAR into which AMP is deployed will write logs. This may (or may not) be what you want. If you are unsure, it may be better to set the values ​​using the command line as this will prevent you from accidentally messing up the values ​​in your AMP.

ECM Architect