Developing with Eclipse

This section describes the process of setting up a local development environment for a simple CQ5 project with Eclipse. It then describes how to integrate logic into the project through Java coding and JSP scripting. Lastly, it points to open source software to enable collaborative and automated developing.

Please refer to the corresponding documentation for more information on the different development environments that are available.

The local development environment involves:

A CQ5 installation that will act as your local environment.
CRX Explorer within the CQ5 instance to create and edit nodes and properties within the CRX repository.
FileVault (VLT), a Day developed utility that maps the CRX repository to your file system.
Eclipse to edit the project source on your local file system.
Apache Maven to run local snapshot builds.

Creating the Project Structure in CQ5

This section describes the creation of a simple project structure in CQ5:

Install CQ5 on your machine. Please refer to Installing CQ5 for the detailed procedure. In the current context, CQ5 runs locally on port 4502.

If already installed then ensure it is running and connect.
In the CRX Explorer, create the project structure:
1. Under the /apps folder, create the nt:folder myApp.
2. Under the myApp folder, create the nt:folder components.
3. Under the myApp folder, create the nt:folder templates.
4. Under the myApp folder, create the nt:folder install.
In your browser, navigate to the Tools tab. Under designs, create the design page of your application:
- Title: My Application Design Page.
- Name: myApp.
- Template: Design Page Template.

Installing FileVault (VLT)

FileVault (VLT) is a tool developed by Day that maps the content of a CRX instance to your file system. The VLT tool has similar functionalities to those of an SVN client, providing normal check in, check out and management operations, as well as configuration options for flexible representation of the project content.

To install VLT, follow the steps:

In your file system, go to <cq-installation-dir>/crx-quickstart/opt/filevault. The build is available in both tgz and zip formats.
Extract the archive.
Add <cq-installation-dir>/crx-quickstart/opt/filevault/vault-cli-<version>/bin to your environment PATH so that the command files vlt or vlt.bat are accessed as appropriate. For example, <cq-installation-dir>/crx-quickstart/opt/filevault/vault-cli-1.1.2/bin
Open a command line shell and execute vlt --help. Make sure it displays the following help screen:

Installing Eclipse

Eclipse is open source software used to edit the project source locally on your file system. Apache Maven is also open source software, used to run local snapshot builds: it compiles Java code and stores the compiled code in a jar file.

In this section, you will install Eclipse and a Maven plugin which embeds the Maven functionality within Eclipse:

Download Eclipse - select the Eclipse IDE for Java EE Developers option.
Install Eclipse: extract from the downloaded zip file to your destination directory.
Start Eclipse:
1. Navigate to the directory into which you extracted the contents of the Eclipse installation zip file. For example C:\Program Files\Eclipse\.
2. Double-click eclipse.exe (or eclipse.app) to start Eclipse.
Create a new workspace for your project and name it myApp.
Install the Maven plugin (m2) from Sonatype: check the documentation at http://m2eclipse.sonatype.org/.
Note: Day recommends to disable Maven SCM handler for Subclipse and Maven Integration for AJDT.
After installation it is recommended to restart Eclipse.

Creating the Project Structure in Eclipse

In this section, you will create two Maven projects:

one called UI (after User Interface) which contains the CQ5 project structure with the JSP scripts.
the other called Core which contains the Java code (source and compiled). The compiled code is stored in a jar file.

The advantage of such a structure is that it adds modularity and autonomy to the logic of your application because each jar file (bundle) can be managed separately.

Create the UI Maven Project

To create the UI Maven project, follow the steps:

In Eclipse open the Workbench.
Create the UI Maven project:
1. In the Menu bar, click File, select New, then Other... .
2. In the dialog, expand the Maven folder, select Maven Project and click Next.
3. Check the Create a simple project box and the Use default Workspace locations box, then click Next.
4. Define the Maven project:
  - Group Id: com.day.cq5.myapp
  - Artifact Id: ui
  - Name: CQ5 MyApp UI
  - Description: This is the UI module
5. Click Finish.
Set the Java Compiler to version 1.5:
1. Right-click the ui project, select Properties.
2. Select Java Compiler and set following properties to 1.5:
  - Compiler compliance level
  - Generated .class files compatibility
  - Source compatibility
3. Click OK.
4. In the dialog window, click Yes.
Create the filter.xml file which defines the content that will be exported by VLT:
1. In Eclipse, navigate to ui/scr/main and create the content folder.
2. Under content, create the META-INF folder.
3. Under META-INF, create the vault folder.
4. Under vault, create the filter.xml file.
5. In filter.xml, copy the following code to filter.xml:
  <?xml version="1.0" encoding="UTF-8"?>  <workspaceFilter vesion="1.0"> <filter root="/apps/myApp" /> <filter root="/etc/designs/myApp" /> </workspaceFilter>
6. Save the changes.
Check out the CQ5 content into your ui project with VLT:
1. From the system command line, navigate to the directory holding your Eclipse workspace <eclipse>/<workspace>/myApp/ui/src/main/content.
2. Execute the command: vlt --credentials admin:admin co http://localhost:4502/crx
  
  This command creates the folder jcr_root under <eclipse>/<workspace>/myApp/ui/src/main/content. This maps to the CRX root (/). Under jcr_root the following files and folders are created, as defined in filter.xml:
  - apps/myApp
  - etc/designs/myApp
  It also creates two files, config.xml and settings.xml in <eclipse>/<workspace>/myApp/ui/src/main/content/META-INF/vault. These are used by VLT.
To enable Eclipse to map the file paths used in the JSP scripts, create a link to the apps folder under ui:
1. Right-click ui, select New, then Folder.
2. In the dialog window, click Advanced and check the Link to folder in the file system box.
3. Click Browse, then specify <eclipse>/<workspace>/myApp/ui/src/main/content/jcr_root/apps.
4. Click OK.
5. Click Finish.
Add the necessary CQ and Sling libraries (.jar files) to the Eclipse's classpath. As the .jar files are available in the repository, you need to copy them from the folders in the repository (content from /libs/*/install) to a local filesystem folder, and add the folder to your IDE's classpath. In this example, you will reference the following libraries:
- /libs/sling/install
- /libs/cq/commons/install
- /libs/wcm/core/install
- <cq-installation-dir>/crx-quickstart/server/lib/container stored in your file system
Proceed as follows:
1. In your file system, create a CQ5 libraries folder called cq5libs. This folder can be created anywhere.
2. Map the repository to your file system by using the WebDAV access.
3. Navigate to /libs/sling/install and copy all the .jar files to the cq5libs folder.
4. Repeat the two former steps for other /libs/*/install folders.
5. In Eclipse, right-click the ui project, select Build Path, then Configure Build Path. In the dialog select the Libraries tab.
6. Click Add External JARS..., navigate to .../cq5libs, select all the jar files and click Open.
The following script downloads all the libraries from a CQ5 instance. It is for Unix-ish systems (Mac, Linux) and uses 'curl' command, but might also succeed running it on Windows with Cygwin (for unix emulation):
#!/bin/sh [ -z "$CRX_URL" ] && CRX_URL=http://localhost:4502 [ -z "$CRX_CREDENTIALS" ] && CRX_CREDENTIALS=admin:admin curl -H x-crxde-version:1.0 -H x-crxde-os:mac -H x-crxde-profile:default -u $CRX_CREDENTIALS $CRX_URL/bin/crxde.classpath.xml > .classpath FILE_LIST=`cat .classpath | sed -n '/lib/s/.*WebContent$.*$\".*/\1/p'` for file in $FILE_LIST; do echo "Downloading $file" curl -u $CRX_CREDENTIALS $CRX_URL$file -O done
To run the script:
1. Open a command line window.
2. Go to the cq5libs folder.
3. Create the file classpath.sh with the above content.
4. Run it with the following command if CQ runs on the default port (4502):
  $ sh ./classpath.sh
  or with the following command if CQ runs on a different port:
  $ CRX_URL=http://localhost:8080 sh ./classpath.sh
To find out which OSGI bundle contains the package that you need to add to your classpath:
1. Go to the Felix console and click Configuration Status.
2. Select the Bundles tab in the navigation bar below the main one.
3. Search for the package in the Exported Packages of the bundles.

Create the Core Maven Project

To create the Core Maven project, follow the steps:

In Eclipse, create the Core Maven project:
1. In the Menu bar, click File, select New, then Other... .
2. In the dialog, expand the Maven folder, select Maven Project and click Next.
3. Check the Create a simple project box and the Use default Workspace locations box, then click Next.
4. Define the Maven project:
  - Group Id: com.day.cq5.myapp
  - Artifact Id: core
  - Name: CQ5 MyApp Core
  - Description: This is the Core module
5. Click Finish.
Add the necessary plugins and dependencies to the core project:
1. Open the pom.xml file under core.
2. Copy-paste following code before the </project> tag:
  <packaging>bundle</packaging> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>1.5</source> <target>1.5</target> </configuration> </plugin> <plugin> <groupId>org.apache.felix</groupId> <artifactId>maven-bundle-plugin</artifactId> <version>1.4.3</version> <extensions>true</extensions> <configuration> <instructions> <Export-Package> com.day.cq5.myapp.*;version=${pom.version} </Export-Package> </instructions> </configuration> </plugin> </plugins> </build> <dependencies> <dependency> <groupId>com.day.cq.wcm</groupId> <artifactId>cq-wcm-api</artifactId> <version>5.3.2</version> </dependency> <dependency> <groupId>com.day.cq</groupId> <artifactId>cq-commons</artifactId> <version>5.3.2</version> </dependency> <dependency> <groupId>org.apache.sling</groupId> <artifactId>org.apache.sling.api</artifactId> <version>2.0.8</version> </dependency> </dependencies>
3. Save the changes.
Deploy the CQ5 specific artifacts as defined in the pom.xml (cq-wcm-api, cq-commons and org.apache.sling.api) to the local Maven repository:
1. In your file system, copy the the file cq-wcm-api-5.3.2.jar located at cq5libs/wcm (you have created those folders before) into <your-user-dir>/.m2/repository/com/day/cq/wcm/cq-wcm-api/5.3.2 (create the folders if they don't exist).
2. In your file system, copy the the file cq-commons-5.3.2.jar located at cq5libs/cq (you have created those folders before) into <your-user-dir>/.m2/repository/com/day/cq/cq-commons/5.3.2 (create the folders if they don't exist).
3. In your file system, copy the the file org.apache.sling.api-2.0.8.jar located at cq5libs/sling (you have created those folders before) into <your-user-dir>/.m2/repository/org/apache/sling/org.apache.sling.api/2.0.8 (create the folders if they don't exist).
You don't need to perform this step if the three CQ5 artifacts are globally deployed for the project on a Maven repository (e.g. using Apache Archiva).
Set the Java Compiler to version 1.5:
1. Right-click the core project, select Properties.
2. Select Java Compiler and set following properties to 1.5:
  - Compiler compliance level
  - Generated .class files compatibility
  - Source compatibility
3. Click OK.
4. In the dialog window, click Yes.
Create the package com.day.cq5.myapp that will contain the Java classes under core/src/main/java:
1. Under core, right-click src/main/java, select New, then Package.
2. Name it com.day.cq5.myapp and click Finish.

Scripting with Eclipse and CQ5

When editing UI code use the following sequence:

Create a template and a component with the CRX Explorer.
Update the changes with VLT (export from the repository to your file system) .
Create a component script (JSP) with Eclipse.
Check in the changes from the file system into the repository with VLT.

The following example illustrates this process:

Create a new template with the CRX Explorer:
1. In the CRX Explorer, under /apps/myApp/templates, create a new template: Name: contentpage Type: cq:Template
2. Under the contentpage Node, edit the Property jcr:title and add as Value: MyApp Content Page Template
3. Under the contentpage Node, add a new Node: Name: jcr:content Type: cq:PageContent
4. Under the jcr:content Node, edit the Property sling:resourceType and add as Value: myApp/components/contentpage
5. Under the jcr:content Node, add a new Property: Name: personName Value: myName
Create a new component with the CRX Explorer:
1. In the CRX Explorer, under /apps/myApp/components, create a new component: Name: contentpage Type: cq:Component
Use VLT to update the changes made from your repository to your file system, and therefore Eclipse:
1. From the system command line navigate to <eclipse>/<workspace>/myApp/ui/src/main/content/jcr_root.
2. Execute: vlt st --show-update to see the changes made on the repository.
3. Execute: vlt up to update the changes from the repository to your file system.
Create the component script (JSP) with Eclipse:
1. In Eclipse, navigate to ui/src/main/content/jcr_root/apps/myApp/components/contentpage.
2. Right-click contentpage, select New, then File.
3. In the dialog, name the file contentpage.jsp and click Finish.
4. Copy the following code into contentpage.jsp:
  This is the contentpage component.
5. Save the changes.
With VLT check in the changes from the file system into the repository:
1. From the system command line navigate to <eclipse>/<workspace>/myApp/ui/src/main/content/jcr_root.
2. Execute: vlt st to see the changes made on the file system.
3. Execute: vlt add apps/myApp/components/contentpage/contentpage.jsp to add the contentpage.jsp file to VLT control.
4. Execute: vlt ci to commit the contentpage.jsp file to the repository.
From CQ5 create a page based on this template. Open the page to make sure it displays the following message:

This is the contentpage component.

It is possible to define the VLT commands as External Tools in Eclipse. This enables you to run the VLT commands from within Eclipse.

Java Developing with Eclipse and CQ5

When editing Core code use the following sequence:

Create a Java class.
Compile the Java class.
Reference the jar file in the ui library.
Embed the Java Class logic into the JSP script.
Use VLT to check these changes to the JSP script (in the file system) into the repository.
Use VLT to deploy the jar file (with the compiled class) from the file system into the repository.

The following example illustrates this process:

Create the Java class:
1. In Eclipse, under core/src/main/java, right-click the com.day.cq5.myapp package, select New, then Class.
2. In the dialog window, name the Java Class HelloPerson and click Finish. Eclipse creates and opens the file HelloPerson.java.
3. In HelloPerson.java replace the existing code with the following:
  package com.day.cq5.myapp; import com.day.cq.wcm.api.Page; public class HelloPerson { private Page personPage; public static final String PN_PERSON_NAME = "personName"; public HelloPerson(Page personPage) { this.personPage = personPage; } public String getHelloMessage() { String personName = personPage.getProperties().get(PN_PERSON_NAME).toString(); return personName != null ? personName : "--empty--"; } }
4. Save the changes.
Compile the Java class:
1. Right-click the core project, select Run As, then Maven Install.
2. Make sure that a new file core-0.0.1-SNAPSHOT.jar (containing the compiled class) is created under core/target.
Reference this jar file in the ui library to enable the code completion when accessing this class with the JSP script:
1. In Eclipse, right-click the ui project, select Build Path, then Configure Build Path. In the dialog select the Libraries tab.
2. Click Add JARS... and navigate to core/target, select the core-0.0.1-SNAPSHOT.jar file and click OK.
3. Click OK to close the dialog.
Embed the Java Class logic into the JSP script:
1. In Eclipse, open the JSP script contentpage.jspin ui/src/main/content/jcr_root/apps/myApp/components/contentpage.
2. Replace the existing code with the following:
  <%@ page import="com.day.cq5.myapp.HelloPerson" %> <%@include file="/libs/foundation/global.jsp"%> <% HelloPerson hello = new HelloPerson(currentPage); String msg = hello.getHelloMessage(); %> Hello, <%= msg %>.</br></br> This is the contenpage component.
3. Save the changes.
With VTL check in the changes to the JSP script from the file system to the repository:
1. From the system command line navigate to <eclipse>/<workspace>/myApp/ui/src/main/content/jcr_root.
2. Execute: vlt st to see the changes made on the file system.
3. Execute: vlt ci to commit the modified contentpage.jsp file to the repository.
Deploy the jar file containing the compiled class from the file system into the repository with VLT:
1. In Eclipse, under core/target, copy the core-0.0.1-SNAPSHOT.jar file.
2. In Eclipse navigate to ui/scr/main/content/jcr_root/apps/myapp/install and paste the copied file.
3. From the system command line navigate to <eclipse>/<workspace>/myApp/ui/src/main/content/jcr_root.
4. Execute: vlt st to see the changes made on the file system.
5. Execute: vlt add apps/myApp/install/core-0.0.1-SNAPSHOT.jar to add the jar file to VLT control.
6. Execute: vlt ci to commit the jar file to the repository.
In your browser, refresh the CQ5 page to make sure it displays following message:
Hello, myName. This is the contentpage component.
In CRX Explorer, change the value myName and make sure that the new value is displayed when you refresh the page.

Building collaborative and automated projects

This section points to three open source softwares which enhance the development of CQ5 projects by adding collaboration and automation features:

Subversion (SVN) to manage a central repository where all the developers involved in the project can commit and retrieve the code and the content they generate on their local instance.
Apache Archiva to centrally store and retrieve the project libraries.
Apache Continuum to automate the build process.

Collaboration with Subversion (SVN)

As the CQ5 repository can be mapped to your file system with VLT, it is now easy to set up a central repository with SVN. This is used by all developers in the project as a place they can commit, and retrieve, the code and content they generate on their local instances.

The setup of an SVN server is not covered in this document as many tutorials are already available online.

When VLT is in operation it creates .vlt files within the local directory structure. These .vlt files hold timestamps and other VLT-specific information that should not be checked into the SVN repository. This can be prevented by adding .vlt to the ignore list of the local SVN setup. To do this you add the following code to the local SVN setup file - settings.xml in the .subversion directory of your user's HOME directory:

[miscellany]
### Set global-ignores to a set of whitespace-delimited globs
### which Subversion will ignore in its 'status' output, and
### while importing or adding files and directories.
global-ignores = .vlt

Central dependency management with Apache Archiva

Java libraries, called artifacts in Maven language, can be managed centrally through Apache Archiva, an artifact repository that is used to store and retrieve the project artifacts. The setup of Archiva is well detailed online and can be referenced during setup. The Archiva server requires little management outside that of configuring local developer accounts to obtain access to the snapshots and full releases.

Build automation with Apache Continuum

Once the project content and code is centrally available through an SVN server, it is possible to automate the build process and run the build on a daily basis (for example a nightly build). This is done with Apache Continuum, a continuous integration server with the sole duty of providing build management of artifacts and releases.

The setup of Continuum is also well detailed online.

Your comments are welcome!

Did you notice a way we could improve the documentation on this page? Is something unclear or insufficiently explained? Please leave your comments below and we will make the appropriate changes. Comments that have been addressed, by improving the documentation accordingly, will then be removed.