IDE Configuration

Achilles is using Annotation Processor to generate source-code at compile time by hooking into the compilation lifecycle of the Java compiler.

Therefore, in order to use Achilles, you must configure carefully your IDE.

Because of the very minimalist support for annotation processors in Eclipse, it is recommended to use IntelliJ but Achilles can work with Eclipse too, providing some extensive configuration (see below)

Configuration for IntelliJ

In IntelliJ IDE, first go to the Preferences menu

Go to Build, Execution, Deployment menu, expand Compiler and go to Annotation Processors

Select your project in the list on the right pane, select Enable annotation processing, choose Obtain processors from project classpath, choose Module content root and set the following values for the directory:

• Production sources directory: target/generated-sources/annotations
• Test sources directory: target/generated-test-sources/test-annotations

Next, right-click on your project and select "Open Module Settings". In the "Module" section, remove the exclusion for target folder:

Then, select target/generated-sources/annotations and mark it as source folder. Do not forget to exclude the other sub-folders in the target directory

It's done. Now, every time you modify your entity mapping (add a new column, update an annotation, change some types ...), you must trigger a manual rebuild of the project so that Achilles can re-generate the updated meta classes.

Configuration for Eclipse

Before configuring your Eclipse, you should ensure first that you have the achilles-core-<version>-shaded.jar in your Maven repository. For this:

• Edit your pom.xml and replace

	<dependency>
		<groupId>info.archinnov</groupId>
		<artifactId>achilles-core</artifactId>
		<version>${achilles.version}</version>
	</dependency>

by

	<dependency>
		<groupId>info.archinnov</groupId>
		<artifactId>achilles-core</artifactId>
		<version>${achilles.version}</version>
		<classifier>shaded</classifier>
	</dependency>

Note that we added the <classifier>shaded</classifier>

• Then open a shell terminal, go to your project root folder and execute mvn dependency:resolve

• Edit your pom.xml again and remove the line <classifier>shaded</classifier> to get back to

	<dependency>
		<groupId>info.archinnov</groupId>
		<artifactId>achilles-core</artifactId>
		<version>${achilles.version}</version>
	</dependency>

The configuration for Eclipse requires more manual configuration because there is no support for automatic annotation processor detection from classpath, contrary to IntelliJ.

First, right click on your project and select Properties

Expand the Java Compiler menu, go to Annotation Processing and select Enable project specific settings, Enable annotation processing (and optionally Enable processing in editor).

In the Generated source directory, put target/generated-sources/annotations

Eclipse will add a new source folder target/generated-sources/annotations to your project source layout. Then, expand the Annotation Processing menu and click on Factory Path. There you should click on the button Add Variable ...

Select the M2_REPO variable and click on the button Extend...

Navigate in the Maven repository folder until you find info/archinnov/achilles-core/<version>/achilles-core-<version>-shaded.jar and select it.

It is important to select the shaded jar and not the normal jar. In the example, the version is achilles-core-4.0.1-shaded.jar but you should of course select the correct version that matches the Achilles version in your pom.xml

Back to the Factory Path menu, click on the Advanced... button

Ensure that you can see info.archinnov.achilles.internals.apt.processors.AchillesProcessor in the popup

Validate the changes by clicking on Apply. If prompted to rebuild the project, select Yes

Once the project is rebuilt, you should see new generated classes in the target/generated-sources/annotations folder

Annotation processor debug messages & issues during compilation

All info/error messages of the Achilles processor are displayed in the output console/compilation output console

With IntelliJ, processor messages are displayed in the `Messages window:

With Eclipse, processor messages are displayed in the Error Log window:

In some cases, if the processor does not generate the code correctly, you may need to do a clean build with Maven (this is actually the only method that is working 100% in any case). For this open a shell terminal and type mvn clean compile then go back to the IDE and refresh your project, you should see the generated code.

Sometimes if you're making a mistake with the annotations on the entities or your annotations are violating some rules enforced by Achilles, you'll see an explicit compilation error message in the output console/compilation output console.

For example, if you're creating an User entity without any @PartitionKey, the annotation processor will issue an explicit error message:

@Table(keyspace = KEYSPACE, table = USERS)
public class UserEntity {

    //@PartitionKey  ---> ERROR BECAUSE NO PARTITION KEY DEFINED ON THE ENTITY
    private String login;

    @NotEmpty
    @Column
    private String pass;

    @Column
    private String firstname;

    @Column
    private String lastname;
    
    ...
}    

With IntelliJ:

With Eclipse:

Please note that if there is an error with your entity annotations, the processor will stop generating classes so that you'll get a lot of compilation errors because some infrastructure classes like info.archinnov.achilles.generated.ManagerFactory, info.archinnov.achilles.generated.ManagerFactoryBuilder or all the info.archinnov.achilles.generated.manager.XXX_Manager classes are note generated. This is a normal behavior.

After you fix the annotation issue, just rebuild the project and everything should be fine.