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.

• CRXDE Lite within the CQ5 instance to create and edit nodes and properties within the CRX repository.

• FileVault (VLT), an Adobe-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.

Create a simple project structure in CQ5:

1. Install CQ5 on your computer. See Installing CQ5 for the procedure. In the context of this article, CQ5 runs locally on port 4502.

   If CQ5 is already installed, ensure it is running and open the Welcome page in your web browser.

2. Open CRXDE Lite (http://localhost:4502/crx/de/) and create the project structure:

   1. Under the /apps folder, create the nt:folder named myApp.

   2. Under the myApp folder, create the nt:folder named components.

   3. Under the myApp folder, create the nt:folder named templates.

   4. Under the myApp folder, create the nt:folder named install.
   5. Click Save All

3. In your browser, navigate to the Tools page of WCM (http://localhost:4502/miscadmin).

4. Select the Designs folder, click New, and enter the following property values:

   • Title: My Application Design Page.

   • Name: myApp.

   • Template: Select Design Page Template.

5. Click Create.

FileVault (VLT) maps the content of a CRX instance to your file system. VLT functionalities are similar to those of an SVN client. You can perform check in, check out, and other file-management operations. Configuration options enable flexible representations of project content.

Install VLT:

1. Copy the FileVault archive file from the cq-quickstart/opt/filevault directory of your CQ5 installation. Copy either filevalut.tgz or filevault.zip, depending on your operating system.

   You can also download the latest version of FileVault from Daycare.
   

2. Extract the archive.

3. Add <archive-dir>/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/helpers/vault-cli-2.4.8/bin

4. Open a command line shell and execute vlt --help. Make sure it displays the following help screen:

   --------------------------------------------------------------------------------
   Jcr File Vault [version 2.4.8] Copyright 2011 by Adobe Systems Incorporated     
   --------------------------------------------------------------------------------
   Usage:                                                                          
     vlt [options]  [arg1 [arg2 [arg3] ..]]                               
   --------------------------------------------------------------------------------
   
   Global options:                                                                 
     -Xjcrlog                 Extended JcrLog options (omit argument for help)     
     -Xdavex                  Extended JCR remoting options (omit argument for     
                              help)                                                
     --credentials            The default credentials to use                       
     --config                 The JcrFs config to use                              
     -v (--verbose)           verbose output                                       
     -q (--quiet)             print as little as possible                          
     --version                print the version information and exit               
     --log-level              the log4j log level                                  
     -h (--help)              print this help                                      
   Commands:                                                                       
     export                   Export the Vault filesystem                          
     import                   Import a Vault filesystem                            
     checkout (co)            Checkout a Vault file system                         
     analyze                  Analyze packages                                     
     status (st)              Print the status of working copy files and           
                              directories.                                         
     update (up)              Bring changes from the repository into the working   
                              copy.                                                
     info                     Displays information about a local file.             
     commit (ci)              Send changes from your working copy to the           
                              repository.                                          
     revert (rev)             Restore pristine working copy file (undo most local  
                              edits).                                              
     resolved (res)           Remove 'conflicted' state on working copy files or   
                              directories.                                         
     propget (pg)             Print the value of a property on files or            
                              directories.                                         
     proplist (pl)            Print the properties on files or directories.        
     propset (ps)             Set the value of a property on files or directories. 
     add                      Put files and directories under version control.     
     delete (del,rm)          Remove files and directories from version control.   
     diff (di)                Display the differences between two paths.           
     rcp                      Remote copy of repository content.                   
     console                  Run an interactive console                           
   --------------------------------------------------------------------------------
   

Eclipse is open-source software that you will use to edit project source files on your file system. Apache Maven is also open source software that compiles Java code and stores the compiled code in a JAR file (snapshot build).

Install Eclipse and a Maven plugin that provides the Maven functionality within Eclipse:

1. Download Eclipse - select the Eclipse IDE for Java EE Developers option.

2. Install Eclipse: extract from the downloaded zip file to your destination directory.

3. 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.

4. In the default workspace, create a new project and name it myApp.

5. Install the Maven Integration for Eclipse (m2e) plugin from Eclipse.org. See the instructions at http://marketplace.eclipse.org/content/maven-integration-eclipse.
   

6. After installation, restart Eclipse.

In this section, you 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:

1. In Eclipse, click File > New > Other.
2. In the dialog, select Maven > Maven Project and click Next.
3. Select the Create a simple project option and the Use default Workspace location option, then click Next.
4. Specify the following property values for the Maven project, and accept the default values for all other properties:

   • 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. In the Project Explorer view, right-click the ui project and click Properties.

2. Select Java Compiler and set following properties to 1.5:

   • Compiler compliance level

   • Generated .class files compatibility

   • Source compatibility

3. Click OK.

Create the filter.xml file that defines the content that VLT exports:

1. In the Project Explorer view, in the ui/src/main folder, 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"?>
   
   <!-- Defines which repository items are generally included -->
   
   <workspaceFilter version="1.0">
   
       <filter root="/apps/myApp" />
   
       <filter root="/etc/designs/myApp" />
   
   </workspaceFilter>
   
   

6. Save filter.xml.

Use VLT to check out the CQ5 content into your ui project:

1. In the system command line, change the current directory to the following directory in 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. VLT uses these files.

In the ui Eclipse project, create a link to the apps folder that you just checked out. This link enables your JSP scripts to reference the files:

1. Right-click ui, select New, then Folder.

2. In the dialog box, click Advanced and select Link to alternate location.

3. Click Browse,  specify <eclipse>/<workspace>/myApp/ui/src/main/content/jcr_root/apps, and then click OK.

4. Click Finish.

The apps folder appears below the ui project in the Project Explorer view.

Add the CQ and Sling libraries (.jar files) that you require to the Eclipse classpath. Copy the libraries from the  repository to a local folder, and add the folder to the Eclipse classpath. In this exercise, you reference the following libraries:

• /libs/sling/install

• /libs/cq/commons/install

• /libs/wcm/core/install

Obtain the libraries using WebDAV:

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 using a WebDAV client.

3. Copy all of the .jar files from the following directories to your cq5libs directory:

   • /libs/sling/install

   • /libs/cq/commons/install

   • /libs/wcm/core/install

4. In Eclipse, right-click the ui project and click Build Path > Configure Build Path. In the dialog select the Libraries tab.

5. Click Add External JARS, browse to the cq5libs folder and select all the JAR files, then click Open.

6. Click OK.

Instead of WebDAV, you can use a script. The following script downloads all the libraries from a CQ5 instance. It is for Unix-like systems (such as Mac OS X and Linux) and uses the '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. Open the OSGi console and click the Configuration Status tab (http://localhost:4502/system/console/config).

2. Select the Bundles tab.

3. Search for the package in the Exported Packages of the bundles.

In Eclipse, create the Core Maven project:

1. Click File > New > Other.

2. In the dialog, select Maven > Maven Project and click Next.

3. Select the Create a simple project option and the Use default Workspace locations option, then click Next.

4. Specify the following property values, and accept the default values for other properties:

   • 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. In the Project Explorer view, open the pom.xml file under core.

2. Click the pom.xml tab at the bottom of the editor, and copy the following code before the closing </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=${project.version} </Export-Package> 
                       </instructions>
                  </configuration> 
             </plugin> 
        </plugins>
   </build>
   <dependencies> 
        <dependency> 
             <groupId>com.day.cq.wcm</groupId>
              <artifactId>cq-wcm-api</artifactId> 
             <version>xxx.xxx.xxx</version> 
        </dependency>
        <dependency> 
             <groupId>com.day.cq</groupId> 
             <artifactId>cq-commons</artifactId> 
             <version>xxx.xxx.xxx</version> 
        </dependency> 
        <dependency> 
             <groupId>org.apache.sling</groupId>
             <artifactId>org.apache.sling.api</artifactId> 
             <version>xxx.xxx.xxx</version>
        </dependency> 
   </dependencies>
   

3. Replace the xxx.xxx.xxx versions with the ones available in the CQ version that you are using. For example, for CQ 5.5, use the following bundle versions:

   • cq-wcm-api: 5.5.0
   • cq-commons: 5.5.0
   • org.apache.sling.api: 2.2.4

   Tip: To find the current bundle versions use the Configuration Status tab of the OSGi Console (http://localhost:4502/system/console/config).

4. Save pom.xml.

If the dependencies are not stored in the local Maven repository, compiler errors appear in the pom.xml file.

Note: Perform the following procedure only if the three CQ5 artifacts are not globally deployed for the project on a public Maven repository (such as using Apache Archiva).

Deploy the CQ5-specific artifacts as defined in pom.xml (cq-wcm-api, cq-commons and org.apache.sling.api) to the local Maven repository:

1. In your file system, copy the file cq-wcm-api-{version}.jar located at cq5libs/wcm (you have created those folders before) into <your-user-dir>/.m2/repository/com/day/cq/wcm/cq-wcm-api/{version} (create the folders if they do not exist).

2. In your file system, copy the file cq-commons-{version}.jar located at cq5libs/cq (you have created those folders before) into <your-user-dir>/.m2/repository/com/day/cq/cq-commons/{version} (create the folders if they do not exist).

3. In your file system, copy the file org.apache.sling.api-{version}.jar located at cq5libs/sling (you have created those folders before) into <your-user-dir>/.m2/repository/org/apache/sling/org.apache.sling.api/{version} (create the folders if they do not exist).

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 the core/src/main/java folder:

1. Under core, right-click the src/main/java folder and click New > Package.

2. Enter the name com.day.cq5.myapp and click Finish.

When editing UI code use the following sequence:

• Use CRXDE Lite to create a template and a component.

• Use VLT to update your file system with the new files.

• Use Eclipse to develop the component script (JSP).

• Use VLT to check in the changes.

1. Open CRXDE Lite in your web browser (http://localhost:4502/crx/de/).
2. Right-click /apps/myApp/templates and click Create > Create Template.
3. Specify the following template properties:
   • Label: contentpage
   • Title: Content Page
   • Resource Type: myApp/components/contentpage
4. Click Next.
5. Add the following allowed path and click Next.
   /content(/.*)?
6. Click Next and then click OK.
7. Select the /apps/myApp/templates/contentpage/jcr:content node.
8. In the Properties tab, add a property:
   • Name: personName
   • Type: String
   • Value: myName
9. Click Save All.
10. Right-click /apps/myApp/components and click Create > Create Component:
    • Label: contentpage
    • Title: Content Page
    • Super Type: cq:Component
11. Click Next, Next, Next, OK.
12. Click Save All.

1. From the system command line change the current directory to <eclipse>/<workspace>/myApp/ui/src/main/content/jcr_root.
2. Execute the following command to see the status of the repository files:
   vlt st -v
3. Execute the following command to update your file system with the changes in the repository:
   vlt up -v

1. In Eclipse, navigate to ui/src/main/content/jcr_root/apps/myApp/components/contentpage.

   You might need to refresh the Project Explorer view to see this folder.

2. Open contentpage.jsp.

3. Add the following code as the final line:
   

   This is the contentpage component.

4. Click File > Save.
   

1. From the system command line change the current directory to <eclipse>/<workspace>/myApp/ui/src/main/content/jcr_root.

2. To see the changes on the file system, execute the following command:

   vlt st -v

3. Execute the following command to commit the changed contentpage.jsp file to the repository:

   vlt ci -v
   

1. Open the CQ5 Websites page in your web browser (http://localhost:4502/siteadmin#/content).
2. Select the Websites folder and click New > New Page. Provide a title and name for the page, such as My Page, and mypage.
   
3. Select the Content Page template and click Create.
4. Open the page and verity that it contains the following text:

   This is the contentpage component.

Use the following process to develop code for the core module:

• Create and compile a Java class. Package the class in a JAR file that can be deployed to CQ.
  

• Reference the JAR file in the ui project build path.

• Add logic to the JSP script so that it uses the Java class.

• Use VLT to update the JSP file in the repository.

• Use VLT to add and upload the JAR file (with the compiled class) to the repository.

The following example illustrates this process.

1. In the core project in Eclipse, under core/src/main/java, right-click the com.day.cq5.myapp package and click New > Class.

2. Name the class HelloPerson and click Finish. 

3. In HelloPerson.java replace the existing code with the following code:

   package com.day.cq5.myapp;
   
   import com.day.cq.wcm.api.Page;
   
   public class HelloPerson {
       private Page personPage;
       //the name of the page property defined in the contentpage template
       public static final String PN_PERSON_NAME = "personName";
       public HelloPerson(Page personPage) {
           this.personPage = personPage;
       }
   /*
    * Retrieves the PN_PERSON_NAME property from personPage and returns it.
    * Checks for null value before returning.
    */
       public String getHelloMessage() {
           String personName = personPage.getProperties().get(PN_PERSON_NAME).toString();
           return personName != null ? personName : "--empty--";
       }
   }

4. Save HelloPerson.java.

5. To compile and package the Java class, right-click the core project and click Run As > Maven Install.

   The core-0.0.1-SNAPSHOT.jar file (containing the compiled class) is created and saved in the core/target folder.

Add core-0.0.1-SNAPSHOT.jar to the build path of the ui project so that the contentpage.jsp script can use the class:

1. In Eclipse, right-click the ui project and click Build Path > Configure Build Path. Then, select the Libraries tab.

2. Click Add JARS, select core/target/core-0.0.1-SNAPSHOT.jar file, and click OK.

3. Click OK to close the Java Build Path dialog.

1. In Eclipse, open contentpage.jsp from the ui/src/main/content/jcr_root/apps/myApp/components/contentpage folder.

2. Replace the existing code with the following code:

   <%@ 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 contentpage component.

3. Save the changes.
4. To update the repository, open a system command line window and change the current directory to <eclipse>/<workspace>/myApp/ui/src/main/content/jcr_root.
5. To see the changes to the file system, execute the following command:

   vlt st -v

6. To commit the contentpage.jsp file to the repository, execute the following command:

   vlt ci -v

1. In Eclipse, under core/target, copy the core-0.0.1-SNAPSHOT.jar file.
2. In Eclipse navigate to ui/src/main/content/jcr_root/apps/myapp/install and paste the copied file.
3. In the system command line, change the current directory to <eclipse>/<workspace>/myApp/ui/src/main/content/jcr_root.
4. To see the changes to the file system, execute the following command:

   vlt st -v


5. To place the JAR file under version control, execute the following command:

   vlt add apps/myApp/install/core-0.0.1-SNAPSHOT.jar -v

6. To commit the JAR file to the repository, execute the following command:

   vlt ci -v

1. In your web browser, refresh the CQ5 page and ensure that it displays the following message:

   Hello, myName.

   This is the contentpage component.

2. In CRXDE Lite, select the /apps/myApp/templates/contentpage/jcr:content node and change the value of the personName property.
3. Save the changes and refresh the web page and verify that the new value appears.

This section points to three open source software projects that 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.

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:

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. Archiva can be found here.

When setting up Archiva for a CQ project the only step that is specific to CQ itself is initially populating the repository with the artifacts needed for CQ development. To acquire the full set of libraries you can use the same method as described above in point #7 of Create The UI Maven Project.

You can use the same script as shown there (and reproduced here):

This script simply downloads all the libraries from your CQ installation. By deploying these libraries to your Archiva repository, you can make them available to your whole development team. To deploy the downloaded files to Archiva, see the Archiva documentation here.

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.