= Using Eclipse

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
:page-partial:

If you are an http://www.eclipse.org[Eclipse] user, then we recommend you download the "Eclipse JEE package" configuration.



//== Editor Templates
//
//We provide a set of editor templates.
//These are used to add new methods to existing classes.
//(These are equivalent to the xref:setupguide:intellij:about.adoc#live-templates[IntelliJ live templates]):
//
//* `is` (Apache Isis domain objects).  link:./resources/eclipse/isis-templates.xml[Download]
//* `ju` (for JUnit tests) link:./resources/eclipse/junit4-templates.xml[Download]
//* `jm` (for JMock mocks or libraries) link:./resources/eclipse/jmock2-templates.xml[Download]
//
//
//To install, download each XML file, then go to `Windows > Preferences > Java > Editor > Templates` and choose `Import`.

== Install the DataNucleus plugin

When running an Apache Isis application, it's necessary to setup the development environment so that the Java bytecode can be enhanced by the link:http://www.datanucleus.org[DataNucleus] enhancer.

If using Eclipse, then JDO enhancement is most easily done by installing the http://www.datanucleus.org/products/accessplatform/jpa/tools.html#eclipse[DataNucleus' Eclipse plugin].
This hooks the bytecode enhancement of your domain objects into Eclipse's normal incremental compilation.

This plugin needs to be configured for each of your domain modules (usually just one in any given app).

The DataNucleus plugin hooks into the Eclipse compiler and will automatically enhance the compiled class files:

* Use Help > Install New Software:

+
image::2017-oxygen/030-datanucleus-install-new-software.png[width="600px"]

* Specify the DataNucleus plugin repository:

+
image::2017-oxygen/040-datanucleus-specify-repository.png[width="400px"]

* Select the plugin

+
image::2017-oxygen/050-datanucleus-select-plugin.png[width="600px"]

* Press Next and Finish to complete the installation of the plugin

Then restart Eclipse


== Install Project Lombok

The xref:docs:starters:simpleapp.adoc[SimpleApp] starter app uses link:http://projectlombok.org[Project Lombok] annotations (`@Getter` and `@Setter` and so on) to reduce the boilerplate.
For Eclipse IDE this requires an link:https://projectlombok.org/setup/eclipse[installation step]:

* Locate the `lombok.jar` jar file:

+
image::2017-oxygen/010-lombok-locate-jar.png[width="600px"]

* Run using `java -jar` (or double click on Windows):

+
image::2017-oxygen/020-lombok-install-into-eclipse.png[width="600px"]

Then restart Eclipse.

== Importing the Project

Use File > Import, then Maven > Existing Maven Projects.

However, you will have some compile errors until you enable annotation processing, discussed below.

[#enable-annotation-processing]
=== Enable Annotation Processing

Both DataNucleus and Project Lombok use annotation processors that must be enabled in Eclipse.

For each project, open its _Properties_ page and then _Java Compiler > Annotation Processing_ to specify the generated source directory of `target/generated-sources/annotations`:

image::2017-oxygen/060-enable-annotation-processor.png[width="600px"]

If your eclipse version also requires you to enter a generated test source directory, specify the following directory: `target/generated-test-sources/test-annotations`.

Then under _Java Compiler > Annotation Processing > Factory Path_ add the following external JARs (for instance from your local `.m2` maven repository)

* `datanucleus-jdo-query-5.0.9.jar` (under `.m2/repository/org/datanucleus/datanucleus-jdo-query/5.0.9`)
* `javax.jdo-3.2.0-m13.jar` (under `.m2/repository/org/datanucleus/javax.jdo/3.2.0-m13`)

The specific versions depend on the DataNucleus version used in your project.You can easily check this in the Dependency Hierarchy tab of the POM.xml viewer in eclipse.

Eclipse should automatically add these directories as a source path; at this point all remaining compiler errors should disappear.

If the JDO Q-files are not generated automatically into the specified source directory then check the `.log` file in your eclipse workspace to see if there are any `ClassNotFoundException`s that could indicate why the DataNucleus annotation processor is failing.

A healthy DataNucleus Annotation Process execution in your eclipse `.log` file should look like this:

[source]
----
!ENTRY org.eclipse.jdt.apt.pluggable.core 1 1 2020-11-06 19:28:41.948
!MESSAGE DataNucleus JDO AnnotationProcessor for generating JDOQLTypedQuery Q classes
----

An error might look like this:

[source]
----
!ENTRY org.eclipse.jdt.apt.pluggable.core 4 1 2020-11-06 18:52:30.688
!MESSAGE Exception thrown by Java annotation processor org.datanucleus.jdo.query.JDOQueryProcessor@60e3ac5d
!STACK 0
java.lang.Exception: java.lang.NoClassDefFoundError: javax/jdo/query/PersistableExpression
----

If you see this specific error message then check that you added the `javax.jdo` JAR that matches the version of DataNucleus used in your project (see _Factory Path_ configuration above).



== JPA: Configure Eclipselink Weaving

CAUTION: TODO - to document

== JDO: Configure DataNucleus Enhancer

[TIP]
====
Make sure you are in the 'Java' Perspective, not the 'Java EE' Perspective.
====

In Eclipse, for the _domain object model_ project(s), first add DataNucleus support:

image::eclipse-100-project-support.png[width="600px"]


Then turn on Auto-Enhancement:

image::eclipse-110-project-support.png[width="600px"]

=== Update the classpath

DataNucleus' enhancer uses the domain object model's own classpath to reference DataNucleus JARs.
So, even though your domain objects are unlikely to depend on DataNucleus, these references must still be present.

If you've based your app on either the xref:docs:starters:helloworld.adoc[HelloWorld] or the xref:docs:starters:simpleapp.adoc[SimpleApp] starter app, then it'll be set up already.

Then, tell DataNucleus to use the project classpath:

image::eclipse-010-windows-preferences.png[width="750px"]

When the enhancer runs, it will print out to the console:

image::eclipse-120-console.png[width="500px"]

[#workaround-for-path-limits-the-dn-plugin-to-use-the-persistence-xml]
=== Workaround for path limits (the DN plugin to use the persistence.xml)

If running on Windows then the DataNucleus plugin is very likely to hit the Windows path limit.

To fix this, we configure the enhancer to read from the `persistence.xml` file.

As a prerequisite, first make sure that your domain object model has a `persistence.xml` file.
Then specify the `persistence-unit` in the project properties:

image::eclipse-025-project-properties.png[width="750px"]

=== Workaround: If the enhancer fails

On occasion it appears that Eclipse can attempt to run two instances of the DataNucleus enhancer.
This is probably due to multiple Eclipse builders being defined; we've noticed multiple entries in the Eclipse's `Debug` view:


image::eclipse-210-enhancer-fails-duplicates.png[width="600px"]


At any rate, you'll know you've encountered this error if you see the following in the console:


image::eclipse-200-enhancer-fails-duplicates.png[width="600px"]



The best solution is to remove DataNucleus support and then to re-add it:


image::eclipse-220-enhancer-fails-duplicates.png[width="600px"]


If you consistently hit problems, then the final recourse is to disable the automatic enhancement and to remember to manually enhance your domain object model before each run.

Not ideal, we know.
Please feel free to contribute a better solution :-)

[#running-the-app]
== Running the App

Create a launch configuration that runs the main class annotated with link:https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/autoconfigure/SpringBootApplication.html[@SpringBootApplication].


== Other domain projects.

There is nothing to prevent you having multiple domain projects.
You might want to do such that each domain project corresponds to a http://www.methodsandtools.com/archive/archive.php?id=97p2[DDD module], thus guaranteeing that there are no cyclic dependencies between your modules.

If you do this, make sure that each project has its own `persistence.xml` file.
And, remember also to configure Eclipse's DataNucleus plugin for these other domain projects.

//== Advanced
//
//In this section are a couple of options that will reduce the length of the change code/build/deploy/review feedback loop.
//
//=== Setting up DCEVM
//
//link:http://github.com/dcevm/dcevm[DCEVM] enhances the JVM with true hot-swap adding/removing of methods as well as more reliable hot swapping of the implementation of existing methods.
//
//In the context of Apache Isis, this is very useful for contributed actions and mixins and also view models; you should then be able to write these actions and have them be picked up without restarting the application.
//
//Changing persisting domain entities is more problematic, for two reasons: the JDO/DataNucleus enhancer needs to run on domain entities, and also at runtime JDO/DataNucleus would need to rebuild its own metamodel.
//You may find that adding actions will work, but adding new properties or collections is much less likely to.
//
//For details of setting up DCEVM, see the xref:setupguide:intellij:hints-and-tips.adoc#setting-up-dcevm[corresponding section] in the IntelliJ documentation.

