Documentation / Setup / Enhancement
Videos
Recommendation
Use both IDE plugin enhancement (Idea or Eclipse) plus build time enhancement.
For IntelliJ IDEA and Eclipse users my recommendation is to use the IDE plugin in addition to either build time enhancement (maven plugin) or agent.
That is, the IDE plugin is good to use during development enhancing the beans as the IDE compiles the classes. Using the IDE plugin can reduce enhancement hassles during development and unit testing. For production you can then choose between build time enhancement via say maven or run time enhancement via javaagent.
Overview
The term "Enhancement" covers all the ways (javaagent, ant, maven,IDE plugin, etc) that are used to modify the entity beans. Others terms used to describe enhancement include "Weaving", "Transformation" and "byte code manipulation".
Load time weaving is used to refer to when the class manipulation occurs at "load time" typically via javaagent compared with class manipulation occurring at "build time" typically via Maven, Ant or IDE plugin.
In raw terms a class is a byte[] and enhancement is manipulating those bytes prior to the class being defined by its ClassLoader.
Using multiple enhancers
Ebean enhancement is aware of when the enhancement has already occurred. In this way it is common and expected that multiple forms of enhancement can be used at the same time such as using both an IDE plugin and maven plugin to perform the enhancement.
Maven enhancement
A Maven plugin performs the enhancement as part of the maven compile process. This can be described as "build time enhancement".
Maven enhancement tile
Ebean supplies a maven tile that brings in both the enhancer for entity beans as well as the enhancement for query beans. This is simpler, cleaner less verbose than defining the plugin in the traditional (non-tile) fashion and now the preferred approach.
The ebean enhancement tile brings plugin configuration for:
- Entity bean and @Transactional enhancement for main and test
- Query bean enhancement for main and test
- ebean-codegen plugin, helper to generate finders etc
ebean enhancement tile
<plugin>
<groupId>io.repaint.maven</groupId>
<artifactId>tiles-maven-plugin</artifactId>
<version>2.40</version>
<extensions>true</extensions>
<configuration>
<tiles>
<!-- other tiles ... -->
<tile>io.ebean.tile:enhancement:14.1.0</tile>
</tiles>
</configuration>
</plugin>
Use mvn help:effective-pom
to view the plugins that the tile brings in.
Maven plugin
If you do not want to use maven tiles you can specify the maven enhancement plugin in 'normal' fashion. Note the unlike the tile this does not bring in the query bean enhancement.
<plugin>
<groupId>io.ebean</groupId>
<artifactId>ebean-maven-plugin</artifactId>
<version>${version}</version>
<executions>
<execution>
<id>main</id>
<phase>process-classes</phase>
<configuration>
<transformArgs>debug=1</transformArgs>
</configuration>
<goals>
<goal>enhance</goal>
</goals>
</execution>
</executions>
</plugin>
Agent
You can use javaagent
parameter on the command line as per the examples below.
This is often described as "Runtime enhancement" or "Load time enhancement".
Note that since version 4.7.1 of ebean-agent is expected that the agent will perform well without specifying the packages to enhance. That is, the agent is pretty good at ignoring non-interesting classes (JDK, groovy, scala, kotlin, jdbc drivers and many common libraries from apache, google, testing etc.
java -javaagent:ebean-agent-${version}.jar MyApplication
java -javaagent:ebean-agent-${version}.jar=debug=3 MyApplication
The ebean-agent jar can be downloaded from maven. The current version is:
<dependency>
<groupId>${groupid}</groupId>
<artifactId>${artifactid}</artifactId>
<version>${version_str}</version>
</dependency>
<dependency org="${groupid}" name="${artifactid}" rev="${version_str}"/>
@Grapes(
@Grab(group='${groupid}', module='${artifactid}', version='${version_str}')
)
'${groupid}:${artifactid}:${version_str}'
'${groupid}:${artifactid}:${version_str}'
libraryDependencies += "${groupid}" % "${artifactid}" % "${version_str}"
[${groupid}/${artifactid} "${version_str}"]
Agent Loader
The agent loader can be used to programmatically load the javaagent onto a running JVM. However, this very occasionally does not enhance a bean as an entity bean class somehow gets loaded prior to the agent being loaded on the JVM and for this reason this is not a recommended approach.
Note that this approach is used in the testing code for Ebean itself and if you use this approach you need to make sure the agent loading occurs before any class loading of entity beans or transactional beans occurs.
<dependency>
<groupId>${groupid}</groupId>
<artifactId>${artifactid}</artifactId>
<version>${version_str}</version>
</dependency>
<dependency org="${groupid}" name="${artifactid}" rev="${version_str}"/>
@Grapes(
@Grab(group='${groupid}', module='${artifactid}', version='${version_str}')
)
'${groupid}:${artifactid}:${version_str}'
'${groupid}:${artifactid}:${version_str}'
libraryDependencies += "${groupid}" % "${artifactid}" % "${version_str}"
[${groupid}/${artifactid} "${version_str}"]
The code below loads the enhancer agent programmatically onto the running JVM.
import org.avaje.agentloader;
...
public void someApplicationBootupMethod() {
// Load the agent into the running JVM process
if (!AgentLoader.loadAgentFromClasspath("ebean-agent","debug=1;packages=org.example.model")) {
logger.info("ebean-agent not found in classpath - not dynamically loaded");
}
}
Ant enhancement
Modify your ant build.xml file to:
- Define the AntEnhanceTask.
- Create a target that uses the AntEnhanceTask to enhance the entity classes.
<taskdef
name="ebeanEnhance"
classname="io.ebean.enhance.ant.AntEnhanceTask"
classpath="your_path_to/ebean-x.x.x.jar"/>
<target name="ormEnhance" depends="clean,compile">
<!--
classSource: This is the directory that contains your class files. That is, the directory where your IDE will compile your java class files to, or the directory where a previous ant task will compile your java class files to.
packages: a comma delimited list of packages that contain entity classes. All the classes in these packages are searched for entity classes to be enhanced. transformArgs: This contains a debug level (0 - 10) .
-->
<ebeanEnhance
classSource="your_classes_directory"
packages="app.domain.*"
transformArgs="debug=1"/>
</target>