ISPN-4119 Move JPA Cache Store back into main repository

documentation/src/main/asciidoc/user_guide/chapter-23_2-JPA_Persistence.adoc

@@ -0,0 +1,169 @@
+= JPA Cache Store
+The Infinispan Community
+:icons: font
+
+== Introduction
+The implementation depends on JPA 2.0 specification to access entity meta model.
+
+In normal use cases, it's recommended to leverage Infinispan for JPA second level cache and/or query cache.
+However, if you'd like to use only Infinispan API and you want Infinispan to persist into a cache store using a common format (e.g., a database with well defined schema), then JPA Cache Store could be right for you.
+
+.Things to note
+* When using JPA Cache Store, the key should be the ID of the entity, while the value should be the entity object.
+* Only a single `@Id` or `@EmbeddedId` annotated property is allowed.
+* Auto-generated ID is not supported.
+* Lastly, all entries will be stored as immortal entries.
+
+=== Sample Usage
+For example, given a persistence unit "myPersistenceUnit", and a JPA entity User:
+
+.persistence.xml
+[source,xml]
+----
+
+<persistence-unit name="myPersistenceUnit">
+	...
+</persistence-unit>
+
+----
+
+User entity class
+
+.User.java
+[source,java]
+----
+
+@Entity
+public class User implements Serializable {
+	@Id
+	private String username;
+	private String firstName;
+	private String lastName;
+
+	...
+}
+
+----
+
+Then you can configure a cache "usersCache" to use JPA Cache Store, so that when you put data into the cache, the data would be persisted into the database based on JPA configuration.
+
+[source,java]
+----
+
+EmbeddedCacheManager cacheManager = ...;
+
+
+Configuration cacheConfig = new ConfigurationBuilder().loaders()
+				.addLoader(JpaCacheStoreConfigurationBuilder.class)
+				.persistenceUnitName("myPersistenceUnit")
+				.entityClass(User.class)
+				.build();
+cacheManager.defineCache("usersCache", cacheConfig);
+
+Cache<String, User> usersCache = cacheManager.getCache("usersCache");
+usersCache.put("raytsang", new User(...));
+
+----
+
+Normally a single Infinispan cache can store multiple types of key/value pairs, for example:
+
+[source,java]
+----
+
+Cache<String, User> usersCache = cacheManager.getCache("myCache");
+usersCache.put("raytsang", new User());
+Cache<Integer, Teacher> teachersCache = cacheManager.getCache("myCache");
+teachersCache.put(1, new Teacher());
+
+----
+
+It's important to note that, when a cache is configured to use a JPA Cache Store, that cache would only be able to store ONE type of data.
+
+[source,java]
+----
+
+Cache<String, User> usersCache = cacheManager.getCache("myJPACache"); // configured for User entity class
+usersCache.put("raytsang", new User());
+Cache<Integer, Teacher> teachersCache = cacheManager.getCache("myJPACache"); // cannot do this when this cache is configured to use a JPA cache store
+teachersCache.put(1, new Teacher());
+
+----
+
+Use of `@EmbeddedId` is supported so that you can also use composite keys.
+
+[source,java]
+----
+
+@Entity
+public class Vehicle implements Serializable {
+	@EmbeddedId
+	private VehicleId id;
+	private String color;	...
+}
+
+@Embeddable
+public class VehicleId implements Serializable
+{
+	private String state;
+	private String licensePlate;
+	...
+}
+
+----
+
+Lastly, auto-generated IDs (e.g., `@GeneratedValue`) is not supported.
+When putting things into the cache with a JPA cache store, the key should be the ID value!
+
+== Configuration
+=== Sample Programatic Configuration
+
+[source,java]
+----
+
+Configuration cacheConfig = new ConfigurationBuilder().loaders()
+				.addLoader(JpaCacheStoreConfigurationBuilder.class)
+				.persistenceUnitName("org.infinispan.loaders.jpa.configurationTest")
+				.entityClass(User.class)
+				.build();
+
+----
+
+[options="header"]
+|===============
+|Parameter|Description
+|persistenceUnitName| JPA persistence unit name in JPA configuration (persistence.xml) that contains the JPA entity class 
+|entityClass| JPA entity class that is expected to be stored in this cache.  Only one class is allowed. 
+|===============
+
+=== Sample XML Configuration
+
+[source,xml]
+----
+
+<namedCache name="vehicleCache">
+	<loaders passivation="false" shared="true" preload="true">
+		<jpaStore 
+			persistenceUnitName="org.infinispan.loaders.jpa.configurationTest"
+			entityClassName="org.infinispan.loaders.jpa.entity.User"
+		/>
+	</loaders>
+</namedCache>
+
+----
+
+[options="header"]
+|===============
+|Parameter|Description
+|persistenceUnitName| JPA persistence unit name in JPA configuration (persistence.xml) that contains the JPA entity class 
+|entityClassName|Fully qualified JPA entity class name that is expected to be stored in this cache.  Only one class is allowed.
+
+|===============
+
+== Additional References
+Refer to the link:$$https://github.com/infinispan/infinispan-cachestore-jpa/tree/master/src/test/java/org/infinispan/loaders/jpa/config/ConfigurationTest.java$$[test case] for code samples in action. 
+
+Refer to link:$$https://github.com/infinispan/infinispan-cachestore-jpa/tree/master/src/test/resources/config/jpa-config-53.xml$$[test configurations] for configuration samples. 
+
+== Javadoc
+
+*TODO* 

documentation/src/main/asciidoc/user_guide/user_guide.adoc

@@ -24,6 +24,7 @@ include::chapter-43-Eviction.adoc[]
 include::chapter-23-Persistence.adoc[]
 include::chapter-23_0-LevelDB_Persistence.adoc[]
 include::chapter-23_1-REST_Persistence.adoc[]
+include::chapter-23_2-JPA_Persistence.adoc[]
 include::chapter-26-Infinispan_transactions.adoc[]
 include::chapter-19-Locking_and_Concurrency.adoc[]
 include::chapter-32-Clustering_modes.adoc[]

parent/pom.xml

@@ -111,13 +111,14 @@
       <version.guava>11.0.2</version.guava>
       <version.h2.driver>1.3.166</version.h2.driver>
       <version.hibernate.annotations>3.5.6-Final</version.hibernate.annotations>
+      <version.hibernate.core>4.2.2.Final</version.hibernate.core>
+      <version.hibernate.entitymanager>${version.hibernate.core}</version.hibernate.entitymanager>
       <version.hibernate.hql.parser>1.0.0.Alpha6</version.hibernate.hql.parser>
       <version.hibernate.javax.persistence>1.0.1.Final</version.hibernate.javax.persistence>
       <version.httpclient>4.2.4</version.httpclient>
       <version.jackson>1.9.2</version.jackson>
       <version.javax.cache>1.0.0-PFD</version.javax.cache>
       <version.javax.cache.cache-tests>0.11</version.javax.cache.cache-tests>
-      <version.javax.persistence>1.0</version.javax.persistence>
       <version.javax.servlet>2.5</version.javax.servlet>
       <version.jbossjta>4.17.13.Final</version.jbossjta>
       <version.jboss.logging.processor>1.1.0.Final</version.jboss.logging.processor>
@@ -381,11 +382,6 @@
             <artifactId>cdi-api</artifactId>
             <version>${version.cdi}</version>
          </dependency>
-         <dependency>
-            <groupId>javax.persistence</groupId>
-            <artifactId>persistence-api</artifactId>
-            <version>${version.javax.persistence}</version>
-         </dependency>
          <dependency>
             <groupId>javax.servlet</groupId>
             <artifactId>jstl</artifactId>
@@ -471,6 +467,16 @@
             <artifactId>hibernate-annotations</artifactId>
             <version>${version.hibernate.annotations}</version>
          </dependency>
+         <dependency>
+            <groupId>org.hibernate</groupId>
+            <artifactId>hibernate-entitymanager</artifactId>
+            <version>${version.hibernate.entitymanager}</version>
+         </dependency>
+         <dependency>
+            <groupId>org.hibernate.javax.persistence</groupId>
+            <artifactId>hibernate-jpa-2.0-api</artifactId>
+            <version>${version.hibernate.javax.persistence}</version>
+         </dependency>
          <dependency>
             <groupId>org.hibernate.hql</groupId>
             <artifactId>hibernate-hql-parser</artifactId>

persistence/jpa/pom.xml

@@ -0,0 +1,105 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+   <modelVersion>4.0.0</modelVersion>
+   <parent>
+      <groupId>org.infinispan</groupId>
+      <artifactId>infinispan-persistence-parent</artifactId>
+      <version>7.0.0-SNAPSHOT</version>
+      <relativePath>../pom.xml</relativePath>
+   </parent>
+
+   <artifactId>infinispan-cachestore-jpa</artifactId>
+   <packaging>bundle</packaging>
+   <name>Infinispan JPA CacheStore</name>
+   <description>Infinispan JPA CacheStore module</description>
+
+   <properties>
+      <!-- Tests against single database cannot be executed in paralllel -->
+      <infinispan.test.parallel.threads>1</infinispan.test.parallel.threads>
+   </properties>
+
+   <build>
+      <plugins>
+         <plugin>
+            <groupId>org.apache.felix</groupId>
+            <artifactId>maven-bundle-plugin</artifactId>
+            <configuration>
+               <instructions>
+                  <Export-Package>
+                     ${project.groupId}.persistence.jpa.*;version=${project.version};-split-package:=error
+                  </Export-Package>
+               </instructions>
+            </configuration>
+         </plugin>
+      </plugins>
+   </build>
+   <dependencies>
+      <dependency>
+         <groupId>org.hibernate.javax.persistence</groupId>
+         <artifactId>hibernate-jpa-2.0-api</artifactId>
+         <scope>provided</scope>
+      </dependency>
+      <dependency>
+         <groupId>com.h2database</groupId>
+         <artifactId>h2</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>mysql</groupId>
+         <artifactId>mysql-connector-java</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>org.slf4j</groupId>
+         <artifactId>slf4j-simple</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>org.hibernate</groupId>
+         <artifactId>hibernate-entitymanager</artifactId>
+         <scope>test</scope>
+      </dependency>
+   </dependencies>
+
+   <profiles>
+      <profile>
+         <id>h2</id>
+         <activation>
+            <activeByDefault>true</activeByDefault>
+         </activation>
+         <build>
+            <plugins>
+               <plugin>
+                  <groupId>org.apache.maven.plugins</groupId>
+                  <artifactId>maven-surefire-plugin</artifactId>
+                  <configuration>
+                     <systemPropertyVariables>
+                        <connection.url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection.url>
+                        <driver.class>org.h2.Driver</driver.class>
+                     </systemPropertyVariables>
+                  </configuration>
+               </plugin>
+            </plugins>
+         </build>
+      </profile>
+      <profile>
+         <id>mysql</id>
+         <build>
+            <plugins>
+               <plugin>
+                  <groupId>org.apache.maven.plugins</groupId>
+                  <artifactId>maven-surefire-plugin</artifactId>
+                  <configuration>
+                     <systemPropertyVariables>
+                        <connection.url>jdbc:mysql://localhost:3306/ispn_jpa_test</connection.url>
+                        <driver.class>com.mysql.jdbc.Driver</driver.class>
+                        <db.username>root</db.username>
+                     </systemPropertyVariables>
+                  </configuration>
+               </plugin>
+            </plugins>
+         </build>
+      </profile>
+   </profiles>
+</project>
+

pom.xml

@@ -34,6 +34,7 @@
       <module>lucene/lucene-v3</module>
       <module>persistence</module>
       <module>persistence/jdbc</module>
+      <module>persistence/jpa</module>
       <module>persistence/remote</module>
       <module>persistence/cli</module>
       <module>persistence/leveldb</module>

src/main/resources/assemblies/all.xml

@@ -57,6 +57,7 @@
             <include>org.infinispan:infinispan-cli-client</include>
             <include>org.infinispan:infinispan-cli-server</include>
             <include>org.infinispan:infinispan-cachestore-jdbc</include>
+            <include>org.infinispan:infinispan-cachestore-jpa</include>
             <include>org.infinispan:infinispan-cachestore-remote</include>
             <include>org.infinispan:infinispan-cachestore-cli</include>
             <include>org.infinispan:infinispan-cachestore-rest</include>
@@ -307,6 +308,7 @@
          <includeSubModules>false</includeSubModules>
          <includes>
             <include>org.infinispan:infinispan-cachestore-jdbc</include>
+            <include>org.infinispan:infinispan-cachestore-jpa</include>
             <include>org.infinispan:infinispan-cachestore-remote</include>
             <include>org.infinispan:infinispan-cachestore-cli</include>
             <include>org.infinispan:infinispan-cachestore-leveldb</include>