Tags:
Related
Recommended

Getting started with DXA.Java

Niclas Cedermalm

This blog post will help you getting started with DXA (Digital Experience Accelerator) for Java and setup your DXA development environment. By following these steps you are then ready to do development on the DXA stack.
  
This is my first blog article about DXA.Java. I will publish a number of blog articles in the nearest future about DXA.Java (inspired by Jarmo’s blog marathon [;)]). I have been active in contributing to the code base of DXA.Java the recent year and done a number of modules (some of them I will soon make available for the community). 
  
So in principle you need to do 5 simple steps to get a complete DXA.Java development environment:
  1. Download the DXA.Java distribution
  2. Install DXA in SDL Tridion
  3. Install non-public JARs to your local Maven repository
  4. Get the DXA source code from Github & compile/install it your local Maven repository
  5. Create a DXA web application 

Before you start

The following you need to have available in your environment:
  • A vanilla SDL Tridion 2013 SP1 HR1 instance (is not needed to be on the same machine)
  • SDL Tridion content delivery setup with Broker DB, deployer and preview service
  • Tomcat 7.x/8.x
  • Java 7/8
  • Java IDE such as IntelliJ IDEA, Eclipse, Netbeans etc
  • Maven 3.x

Step 1: Download the DXA.Java distribution

The distribution we gonna use for installing the needed Tridion stuff + getting the needed non-public JARs. The rest we will compile using the sources on Github.

Step 2: Install DXA in SDL Tridion

First you need to install the DXA publications to your SDL Tridion instance. This is done by using an import script provided by the DXA distribution. Following the instructions on docs.sdl.com to install DXA in your SDL Tridion instance:
  
After you have installed your publications you need to have a populate your broker database with the DXA settings + example content. This is done by publishing all pages in the 400 Example Site publication. This is described in detail in:

Step 3: Install non-public JARs to your local Maven repository

Go to the following folder in your DXA.Java 1.2 distribution: web/tridion-libs/7.1.0 and run the following:
mvn install
This will install all needed Tridion, DD4T and non-public 3PP JARs into your local maven repository. 
In addition to be able to compile the DXA code you also need to add the Microsoft SQL Server JDBC v4.0 JAR into your Maven repository. This will hopefully be corrected in a future version as DXA core does not need any specific JDBC driver. That is something you select when you assemble your web application. Anyhow you can download the JAR file from Microsoft here: http://www.microsoft.com/en-us/download/details.aspx?id=11774 
You then install the JAR file by doing:      
mvn install:install-file -DgroupId=com.microsoft.sqlserver -DartifactId=sqljdbc4 -Dversion=4.0 -Dpackaging=jar -Dfile=sqljdbc.jar
  
So now we have done all preparations needed to be able to compile and run DXA locally on your machine.

Step 4: Get the DXA source code from Github & compile/install it your local Maven repository

The DXA JARs are provided by the DXA distribution (hidden in the packaged webapp), but I prefer to package the JARs myself and install them into the local Maven repository. You get the DXA code from Github by doing: 
Compile it (and make it available to your maven repo) by doing:
mvn install
In this stage you can create a new workspace/project in your IDE where you include the DXA code if you want (by normally just include the master POM file and the the IDE will find all sub-projects). See below for how you do that through IntelliJ IDEA:
This can be handy to help understand how DXA code works, but it is not necessary to have the code into your IDE. Is is enough to just have it as Maven dependencies. 
The DXA modules are in a separate repository, so you need to get that as well to be able to have a functional web application. The module we need primarily is the core module (dxa-module-core) to get the core controllers, models and views. To get the code you do the following:
git clone https://github.com/sdl/dxa-modules
And then go into the directory ‘webapp-java’ and compile & install those modules into your Maven repository:
mvn install
If you want you can import the modules into your IDE in the same way as with the DXA source code.

Step 5: Create web application

As base for your webapp you can copy the whole example-webapp from the DXA source. This will be available as a Maven archetype in a later version of DXA, but until then we have copy and manually do some changes: 
 
- Modify the pom.xml to your preferred group ID, artefact ID & version:
  <groupId>com.yourcompany</groupId>
  <artifactId>your-webapp</artifactId>
  <version>your-version</version>
  <packaging>war</packaging>
- Add the following runtime dependencies:
 <dependency>
      <groupId>org.codehaus.jettison</groupId>
      <artifactId>jettison</artifactId>
      <version>1.3.4</version>
 </dependency>
 <dependency>
      <groupId>net.sf.ehcache</groupId>
      <artifactId>ehcache</artifactId>
      <version>2.8.2</version>
 </dependency>
 <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-context-support</artifactId>
      <version>3.2.0.RELEASE</version>
</dependency>
- Make sure that the Maven property ‘dxa.version’ corresponds with the version used in the DXA master pom
- Add dependency to the JDBC driver you want to use for your web application, e.g. Oracle, MS-SQL server
  (MS-SQL server JDBC driver is already included as a DXA dependency)
- Modify the WebAppConfiguration class and your base package for your code (for your custom controllers):     
  @Configuration
  @ComponentScan(basePackages = {"com.sdl.webapp", "com.sdl.dxa". "com.yourpackage"})
  public class WebAppConfiguration {
  }
- Refactor the package com.sdl.webapp.main to your preferences.
- Copy needed Tridion XML config to the src/main/resources folder. You need at least the following configuration files:
cd_storage_conf.xml, cd_dynamic_conf.xml, cd_ambient_conf.xml, cd_link_conf.xml & cd_licences.xml. You can copy templates from web/install/source-config in the DXA1.2 distribution. See the following doc resource for details on how to configure those files:
Make sure that your entry in cd_dynamic_conf.xml & cd_link_conf.xml matches your Tomcat setup (e.g. localhost port 8080) and that you add the configuration needed for a staging site.
After that you are good to compile your first DXA webapp by either do 'mvn package' or include the project in your IDE of your preference. Next step is to add your webapp to a Tomcat configuration within your IDE. Right now DXA requires to be the root webapp (it will be improved in later versions of DXA). Below is how you do that through IntelliJ IDEA:

1. Select ‘Edit Configurations'
2. Add new configuration -> Tomcat Server -> Local

3. Configure your Tomcat server by selecting your Tomcat instance and then configure as below. The JVM options you can tune to your preference depending on your webapp characteristics. I usually use the following JVM options for DXA, which works fine as a good starting point: 

-Xms512m -Xmx1024m -XX:MaxPermSize=128M -Dfile.encoding=UTF8

5. Then you add your webapp as an exploded WAR to the Tomcat server and set application context to ‘/‘ (root webapp):

6. Click ‘Ok’ and then you have Tomcat configuration for your new DXA webapp.
7. So now you can just click on the Run button and the Tomcat server will startup with your webapp. If no errors in the console, you should be able to go to http://localhost:8080 in your browser and a functional DXA site should appear:

And now you are ready to start developing on DXA!
  
I will in my next-coming blog posts describe how you create new DXA.Java modules and customize the look&feel. I plan also to touch on topics such as how to enable Contextual Image Delivery (CID) and getting started with DXA.Java and SmartTarget.