Develop with Eclipse

Introduction

Goal

Use the Eclipse IDE to work on Bloomreach Experience Manager implementation projects.

Background

Eclipse integrates with Maven to enable creating, building, running and debugging projects within the IDE.

Eclipse Plugins

Maven Integration for Eclipse

Maven Integration for Eclipse is required to work with Bloomreach Experience Manager projects in Eclipse. It comes pre-installed with the Eclipse for Java EE Developers package, which we recommend you use.

Freemarker Plugin

A Freemarker Plugin for Eclipse is available as part of the JBoss Tools Project and can be installed separately.

1. Choose Help > Eclipse Marketplace.
2. Search for "Freemarker".
3. Under "Freemarker IDE from JBoss Tools", choose Install.
4. A tree of checkboxes will appear, uncheck all (by unchecking the root) except FreeMarker IDE.

YEdit Plugin

It is recommended to install YEdit for editing your repository data YAML files.

1. Choose Help > Eclipse Marketplace.
2. Search for "YEdit".
3. Choose Install.

Create a New Bloomreach Experience Manager Project

1. Choose File > New > Maven Project.
2. Optionally specify a non-default project location and/or a working set.
3. Choose Next.
   If this is the first time you create a Bloomreach Experience Manager project in Eclipse, you must first choose Add Archetype... and enter the Bloomreach Experience Manager Maven archetype coordinates:
   Archetype Group Id: org.onehippo.cms7
   Archetype Artifact Id: hippo-project-archetype
   Archetype Version: 13.0.0 (or the latest version)
   Repository URL: https://maven.bloomreach.com/repository/maven2/ (or https://maven.bloomreach.com/repository/maven2-enterprise/ if you hold an enterprise license)
4. At Catalog choose Nexus Indexer.

5. Choose the archetype with Group Id org.onehippo.cms7 and Artifact Id hippo-project-archetype.

   The latest version of the archetype is automatically selected. To select an earlier version, uncheck Show the last version of Archetype only.
6. Choose Next.
7. Enter a Group Id, Artifact Id, Version and Package for the new project.
8. Choose Finish to generate the project.

Import an Existing Bloomreach Experience Manager Project

1. Choose File > Import....
2. Select Maven > Existing Maven Projects.
3. Choose Next.
4. Browse to the root directory of your project.
5. Optionally add the project to a working set.
6. Choose Finish to import the project.

Run or Debug a Bloomreach Experience Manager Project on a Tomcat Server within Eclipse

1. First prepare a local Tomcat installation:
   1. Download Tomcat 9 and install it on your development machine. Do not run it yet, you will do this from within Eclipse later on.
   2. Build and run your Bloomreach Experience Manager project from the command line. Once it is running, stop it by pressing Ctrl+C.
   3. Copy the following files from your project's target/tomcat9x folder to your Tomcat installation (use the exact same folder hierarchy and replace existing files):
      1. common/lib/*.jar
      2. shared/lib/*.jar except your project's repository-data-development and repository-data-site-development jars (e.g. myproject-repository-data-development-1.0.0.jar & myproject-repository-data-site-development-1.0.0.jar).
      3. conf/context.xml
      4. conf/catalina.properties
2. Configure the Tomcat Server in Eclipse:
   1. Choose File > New > Other, select Server > Server and choose Next.
   2. Select Apache > Tomcat v9.0 Server and choose Next.
   3. Set Tomcat installation directory to the location of your local Tomcat installation prepared in step 1, and choose Next.
   4. Select the cms, essentials and site modules of your project in the Available column and add them to the Configured column, and choose Finish.
   5. Choose Window > Show View > Servers.
   6. Double-click to open Tomcat v9.0 Server at localhost.
   7. Under General Information click on Open launch configuration.

   8. Select the Arguments tab and add the following arguments to those already there in the VM arguments box (use the appropriate paths for your situation):

      -Dderby.stream.error.file="/Users/hippo/apache-tomcat-9.0.13/logs/derby.log"
      -Dlog4j.configurationFile=file:/Users/hippo/workspace/myproject/conf/log4j2-dev.xml
      -Dproject.basedir=/Users/hippo/workspace/myproject
      -Drepo.path=/Users/hippo/workspace/myproject/storage
      -Xms256m -Xmx1024m

   9. Under Server Locations select the option Use Tomcat installation (takes control of Tomcat installation).
   10. Under Timeouts raise the Start timeout to 200.
   11. Choose File > Save to save the server configuration.
3. Configure the cms application to include the repository-data-development module in its deployment assembly:
   1. Right click on your project's cms module (e.g. myproject-cms) and select Properties.
   2. Select Deployment Assembly.
   3. Click on Add.
   4. Select Project and click on Next.
   5. Select your project's repository-data-development module (e.g. myproject-repository-data-development) and click on Finish.
   6. Click Apply and Close.
4. Configure the site web application to include the repository-data-site-development module in its deployment assembly:
   1. Right click on your project's webapp module (e.g. myproject-webapp) and select Properties.
   2. Select Deployment Assembly.
   3. Click on Add.
   4. Select Project and click on Next.
   5. Select your project's repository-data-site-development module (e.g. myproject-repository-data-site-development) and click on Finish.
   6. Click Apply and Close.
5. Configure the repository-data-webfiles module not to be auto-redeployed by Eclipse (web files are automatically synchronized by the Bloomreach Experience Manager application):
   1. Right click on your project's repository-data-webfiles module (e.g. myproject-repository-data-webfiles) and select Properties.
   2. Select Deployment Assembly.
   3. There should be one entry: src/main/resources. Remove it so the list is empty.
   4. Click Apply and Close.
6. Configure the context root of the site webapp:
   1. Right click on your project's webapp module (e.g. myproject-webapp) and select Properties.
   2. Select Web Project Settings.
   3. Change Context root from site to your project name, e.g. myproject.
7. To run your Bloomreach Experience Manager project on the Tomcat server click on the Run icon in the Servers view.
8. To debug your Bloomreach Experience Manager project on the Tomcat server click on the Debug icon in the Servers view.

Troubleshooting

If Tomcat won't start because of:

java.lang.NoClassDefFoundError: Lorg/slf4j/Logger

Then you either did not copy the shared folder correctly, or you did not copy the conf/catalina.properties correctly.

Debug a Bloomreach Experience Manager Project Running Outside Eclipse

If you choose to run your Bloomreach Experience Manager project from the command line, you can still use Eclipse for debugging by attaching its debugger to the running application.

1. Choose Run > Debug Configurations...
2. Select Remote Java Application and click on the New launch configuration icon in the top left corner of the dialog.
3. Enter a Name for this debug configuration.
4. On the Connect tab, at Project browse to the project you want to debug. Typically this is the webapp module, e.g. myproject-webapp.
5. Make sure Port is set to 8000.
6. Choose Apply to save the debug configuration.
7. Choose Debug to attach de Eclipse debugger to the running application.

If you now set breakpoints in your code Eclipse will open the debug perspective when your application executes that code.