Skip to content

Better docs #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 15 commits into
base: master
Choose a base branch
from
Open

Better docs #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
0f559dd
Bumped dependency versions
iSnow Jun 11, 2020
2b8d265
Jitpack link
iSnow Jun 11, 2020
86c422b
Jitpack link
iSnow Jun 11, 2020
1841dda
Jitpack link
iSnow Jun 11, 2020
9889d0c
Moved the processing over from processing test-persistence.xml to pro…
iSnow Jun 11, 2020
d0eeca4
Moved the processing over from processing test-persistence.xml to pro…
iSnow Jun 11, 2020
f91342a
docs
iSnow Jun 11, 2020
f0a2794
docs
iSnow Jun 11, 2020
e2d052b
docs
iSnow Jun 11, 2020
98c15ab
docs
iSnow Jun 12, 2020
e7ff062
Update README.md
iSnow Oct 5, 2020
7d6cbfc
Update README.md
iSnow Oct 5, 2020
f399b31
Update README.md
iSnow Oct 5, 2020
c96f969
Update README.md
iSnow Oct 5, 2020
ecf24f0
Update README.md
iSnow Oct 5, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 81 additions & 36 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,62 @@
jpa-maven-plugin
================

This project houses a [Maven plugin][1] for performing various tasks
to help with JPA-based projects.
[![Jitpack Snapshots](https://jitpack.io/v/iSnow/jpa-maven-plugin.svg)](https://jitpack.io/#iSnow/jpa-maven-plugin)

This project houses a [Maven plugin][1] for auto-discovering JPA-annotated entity classes from libraries. The
primary use-case is developers who factor out model classes into a library and need JPA providers like Eclipselink
to see them. Spring developers do not need this plugin, neither do Hibernate developers.

If you use this from IntelliJ, you need to add a Maven goal `mvn package` to the "before launch" section
of your run configuration.

## TODO
- two or more persistance units

## Quick Start

Create a `persistence.xml` to be used for unit testing in
`src/test/resources/META-INF`:
### From Jitpack

To use it from Jitpack, you need to add Jitpack as a repository location to your pom.xml:

<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>

Look up the latest commit hash on [Jitpack](https://jitpack.io/#iSnow/jpa-maven-plugin) and include it in your pom.xml (replacing 7d6cbfc42f with the actual hash):

<plugin>
<groupId>com.github.iSnow</groupId>
<artifactId>jpa-maven-plugin</artifactId>
<version>7d6cbfc42fT</version>
<executions>
<execution>
<id>Generate entityClassnames.properties</id>
<goals>
<goal>list-entity-classnames</goal>
</goals>
</execution>
</executions>
</plugin>

### Compile and install the plugin

The plugin is not on central, so if you don't want to use Jitpack, you must build it yourself. To build and use it locally, type `mvn install` in the terminal.
The plugin will be installed into your .m2/repository and be available for local builds. CI pipelines will not like this.

### Use in projects

You should have a `persistence.xml` to be used for in
`src/main/resources/META-INF`:

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.0"
xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
<persistence-unit name="test-Hibernate" transaction-type="RESOURCE_LOCAL">
<persistence-unit name="hibernate" transaction-type="RESOURCE_LOCAL">

<!-- This provider is just an example. -->
<provider>org.hibernate.ejb.HibernatePersistence</provider>
Expand All @@ -23,12 +66,12 @@ Create a `persistence.xml` to be used for unit testing in

<properties>
<property name="javax.persistence.jdbc.driver" value="TODO: JDBC driver class name goes here" />
<property name="javax.persistence.jdbc.url" value="TODO: JDBC connection URL for unit tests goes here" />
<property name="javax.persistence.jdbc.user" value="TODO: unit test database user goes here" />
<property name="javax.persistence.jdbc.password" value="TODO: unit test database password goes here" />
<property name="javax.persistence.jdbc.url" value="TODO: JDBC connection URL goes here" />
<property name="javax.persistence.jdbc.user" value="TODO: database user goes here" />
<property name="javax.persistence.jdbc.password" value="TODO: database password goes here" />

<!-- You may of course put any properties you want here -->
<property name="hibernate.default_schema" value="TODO: default test schema goes here" />
<property name="hibernate.default_schema" value="TODO: default schema goes here" />
<property name="hibernate.id.new_generator_mappings" value="true"/>
<property name="hibernate.show_sql" value="true" />
<property name="hibernate.format_sql" value="true" />
Expand All @@ -39,33 +82,35 @@ Create a `persistence.xml` to be used for unit testing in
Ensure that it does _not_ get copied during resource copying. Add
this in your `pom.xml`'s `<build>` section:

<testResources>
<testResource>
<directory>src/test/resources</directory>
<resources>
<resources>
<directory>src/resources</directory>
<excludes>
<exclude>META-INF/persistence.xml</exclude>
</excludes>
<!-- Whether you want to filter the other test resources is up to you -->
<!-- Whether you want to filter the other resources is up to you -->
<filtering>true</filtering>
</testResource>
</testResources>
</resources>
</resources>

Now set up the `jpa-maven-plugin`. Place this in your `pom.xml`'s
`<build>`'s `<plugins>` section:

<plugin>
<groupId>com.edugility</groupId>
<artifactId>jpa-maven-plugin</artifactId>
<version>1.1-SNAPSHOT</version>
<executions>
<execution>
<id>Generate entityClassnames.properties</id>
<goals>
<goal>list-entity-classnames</goal>
</goals>
</execution>
</executions>
</plugin>
```
<plugin>
<groupId>com.github.iSnow</groupId>
<artifactId>jpa-maven-plugin</artifactId>
<version>4-SNAPSHOT</version>
<executions>
<execution>
<id>Generate entityClassnames.properties</id>
<goals>
<goal>list-entity-classnames</goal>
</goals>
</execution>
</executions>
</plugin>
```

Finally, make sure that the `persistence.xml` is copied over, but only
after the `jpa-maven-plugin` has run. Place this **IMMEDIATELY
Expand All @@ -77,19 +122,19 @@ BELOW** the plugin stanza listed above:
<executions>
<execution>
<id>Copy persistence.xml filtered with generated entityClassnames.properties file</id>
<phase>process-test-classes</phase>
<phase>process-classes</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<filters>
<filter>${project.build.directory}/generated-test-sources/jpa-maven-plugin/entityClassnames.properties</filter>
<filter>${project.build.directory}/generated-sources/jpa-maven-plugin/entityClassnames.properties</filter>
</filters>
<outputDirectory>${project.build.testOutputDirectory}/META-INF</outputDirectory>
<outputDirectory>${project.build.outputDirectory}/META-INF</outputDirectory>
<resources>
<resource>
<filtering>true</filtering>
<directory>src/test/resources/META-INF</directory>
<directory>src/main/resources/META-INF</directory>
<includes>
<include>persistence.xml</include>
</includes>
Expand All @@ -100,12 +145,12 @@ BELOW** the plugin stanza listed above:
</executions>
</plugin>

Run `mvn clean process-test-classes` if you just want to see the
effects of the `jpa-maven-plugin`. Look in your
`target/test-classes/META-INF` directory. You will see a
Run `mvn clean process-classes` if you just want to see the
effects of the `jpa-maven-plugin` or `mvn clean package` to use it in your build. Look in your
`target/classes/META-INF` directory. You will see a
`persistence.xml` file with all of your entity and mapped superclass
and embeddables and id classes listed. Any Maven lifecycle phases
that occur before `process-test-classes` will not be able to use the
that occur before `process-classes` will not be able to use the
effects of the `jpa-maven-plugin`.

## More Information
Expand Down
21 changes: 11 additions & 10 deletions pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@
<maven>3.0.4</maven>
</prerequisites>

<groupId>com.edugility</groupId>
<groupId>com.github.iSnow</groupId>
<artifactId>jpa-maven-plugin</artifactId>
<version>3-SNAPSHOT</version>
<version>4-SNAPSHOT</version>
<packaging>maven-plugin</packaging>

<parent>
Expand Down Expand Up @@ -92,7 +92,7 @@
</dependency>

<dependency>
<groupId>net.sf.scannotation</groupId>
<groupId>org.scannotation</groupId>
<artifactId>scannotation</artifactId>
<version>${scannotationVersion}</version>
<exclusions>
Expand All @@ -106,7 +106,7 @@
<dependency>
<groupId>org.javassist</groupId>
<artifactId>javassist</artifactId>
<version>3.18.2-GA</version>
<version>${javassistVersion}</version>
</dependency>

</dependencies>
Expand Down Expand Up @@ -134,7 +134,7 @@
</dependency>

<dependency>
<groupId>net.sf.scannotation</groupId>
<groupId>org.scannotation</groupId>
<artifactId>scannotation</artifactId>
</dependency>

Expand Down Expand Up @@ -358,8 +358,8 @@

<!-- Versions -->
<findbugsMavenPluginVersion>2.5.2</findbugsMavenPluginVersion>
<javaxPersistenceVersion>2.0.5</javaxPersistenceVersion>
<junitVersion>4.11</junitVersion>
<javaxPersistenceVersion>2.2.1</javaxPersistenceVersion>
<junitVersion>4.13</junitVersion>
<mavenAssemblyPluginVersion>2.4</mavenAssemblyPluginVersion>
<mavenCleanPluginVersion>2.5</mavenCleanPluginVersion>
<mavenCompilerPluginVersion>3.0</mavenCompilerPluginVersion>
Expand All @@ -381,15 +381,16 @@
<mavenSitePluginVersion>3.2</mavenSitePluginVersion>
<mavenSourcePluginVersion>2.2.1</mavenSourcePluginVersion>
<mavenSurefirePluginVersion>2.13</mavenSurefirePluginVersion>
<scannotationVersion>1.0.2</scannotationVersion>
<scannotationVersion>1.0.3</scannotationVersion>
<javassistVersion>3.27.0-GA</javassistVersion>
<siteMavenPluginVersion>0.9</siteMavenPluginVersion>
<versionsMavenPluginVersion>2.0</versionsMavenPluginVersion>

<!-- maven-compiler-plugin properties -->
<maven.compiler.showDeprecation>true</maven.compiler.showDeprecation>
<maven.compiler.showWarnings>true</maven.compiler.showWarnings>
<maven.compiler.source>1.6</maven.compiler.source>
<maven.compiler.target>1.6</maven.compiler.target>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
<maven.compiler.verbose>false</maven.compiler.verbose>

<!-- maven-javadoc-plugin properties -->
Expand Down
Loading