Tuxitecte

dimanche 25 avril 2010

Maven + Alfresco : Jetty, Boostrap and Profil



Hello everyone!

This time I'll show you how you can bootstrap (initialize) data during the installation of our AMP and how we can test it easily.


1. Bootstrap

First of all, there are several ways to create a bootstrap
  • by XML files,
  • programmatically (via a java class).
The advantage of the first approach is its simplicity! Indeed, a bootstrap XML is nothing more than the equivalent of the import / export available in Alfresco Explorer. You know the green arrows on a folder in Details screen ... Anyway... Nodes are exported as XML and then (re) integrate into a (new) Alfresco instance. A typical example is the transition between a test server to a production server. On the DEV server, the development team has created a specific project tree, which must be installed on the PROD server automatically . This must be done during the first installation of our AMP on the PROD server.

The limitation of this approach is that only object creation is possible. You can not delete or change nodes...

The advantage of the second approach is its richness! Indeed, we have access to all Alfresco services plus (possibly) services of our project. We can do whatever you want .. You can reorganize a tree, perform a mass change of nodes or transform some contents ...

The disadvantage : you need to know programming :o/ and know how Alfresco service works.

In following I am going to explore the first approach. I may focus on the second approach in a future post ..

1.1 Boostrap via XML
So first, I'll explain the approach by an XML file.
In our example of bootstrapping, I want to create four spaces: a root space : BASE DOCUMENTAIRE (don't forget I'm a little french) + 3 sub-spaces PROJET 1 PROJET 2 PROJET 3. These spaces have been previously created in my Alfresco TEST instance. Now I want to boostrap my project with this data. In this manner, I can share data with any instance of Alfresco.

1.2 Export
First I export spaces in my Alfresco TEST (via the export action), then I download locally the ACP file generated in order to extract the XML file. My XML file is called spaces.xml (orginal isn't it ...).

For more information on the IMPORT / EXPORT: http://wiki.alfresco.com/wiki/Export_and_Import

1.3 Integration in the project
I will add this file to the new directory /alf-amp-osecm/src/main/config/bootstrap. Currently, this file is orphaned and will not be taken into account. We must declare it in Alfresco (and in Spring of course...).
For this, we will create a new file called bootstrap-context.xml in the directory /alf-amp-osecm/src/main/config/context















/${spaces.company_home.childname}
alfresco/module/fr.opensourceecm.alf-amp-osecm/bootstrap/spaces.xml






To summarize how to understand this file?
Literally, that's what he means:
We create a Spring bean identified by osecm.bootstrapSpaces . It inherits module.baseComponent. This bean is used to import spaces. It applies to the module fr.opensourceecm.alf-amp-osecm (our AMP), since version 0.0.4. Treatment of bean (hence the import) is required only once (so only during the first start). It takes as a parameter "bootstrapViews". This will allow us to create our tree structure as a subspace of {spaces.company_home.childname}

Simple isn't it ? :o)

1.4 Creating the project
Now we have our bootstrap. We just have to test it ! We can make a package of our AMP via the maven command

mvn clean install


In target folder, you have alf-amp-osecm-0.0.4.amp. It's possible to integrate it into your alfresco.war and test it.

Copy/paste the file alf-amp-osecm-0.0.4.amp to the amps directory in your Alfresco installation. Then run the installation script : apply_amps.bat in your root Alfresco installation folder. Follow instructions, wait few seconds and after that you have a new alfresco.war in tomcat/webapps folder.

Now you can run Alfresco and verify the integration of your custom module.

For more information : http://wiki.alfresco.com/wiki/AMP_Files

2. Starting and Testing Alfresco via Maven

If you've followed all of preceding posts on integrating Alfresco + Maven, you realized that you spend a lot of time to incorporate an AMP in Alfresco... Copy / paste is well but is a bit repetitive... The idea to improve the process would execute a maven command to start Alfresco !

How?
Well through the use of new plugins: maven-jetty and war!

Jetty is a lightweight HTTP container (just the same style as Tomcat ...) which will enable us to launch Alfresco. Maven-war allow us to create the war of our application.

Simply, we want to create an exploded alfresco.war in a subdirectory of target folder (with maven-war plugin) and launch it as a web application (with the Jetty server).

Here we go!

2.1 Profile
In fact the majority of the configuration work is done at our project's pom.xml. We will create what is called a PROFILE. A profile is a set of maven action made optional or not by the user during the execution of a command. It can be seen as a conditional statement controlled by the user. In this case, we try to start an Alfresco to verify that bootstrap has worked. We also try to verify if our AMP works.

However, before setting up our profile, we need to create some properties files.


2.2 Jetty-env.xml

Above all, we create jetty-env.xml in /alf-amp-osecm/src/test/properties/local. This file configure connection to the database via JNDI.




jdbc/dataSource


jdbc:mysql://localhost/${alfresco.db.name}
${alfresco.db.username}
${alfresco.db.password}





2.3 Application.properties
if you say new environment inevitably you say new repository configuration. We will create a new file for this called application.properties and we will add it to the directory: /alf-amp-osecm/src/test/properties/local
This file contains a set of key / value which can be used by the pom.xml and by dev.properties file.

webapp.name=alfresco-jetty
alfresco.data.jetty=alf_data_jetty
alfresco.data.location=./alf_data_jetty
alfresco.db.driver=org.gjt.mm.mysql.Driver
alfresco.hibernate.dialect=org.hibernate.dialect.MySQLInnoDBDialect
alfresco.db.url=localhost
alfresco.db.name=alfjetty
alfresco.db.username=alfresco33
alfresco.db.password=alfresco
webapp.log.level=error
webapp.log.dir=
module.log.level=debug

2.4 Dev.properties
Here we will create a file called dev.properties and we'll add it to the directory: /alf-amp-osecm/src/test/properties/local. This file create the link between variables defined in application.properties and dev-context.xml. When creating our war, this file will overwrite our dev.properties previously defined.

dir.root=${alfresco.data.location}
index.recovery.mode=AUTO
integrity.failOnError=true
db.test.name=${alfresco.db.name}
db.username=${alfresco.db.username}
db.password=${alfresco.db.password}
db.host=${alfresco.db.host}
db.port=${alfresco.db.port}
db.driver=${alfresco.db.driver}
db.url=jdbc:mysql://${db.test.host}:${db.test.port}/${db.test.name}
hibernate.dialect=${alfresco.hibernate.dialect}


2.5 properties
Now we can attack the configuration of our pom.xml. First we will declare two property : env and webapp.name. Those properties are defined after project declaration block and before the dependencies block .


local
alfresco-jetty


2.6 Create Profile
As the title indicates, we will now create a block profile called webapp. Its main default goal is jetty: run-exploded (ie launch exploded war as a webapp application into jetty). This block is to add at the end of our pom.xml but before the project closing tag.



webapp


src/test/properties/${env}/application.properties

jetty:run-exploded


... Following points...




true
src/test/resources

alfresco/desktop/*.*



true
src/test/properties/${env}
alfresco/extension

dev.properties






org.alfresco.sdk
alfresco-community-war
3.3
war






Note several points:
First we added FILTER via the file application.properties. It will allow us to use all the variables defined in this file in the rest of the pom.xml and more specifically in our profile.

Then we addedalfresco-community-war (ie the application Alfresco Explorer) as a dependency. Of course, we have previously added to our Maven repository local via a maven command :


call mvn install:install-file -Dfile=alfresco.war -DgroupId=org.alfresco.sdk -DartifactId=alfresco-community-war -Dversion=3.3 -Dpackaging=war


After that we added a testResource. It allow us
  • to ignore desktops actions into our AMP (As reminder desktop actions are simply necessary for unit testing in Eclipse)
  • to declare repository configuration defined by dev.properties.


2.6 Configure Maven-War plugin
This plugin will allow us to deploy the alfresco war and to add our configuration files.


org.apache.maven.plugins
maven-war-plugin
2.0.2


it
package

exploded


true




false
${project.build.directory}/${webapp.name}

false

licenses/**


${project.build.testOutputDirectory}
WEB-INF/classes
true

**



src/test/properties/${env}
WEB-INF
true

jetty*







We note in resources block that we
  • Add all configuration files in src/test/resource/alfresco/* (equivalent to ${project.build.testOutputDirectory}

  • Add jetty-env.xml for JNDI database setting


2.8 Configure Jetty plugin

This plugin will enable us to launch the alfresco application and to declare sources of our project.


org.mortbay.jetty
maven-jetty-plugin
6.1.22


it
integration-test

run-exploded


/${webapp.name}
${project.build.directory}/${webapp.name}
10


8080
60000







mysql
mysql-connector-java
5.0.3
provided





Don't forget the dependence with mysql!

2.9 Launch application
Now you are ready to launch your application via a simple command

mvn clean integration-test -P webapp


For information, we use a profile by adding the parameter -P followed by the profile name. If you do not want to play the tests, add the parameter -DskipTests = true at the end of the command.

A few minutes later if all goes well, you can open a browser and type the address http://localhost:8080/alfresco-jetty/

You realize then the presence of a space called BASE DOCUMENTAIRE!

Well Done!


3. Extras

Generally, a bootstrap test does not work the first time! If you want to retry again, it would be useful to reset our application (and your repository).

Now you are familiar with profiles and configuration plugin, so I want to share this extra profile : clean-jetty. Its main goal is to erase your database, stores and lucenes indexes.
It's your turn to place it judiciously in the pom.xml and eventually to improve it!



clean-jetty



maven-clean-plugin
2.4

true


target

war/**


**



alf_data_jetty

oouser/**






org.codehaus.mojo
sql-maven-plugin
1.4



mysql
mysql-connector-java
5.0.3



org.gjt.mm.mysql.Driver
jdbc:mysql://localhost/
root
admin
true



drop-db-jetty
pre-clean

execute


true
drop database IF EXISTS alfjetty



create-db-jetty
clean

execute


true
create database alfjetty default character set utf8 collate utf8_bin










Hope you enjoy this post. Rendez vous to the next chapter!

A ++


PS
All sources of alf-amp-osecm can be downloaded at:
http://www.box.net/shared/bpcx8kl7dn


Digg Google Bookmarks reddit Mixx StumbleUpon Technorati Yahoo! Buzz DesignFloat Delicious BlinkList Furl

0 commentaires: on "Maven + Alfresco : Jetty, Boostrap and Profil"