mirror of
https://github.com/Alfresco/alfresco-sdk.git
synced 2026-09-16 18:13:23 +00:00
mindthegab
58d01898bd
git-svn-id: http://maven-alfresco-archetypes.googlecode.com/svn/trunk@625 04253f4f-3451-0410-a141-5562f1e59037
252 lines
11 KiB
Plaintext
252 lines
11 KiB
Plaintext
This document needs updating...
|
|
|
|
**********************************
|
|
Disclaimer for maven-alfresco list
|
|
**********************************
|
|
|
|
This codebase is currently work in progress; the effort have been split in three directions:
|
|
a) The definition of 2 POM files that can handle versions and common build behaviors/features
|
|
b) The writing of an alfresco-maven-plugin to enable amp-to-war overlay provided by Alfresco
|
|
Repository built-in features (ModuleManagementTool) and replace the maven-amp-plugin (big
|
|
rewriting of the maven-war-plugin)
|
|
c) The definition of (initially 2) archetypes that show some simple project's configuration using
|
|
the parent POMs
|
|
|
|
Most of the build features have been successfully ported to a new structure, whose main advantage is
|
|
to keep pom.xml files extremely simple and readable (since a lot of logic have been moved to the parent).
|
|
Inherited behaviours are configurable simply defining specific properties in the project's or module's pom.xml
|
|
(see documentation below).
|
|
|
|
Here follows a list of build features that have not been ported yet:
|
|
- Maven SCM and release
|
|
- JBoss run
|
|
- Tomcat remote deployment
|
|
- Jetty Java source and resources reloading (Jetty currently runs .war files)
|
|
- Maven Site generation
|
|
- Maven reporting
|
|
- Maven distributionManagement
|
|
|
|
Apart from SCM and release, all the mentioned features are probably best suited for a more enterprise archetype,
|
|
using the Alfresco Web Integration POM as parent and adding more build features around Maven, Tomcat and JBoss.
|
|
|
|
******************
|
|
Alfresco Maven SDK
|
|
******************
|
|
|
|
The Maven SDK is an effort that have been developing in the last 5 years - mostly driven by community efforts on
|
|
Google Code (http://code.google.com/p/maven-alfresco-archetypes) - which delivers archetypes for building Alfresco
|
|
integration project with Maven; builds are based on artifacts that are deployed into maven.alfresco.com Repository
|
|
manually as a community effort.
|
|
|
|
The main advantages with the (currently official) Alfresco SDK follows:
|
|
|
|
- IDE-independent SDK, use IntelliJ, eMacs or any other IDE sto write your code
|
|
|
|
- No IDE manual configuration, all build-related features are provided by Apache Maven, which is the only
|
|
prerequisite to use this SDK
|
|
|
|
- Language independent, you don't like Maven? You can still use Ant, Ivy, Buildr, Gradle, Leiningen or any other build
|
|
system that is compatible with Maven artifact resolution mechanism; just configure maven.alfresco.com as (one of) your
|
|
Maven repositories and you're ready to go
|
|
|
|
- Javadoc and Sources support, provided by maven.alfresco.com related Maven artifacts; you don't need to manually
|
|
configure your IDE to attach (manually downloaded) sources to your (manually downloaded) binaries.
|
|
|
|
- Clean and readable, the build logic related with OOTB Alfresco features is wrapped in 50 lines of pom.xml
|
|
|
|
- Advanced build functionality, inherited by your parent POMs you can use embedded databases and j2ee
|
|
containers with (almost) no configuration at all, among other features exposed below.
|
|
|
|
- One mvn command to generate, one mvn command to run, this is all you need to do to have a local Alfresco running
|
|
on an empty laptop
|
|
|
|
- Supports community and enterprise flawlessly, allowing to switch one to another very easily
|
|
|
|
The following documentation aims to provide three different levels of complexity to tackle an Alfresco integration
|
|
project: simple, advanced and custom; the latter exposes in details the Maven Alfresco SDK features.
|
|
|
|
*************
|
|
Prerequisites
|
|
*************
|
|
|
|
The main and only prerequisite to follow reading this document is to have Apache Maven 3.0.3 (or higher) installed
|
|
on your machine; there is no preferred IDE nor web container and database requirements needed.
|
|
|
|
It is strongly advised to use the Apache Maven official binary distributions downloaded from maven.apache.org; avoid
|
|
OS-specific distributions as much as possible.
|
|
|
|
************
|
|
Use - Simple
|
|
************
|
|
|
|
If you're new to Alfresco, you probably want to know which is the impact of introducing such a technology within your
|
|
development team, run it locally, assess all development processes involved with the product and which
|
|
technologies/tools are best suited for those.
|
|
|
|
You can currently choose between two different flavors, depending on your final goal:
|
|
|
|
* If you want to assess efforts involved with AMP development, you can run the following commands:
|
|
|
|
1.
|
|
mvn archetype:generate \
|
|
-DarchetypeGroupId=org.alfresco.maven \
|
|
-DarchetypeArtifactId=quickstart-amp-archetype \
|
|
-DarchetypeVersion=1.0 \
|
|
-DgroupId=com.someco \
|
|
-DartifactId=alfresco-amp-quickstart \
|
|
-Dversion=1.0-SNAPSHOT \
|
|
-DarchetypeRepository=http://maven.alfresco.com/nexus/content/repositories/releases \
|
|
-DinteractiveMode=false
|
|
|
|
You can always switch Alfresco versions/editions by editing the <parent> coordinates of your generated pom.xml
|
|
|
|
2.
|
|
cd alfresco-amp-quickstart && MAVEN_OPTS="-Xms256m -Xmx1G -XX:PermSize=300m" mvn package -Drunamp
|
|
|
|
Browse to http://localhost:8080/amp-quickstart and you will find Alfresco Explorer Client running against a local
|
|
Alfresco Repository sitting on top of an H2 embedded database and loading your AMP package.
|
|
|
|
* If you want to customise Alfresco Explorer and/or Share clients, embed AMP packages/projects or simply run both
|
|
Alfresco Explorer and Share on the same machine, run the following commands:
|
|
|
|
1.
|
|
mvn archetype:generate \
|
|
-DarchetypeGroupId=org.alfresco.maven \
|
|
-DarchetypeArtifactId=quickstart-allinone-archetype \
|
|
-DarchetypeVersion=1.0 \
|
|
-DgroupId=com.someco \
|
|
-DartifactId=alfresco-allinone-quickstart \
|
|
-Dversion=1.0-SNAPSHOT \
|
|
-Dedition=community \
|
|
-DarchetypeRepository=http://maven.alfresco.com/nexus/content/repositories/releases \
|
|
-DinteractiveMode=false
|
|
|
|
2.
|
|
cd alfresco-allinone-quickstart && MAVEN_OPTS="-Xms256m -Xmx1G -XX:PermSize=300m" mvn package -Drun
|
|
|
|
Compared with the previous flavor, alfresco-allinone-quickstart is a Maven multi-module project, which also includes
|
|
an AMP project that gets 'overlaid' into both Alfresco and Share web applications.
|
|
Alfresco Explorer is available at http://localhost:8080/alfresco whereas Alfresco Share is available at
|
|
http://localhost:8080/share
|
|
|
|
************
|
|
Use - Custom
|
|
************
|
|
|
|
When the build logic becomes tough, integrating with third party technologies, introducing complex build scenarios,
|
|
you might want to have a lower integration level with Alfresco SDK; there are basically 2 big integration points
|
|
you can rely on, which are basically Alfresco-maintained POM files that provide:
|
|
|
|
- A list of Alfresco artifacts, including binaries, javadoc and sources, Maven plugins successfully tested against
|
|
the standard and supported build process; artifacts come with correct platform versions and editions
|
|
(community vs enterprise) according with the <groupId> and <version> tags parent coordinates.
|
|
You can simply define the following parent POM in your project's pom.xml:
|
|
|
|
<parent>
|
|
<groupId>org.alfresco.enterprise</groupId>
|
|
<artifactId>alfresco-platform-parent</artifactId>
|
|
<version>4.0.1</version>
|
|
</parent>
|
|
|
|
In Maven geek terms, this parent POM will define <dependencyManagement>, <pluginManagement> and <properties> elements
|
|
related with Alfresco-produced artifacts.
|
|
|
|
The main goal of this approach is to give you full access to Alfresco artifacts without needing to handle dependency
|
|
and plugin management inside your pom.xml.
|
|
|
|
Please note that Alfresco artifacts are not shipped with POM files at the moment, therefore transitive dependencies
|
|
are not handled; you will need to define them explicitly in your pom.xml (using <scope>provided</scope>
|
|
|
|
- A set of useful build features around Alfresco web integrations, which are also inherited by alfresco-platform-parent;
|
|
if you want to use it directly and skip alfresco-platform-parent, you can define:
|
|
|
|
<parent>
|
|
<groupId>org.alfresco.enterprise</groupId>
|
|
<artifactId>alfresco-developer-parent</artifactId>
|
|
<version>1</version>
|
|
</parent>
|
|
|
|
In this case you will have to re-define a list of properties to set your dependency versions:
|
|
|
|
<alfresco.version>4.0.1</alfresco.version>
|
|
<spring.version>3.0.5.RELEASE</spring.version>
|
|
<h2.version>1.3.158</h2.version>
|
|
<h2-support.version>1.2</h2-support.version>
|
|
<servlet.api.version>2.5</servlet.api.version>
|
|
<faces.version>1.1_02</faces.version>
|
|
<digester.version>1.6</digester.version>
|
|
<log4j.version>1.2.15</log4j.version>
|
|
|
|
Besides the alfresco-integration-parent items inherited, this parent POM provides 3 commonly used features that can
|
|
be easily enabled/disabled/configured:
|
|
|
|
* AMP overlay into an Alfresco (or Share) Extension
|
|
---
|
|
Activation: built-in
|
|
---
|
|
When your project (or sub-module) is a <packaging>war</packaging>, you can automatically include one or more
|
|
AMP files by defining the dependencies into the pom.xml, as follows:
|
|
<dependency>
|
|
<groupId>com.mycompany</groupId>
|
|
<artifactId>amp-module</artifactId>
|
|
<version>1.0-SNAPSHOT</version>
|
|
<type>amp</type>
|
|
</dependency>
|
|
The AMP files will be overlayed on top of your current WAR customizations, therefore
|
|
they can override the content of the original WAR.
|
|
|
|
-- oOo --
|
|
|
|
* Multi-environment property filtering
|
|
---
|
|
Activation: exists src/main/properties
|
|
---
|
|
You can enable multi-environment property filtering by simply creating the
|
|
src/main/properties/${env}/${webapp.resource.filter} file with your property values;
|
|
all files included in src/main/resources and src/main/properties will be filtered
|
|
with your properties defined; in order to switch between environments,
|
|
simply attach -Denv=yourenv to your mvn commands.
|
|
---
|
|
Properties
|
|
---
|
|
<env>local</env>
|
|
<webapp.resource.filter>alfresco-global.properties</webapp.resource.filter>
|
|
<webapp.resource.build.folder>${project.build.outputDirectory}</webapp.resource.build.folder>
|
|
<webapp.name>${project.artifactId}</webapp.name>
|
|
|
|
-- oOo --
|
|
|
|
* Jetty H2 configuration
|
|
---
|
|
Activation: exists jetty/jetty.xml
|
|
---
|
|
You can enable Jetty to run your application(s); by default Jetty will run all contexts
|
|
using jetty/jetty.xml as Jetty Server configuration, allowing to add the jndi resource
|
|
needed to start Alfresco Repository webapp; if you want to run multiple webapps - for
|
|
example share and alfresco - follow the example listed below:
|
|
<plugin>
|
|
<groupId>org.mortbay.jetty</groupId>
|
|
<artifactId>maven-jetty-plugin</artifactId>
|
|
<executions>
|
|
<execution>
|
|
<id>run</id>
|
|
<goals><goal>run</goal></goals>
|
|
<phase>package</phase>
|
|
<configuration>
|
|
<contextPath>/</contextPath>
|
|
<webAppSourceDirectory>.</webAppSourceDirectory>
|
|
<webXml>jetty/root-web.xml</webXml>
|
|
<contextHandlers>
|
|
<contextHandler implementation="org.mortbay.jetty.webapp.WebAppContext">
|
|
<war>${project.basedir}/../alfresco/target/alfresco.war</war>
|
|
<contextPath>/alfresco</contextPath>
|
|
</contextHandler>
|
|
<contextHandler implementation="org.mortbay.jetty.webapp.WebAppContext">
|
|
<war>${project.basedir}/../share/target/share.war</war>
|
|
<contextPath>/share</contextPath>
|
|
</contextHandler>
|
|
</contextHandlers>
|
|
</configuration>
|
|
</execution>
|
|
</executions>
|
|
</plugin> |