This article covers a Bloomreach Experience Manager version 12. There's an updated version available that covers our most recent release.

Develop with Eclipse

This documentation describes the use of a third-party development tool and is maintained by Bloomreach on a best-effort basis. Bloomreach cannot guarantee this documentation is up to date with the latest release of the third-party development tool. Please refer to the documentation of the third-party development tool for the latest installation, configuration, and usage instructions.

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.

This documentation has been verified using Eclipse Java EE IDE for Web Developers, version Neon Release (4.6.0).

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 "JBoss Tools".
  3. 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 Configure..., then Add Remote Catalog and add the Bloomreach Experience Manager Maven repository:
    Catalog File: https://maven.onehippo.com/maven2
    Description: Bloomreach Experience Manager
  4. At Catalog choose Bloomreach Experience Manager.
  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.

    In Eclipse Mars you may also need to manually override the default values for the groupId, artifactId, version and projectName properties in the list under Properties available from archetype. This appears to be a bug in Maven Integration for Eclipse.
  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 8 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/tomcat8x 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 jar (e.g. myhippoproject-repository-data-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 v8.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 v8.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-8.5.43/logs/derby.log”
      -Dlog4j.configuration=file:/Users/hippo/workspace/myhippoproject/conf/log4j-dev.xml
      -Dproject.basedir=/Users/hippo/workspace/myhippoproject
      -Drepo.path=/Users/hippo/workspace/myhippoproject/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. myhippoproject-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. myhippoproject-repository-data-development) and click on Finish.
    6. Click OK.
  4. 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. myhippoproject-repository-data-webfiles) and select Properties.
    2. Select Deployment Assembly.
    3. There should be two entries: src/main/java and src/main/resources. Remove both entries so the list is empty.
    4. Click OK.
  5. To run your Bloomreach Experience Manager project on the Tomcat server click on the Run icon in the Servers view.
  6. To debug your Bloomreach Experience Manager project on the Tomcat server click on the Debug icon in the Servers view.
Running your Bloomreach Experience Manager project this way enables all IDE features including automatic compilation and redeployment of your code!
The above instructions are based on 'Tutorial: setup Eclipse workspace for Hippo CMS' by Bart Vreeken.

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 site module, e.g. myhippoproject-site.
  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.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?