in Alfresco

Maven Alfresco SDK – tutorial #1

Alfresco comes packed with features but usually it is required to add some of your own flavors, features, extensions, webscripts, services, actions and so on. Best way to do that is to create a alfresco module and deploy it to alfresco. Creating alfresco module is the easy part, just add a few files, folders and we are set, problem becomes when it is required to have jUnit tests, auto builds,deploys and so on.

Purpose of this tutorial is to explain how to use Maven Alfresco SDK, package, deploy, run your jUnit tests and how to extend alfresco 4.2 without going into alfresco module details.

First is first we need to match the Maven Alfresco SDKs pre-requisites.

  • Download Maven 3.0.3+ version from maven.apache.org and install it using this instuction
  • Add MAVEN_OPTS=”-Xms256m -Xmx1G -XX:PermSize=500m” ( I could not run jUnit with PermSize=300m ).
  • Check for java version 1.7 typing  java -version in  your console
  • I prefer eclipse you can feel free to use what you like the most

Lets create maven project where we will develop our module , using AMP archetype from maven alfresco sdk.

  • Open your console create workspace folder and go into it
  • In your console type
    mvn archetype:generate -DarchetypeCatalog=https://artifacts.alfresco.com/nexus/content/groups/public/archetype-catalog.xml -Dfilter=org.alfresco.maven.archetype:
  • Choose the archetype will appear after few of INFO lines, you can select between alfresco-amp-archetype and alfresco-allinone-archetype and  typing one (1) will select alfresco-amp-archetype.
  • Choose org.alfresco.maven.archetype:alfresco-amp-archetype version will appear giving you possibility to choose between several versions from 1.0 to 1.1.1, we will select 1.1.1 version entering number 5 which is default value.
  • Define value for property ‘groupId’ : com.alfrescoblog
  • Define value for property ‘artifactId’: alfrescoblogAMPArch, this will define project name
  • After confirming(with ‘Y’ ) you will see the message stating that project will be created and that you can import it into your eclipse project

Yeeey we have a project finished , lets dig into it and see what it there :), next listing we have a list of folders in our project and what is there.

 pom.xml
  src/main/amp  
            |-> module.propertie
            |-> config/
            |-> web/
            |-> licenses/
  src/main/java //Java classes to be packaged in the AMP embedded JAR)
  src/main/resources //resources to the packaged in the AMP embedded JAR)
  src/test/java // Unit tests
  src/test/resources // Unit test resources
  src/test/properties/<env> //  Environment aware alfresco-global.properties. By default <env>=local

After importing this project into eclipse workspace let take a look at it in more detail.

Lets open  the pom.xml and see that it contains parent :
<parent>
<groupId>org.alfresco.maven</groupId>
<artifactId>alfresco-sdk-parent</artifactId>
<version>1.1.1</version>
</parent>

Additionally contains properties where things like alfresco.client.war.version is specified, alfresco.client.war and so on…

<properties>
<alfresco.version>4.2.e</alfresco.version> <!--Alfresco version to compile against-->
<app.log.root.level>WARN</app.log.root.level>
<alfresco.client.war>alfresco</alfresco.client.war><!--defines target war-->
<alfresco.client.war.version>4.2.e</alfresco.client.war.version>
<!--defines target war version -->
</properties>

We will notice that this amp will be installed to alfresco.war , setting the alfresco.client.war to share would change this behavior.

Every alfresco module must have module.properties file where module id, title description and version are defined, content of this module is listed bellow. We can notice that module.id depends of pom.xml values and values that we have specified on project creation explained before.

module.id=${project.artifactId} #unique identifier for this module
#module.aliases=myModule-123, my-module #if module.id gets renames old value can be set here
module.title=${project.name}
module.description=${project.description}
module.version=${noSnapshotVersion}

module-context.xml , this file represents root Spring configuration, it must be placed in alfresco.module.<moduleId> and to be named module-context.xml . When module-context.xml file contains too many beans it is smart to split it into several smaller ones. Going into src/main/amp/config/alfresco/module/alfrescoblogAMPArch we will find module-context.xml. Contents of this file are listed bellow.
<beans>
<!-- This is filtered by Maven at build time, so that module name is single sourced. -->
<import resource="classpath:alfresco/module/${project.artifactId}/context/service-context.xml" />
</beans>

We have an import of file service-context.xml where rest of our spring configuration is located. In service-context.xml we have defined 2 Spring beans changeme.exampleBean with class org.alfresco.demoamp.Demo that has init method called init and changeme.exampleComponent with class …DemoComponent. This is the file where we would add our Spring  beans.

How to build amp file and deploy it to the server ?

Deploying to the server is fairly easy, by opening the console and after going to the eclipse project folder enter command.

mvn package or mvn install

This command will create our amp file in target folder of your project, in this case file will be named alfrescoblogAMPArch.amp ( name of our project + .amp ). iF you are running this for the first time it can take a while as it needs to download required jars.

To install amp to alfresco copy it to Alfresco\amps , and run Alfresco\bin\apply_amps.bat if you are running on windows, in case that you are running on linux or you have some custom installation you can always install alfresco module using next command :

java -jar alfresco-mmt.jar install example-amp.amp alfresco.war

Integration Test

Before you deploy this module to your server you should test to see if all is configured correctly. Running next command will start tomcat on port 8081 with your module installed.

mvn integration-test -Pamp-to-war -Dmaven.tomcat.port=8081

jUnit Tests

Previously we mentioned component called DemoComponent, let find the class in the src/main/java/org.alfresco.demoamp.DemoComponent and letts look what it does :

  1. GetsTheCompanyHome folder
  2. Counts the children of folder that is passed to method

It is very important to create jUnit tests so deploy that does not pass tests would not get deployed. So where do we write tests ? Test has been created already and it is located in src/test/java/org.alfresco.demoampTest.java . There we have three tests in total , one of them is:

@Test
public void testChildNodesCount() {
//sets authentification to admin user name

AuthenticationUtil.setFullyAuthenticatedUser(ADMIN_USER_NAME); 

//gets the company home nodeRef
NodeRef companyHome = demoComponent.getCompanyHome();

//counts the number of children
int childNodeCount = demoComponent.childNodesCount(companyHome);
assertNotNull(childNodeCount);
// There are 7 folders by default under Company Home
assertEquals(7, childNodeCount);
}

Tests are automatically executed before every packaging and it should never be otherwise, although it can .

Adding web-client-config-custom.xml to module .

Lets create a folder extension in src/main/amp/config/alfresco/ and create xml file called web-client-config-custom.xml. Here we can add custom settings . Alfresco by default does not allow search query to have less then 3 characters, we are going to change that to one . Contents of this xml file will be :

<alfresco-config>
<config>
<client>
<!-- the minimum number of characters required for a valid search string -->
<search-minimum>1</search-minimum>
</client>
</config>
</alfresco-config>

 

Extending the alfresco REST with webscripts

It is common to have a need for extending the alfresco REST, this time we will create one webscript and place it inside of this module. Frist let create a folder in src/main/amp/ with path config/alfresco/extension/templates/webscripts. Webscript can have number of files, for our example we are going to have one xml, one js and one ftl file, for setting the url of the wescript, setting the message in the webscript model and showing the message respectively .

Contents of file example.get.desc.xml

<webscript>
<shortname>Alfresco Blog Example Webscript</shortname>
<description>Alfresco Blog Example Webscript</description>
<url>/alfrescoblog/example</url>
<authentication>user</authentication>
<format default="json">extension</format>
</webscript>

Contents of file example.get.js

function main()
{
model.message = "Alfresco Blog ";
}
main();

Contents of file example.get.json.ftl

${message}

This script will be visible  http://localhost:8080/alfresco/service/alfrescoblog/example

This concludes first part of this tutorial, second part is here.

 

Don't be shellfish...Tweet about this on TwitterShare on LinkedInShare on Google+Share on RedditShare on Facebook