Summary: Using JPA with GigaSpaces.
OverviewThe Java Persistency API (JPA) is a Java programming language framework managing relational data in applications using Java Platform. GigaSpaces JPA allows you to use JPA's functionality, annotations and execute JPQL queries on Space. GigaSpaces JPA implementation is based on OpenJPA.
GigaSpaces JPA ConfigurationOpenJPAOpenJPA's jar file is included with the GigaSpaces ditribution (provided under <GigaSpaces root>/lib/platform/jpa), and the GigaSpaces-specific JPA implementation classes are part of the OpenSpaces jar (located under <GigaSpaces root>/lib/required/gs-openspaces.jar). <dependencies> <dependency> <groupId>org.apache.openjpa</groupId> <artifactId>openjpa</artifactId> <version>2.0.0</version> </dependency> </dependencies> OpenJPA 2.0.1GigaSpaces 8.0.1 uses OpenJPA version 2.0.1. The persistence.xml fileTo enable the GigaSpaces JPA implementation you should specify the following 3 mandatory properties in your persistence.xml:
Your persistence.xml file should be placed in any **/META-INF folder in your classpath. GigaSpaces JPA 8.0.1In 8.0.1, it is no longer needed to set the "abstractstore.AbstractStoreManager" property. The following is an example of a GigaSpaces JPA persistence.xml configuration file:
8.0.0 persistence.xml
<persistence-unit name="gigaspaces" transaction-type="RESOURCE_LOCAL"> <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider> <properties> <property name="BrokerFactory" value="abstractstore"/> <property name="abstractstore.AbstractStoreManager" value="org.openspaces.jpa.StoreManager"/> <property name="LockManager" value="none"/> </properties> </persistence-unit>
8.0.1 persistence.xml
<persistence-unit name="gigaspaces" transaction-type="RESOURCE_LOCAL"> <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider> <properties> <property name="BrokerFactory" value="org.openspaces.jpa.BrokerFactory"/> <property name="LockManager" value="none"/> </properties> </persistence-unit> Transaction Read Lock LevelGigaSpaces JPA default read lock level is set to "read" which is equivalent to GigaSpaces' ReadModifiers.REPEATABLE_READ.In order to use ReadModifiers.EXCLUSIVE_READLOCK the "ReadLockLevel" property should be set to "write": <property name="ReadLockLevel" value="write"/>
Space Connection InjectionSpecifying a space connection URL or a space instance can be done in one of the following ways: Referencing an Existing Space Instance through Factory PropertiesSpecifying a space instance is possible when creating an EntityManagerFactory in the following way: GigaSpace gigaspace = ... Properties properties = new Properties(); properties.put("ConnectionFactory", gigaspace.getSpace()); EntityManagerFactory emf = Persistence.createEntityManagerFactory("gigaspaces", properties); Injection using SpringIt is possible to inject either an EntityManager or EntityManagerFactory using Spring. Before reading this, it is recommend that you make yourself familiar with Spring's JPA support. <?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:os-core="http://www.openspaces.org/schema/core" xmlns:tx="http://www.springframework.org/schema/tx" xmlns:context="http://www.springframework.org/schema/context" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd http://www.openspaces.org/schema/core http://www.openspaces.org/schema/8.0/core/openspaces-core.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-3.0.xsd"> <!-- space definition --> <os-core:space id="space" url="/./jpaSpace" lookup-groups="test"/> <!-- gigaspace definition --> <os-core:giga-space id="gigaSpace" space="space"/> <!-- JPA entity manager factory definition --> <bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"> <!-- this relies on the fact that our persistence.xml file defines a persistence unit named "gigaspaces" --> <property name="persistenceUnitName" value="gigaspaces"/> <property name="jpaVendorAdapter"> <bean class="org.openspaces.jpa.OpenSpacesJpaVendorAdapter"> <property name="space" value="#{gigaSpace.space}"/> </bean> </property> </bean> <!-- JPA transaction manager definition --> <bean id="transactionManager" class="org.springframework.orm.jpa.JpaTransactionManager"> <property name="entityManagerFactory" ref="entityManagerFactory" /> </bean> <!-- support annotations --> <bean class="org.springframework.orm.jpa.support.PersistenceAnnotationBeanPostProcessor" /> <context:annotation-config/> <tx:annotation-driven transaction-manager="transactionManager"/> <!-- JPA example service definition --> <bean id="jpaService" class="org.openspaces.jpa.JpaService" /> </beans> Note that in our DAO, we'll have Spring inject the EntityManager using the @PersistentContext annotation. Spring will make sure to create an EntityManager using the EntityManagerFactory we have defined at the beginning of every transaction. @Repository @Transactional public class JpaService { @PersistenceContext private EntityManager em; public JpaService() { } @Transactional public void persistObject() { em.persist(...); } } Detailed information regarding persistence.xml can be found in OpenJPA's Manual. Listing Your Persistent Classes
When working with persistent classes, you have a number of ways to make the JPA layer aware of them:
Enhancing Your ClassesJPA classes are monitored at runtime for automatic dirty detection. To be transparent to the user, this requires bytecode enhancement to take place.
GigaSpaces JPA Entities
AnnotationsGigaSpaces JPA Entities must have both JPA and GigaSpaces annotations for the following annotations:
As with GigaSpaces POJOs, you may use the @SpaceIndex & @SpaceRouting annotations with GigaSpaces JPA entities.
Here's an example of a basic JPA Entity: @Entity public class Trade { private Long id; private Double quantity; private List<Double> rates; private boolean state; // Public no-argument constructor public Trade() { } // Both SpaceId and Id should be declared on the id property @Id @SpaceId public Long getId() { return this.id; } // Persistent property, no additional GigaSpaces annotations needs to be used. public Double getQuantity() { return this.quantity; } // A persistent collection property. In this case we'll use a GigaSpaces annotation // for indexing its values. @ElementCollection @SpaceIndex(path = "[*]") public List<Double> getRates() { return this.rates; } // A transient property. In this case we'll use both GigaSpaces and JPA annotations @Transient @SpaceExclude public boolean getState() { return this.state; } /* Additional Getters & Setters... */ } For auto generated Id declaration and complex object Id declaration refer to JPA Entity Id. Example of a JPA Owner entity with one to many relationship: @Entity public class Owner { // private Integer id; private String name; private List<Pet> pets; // public Owner() { } public Owner(Integer id, String name, List<Pet> pets) { super(); this.id = id; this.name = name; this.pets = pets; } // @Id @SpaceId public Integer getId() { return id; } public void setId(Integer id) { this.id = id; } @SpaceRouting public String getName() { return name; } public void setName(String name) { this.name = name; } @OneToMany(cascade = CascadeType.ALL) public List<Pet> getPets() { return pets; } public void setPets(List<Pet> pets) { this.pets = pets; } } Non-Indexed FieldsNon-Indexed fields that are not used for queries should be placed within a user defined class (payload object) and have their getter and setter placed within the payload class. This improves the read/write performance since these fields would not be introduced to the space class model. JPA Query Language (JPQL)GigaSpaces JPA supports a subset of JPQL. Here are a few examples of the supported queries: Querying on Properties of Nested ObjectsEntityManagerFactory emf = Persistence.createEntityManagerFactory("gigaspaces"); EntityManager em = emf.createEntityManager(); Query query = em.createQuery("SELECT c from org.openspaces.objects.Customer c WHERE c.address.country = 'United States'"); List<Customer> customers = (List<Customer>) query.getResultList(); em.close(); emf.close(); JOIN support for one to many relationship (Owner --> List<Pet>)EntityManagerFactory emf = Persistence.createEntityManagerFactory("gigaspaces"); EntityManager em = emf.createEntityManager(); Query query = em.createQuery("SELECT o FROM org.openspaces.objects.Owner o JOIN o.pets p WHERE p.name = :name"); query.setParameter("name", "Whiskey"); Owner owner = (Owner) query.getSingleResult(); em.close(); emf.close();
Persisting Collection PropertiesIt's possible to make a collection property persistent by using the @ElementCollection annotation. @Entity public class Card { // ... private List<Integer> numbers; @ElementCollection @SpaceIndex(path = "[*]") // the list values will be indexed. public List<Integer> getNumbers() { return this.numbers; } public void setNumbers(List<Integer> numbers) { this.numbers = numbers; } // ... } In order to query the Card entity using a specific Integer in the numbers collection we use JPQL's "MEMBER OF": EntityManagerFactory emf = Persistence.createEntityManagerFactory("gigaspaces"); EntityManager em = emf.createEntityManager(); Query query = em.createQuery("SELECT c FROM org.openspaces.objects.Card c WHERE :number MEMBER OF c.numbers"); query.setParameter("number", "10"); Card card = (Card) query.getSingleResult(); em.close(); emf.close(); Persisting Enum PropertiesJPA allows to persist Enum proeprties using the @Enumerated annotation, as shown below: // A Vehicle entity which has an Enum property @Entity public class Vehicle { // Enum Declaration public enum VehicleType { CAR, TRUCK, BIKE }; private Integer id; private String name; private VehicleType type; public Vehicle() { } @Id @SpaceId public Integer getId() { return this.id; } public String getName() { return this.name; } @Enumerated public VehicleType getType() { return this.type; } /* Additional Getters & Setters */ } We used the @Enumerated annotation for persisting an Enum property. Enums In JPQLIt's possible to query according to an Enum property by setting an Enum parameter or by using the Enum's value in the query string: EntityManager em = emf.createEntityManager(); // Query using an Enum parameter Query query1 = em.createQuery("SELECT vehicle FROM com.gigaspaces.objects.Vehicle vehicle WHERE vehicle.type = :type"); query1.setParameter("type", VehicleType.CAR); Vehicle result1 = (Vehicle) query1.getSingleResult(); // Query using an Enum in query's string Query query2 = em.createQuery("SELECT vehicle FROM com.gigaspaces.objects.Vehicle vehicle WHERE vehicle.type = 'BIKE'"); Vehicle result2 = (Vehicle) query2.getSingleResult(); InteroperabilityOne of the nice benefits of the GigaSpaces JPA implementation is that its fully interoperable with the GigaSpaces native POJO API. @Entity public class Author { private Integer id; private String name; private List<Book> books; public Author() { } @Id @SpaceId public Integer getId() { return this.id; } public String getName() { return this.name; } @OneToMany(cascade = CascadeType.ALL) @SpaceIndex(path = "[*].id") public List<Book> getBooks() { return this.books; } // Additional Getters & Setters... } @Entity public class Book implements Serializable { private Integer id; private String name; public Book() { } @Id @SpaceId public Integer getId() { return this.id; } public String getName() { return this.name; } // Additional Getters & Setters... } GigaSpace gigaspace = ... Book book1 = new Book(10, "Book Title 1"); Book book2 = new Book(20, "Book Title 2"); List<Book> books = new ArrayList<Book>(); books.add(book1); books.add(book2); Author author = new Author(); author.setId(1234); author.setBooks(books); // Persist using GigaSpaces JPA.. Properties properties = new Properties(); properties.put("ConnectionFactory", gigaspace.getSpace()); EntityManagerFactory emf = Persistence.createEntityManagerFactory("gigaspaces", properties); EntityManager em = emf.createEntityManager(); em.getTransaction().begin(); em.persist(author); em.getTransaction().commit(); em.close(); // Read using Space API.. Author result = gigaspace.readById(Author.class, 1234); // Or even SQLQuery.. SQLQuery<Author> query = new SQLQuery<Author>(Author.class, "id = 1234"); result = gigaspace.read(query); // Or by a certain book.. query = new SQLQuery<Author>(Author.class, "books[*].id = 10"); result = gigaspace.read(query); Native Query Execution
SQLQuery ExecutionSQLQuery execution using JPA native query API is pretty simple and made in the following way: // SQLQuery execution EntityManager em = emf.createEntityManagerFactory(); Query query = em.createNativeQuery("name = 'John Doe'", Author.class); Author author = (Author) query.getSingleResult(); // SQLQuery execution with parameters query = em.createNativeQuery("name = ?", Author.class); query.setParameter(1, "John Doe"); author = (Author) query.getSingleResult(); For more details on the SQLQuery syntax, refer to the SQLQuery page. Task ExecutionUsing GigaSpaces JPA native query API it is possible to execute tasks over the space in the following manner: // Task definition public class MyTask implements Task<Integer> { @TaskGigaSpace private transient GigaSpace gigaSpace; private Object routing; public MyTask(Object routing) { this.routing = routing; } public Integer execute() throws Exception { return gigaSpace.count(new Author()); } @SpaceRouting public Object getRouting() { return this.routing; } } // Task execution Query query = em.createNativeQuery("execute ?"); // Special syntax for task execution query.setParameter(1, new MyTask(1)); // We pass our task instance as a parameter to the query Integer result = (Integer) query.getSingleResult(); // Task execution always returns a single result
Getting an EntityManagerFactory instance in a TaskIts possible to get an EntityManagerFactory instance (according to the bean definition in pu.xml) by implementing the ApplicationContextAware interface. public class MyTask implements Task<Integer>, ApplicationContextAware { private transient EntityManagerFactory emf; public void setApplicationContext(ApplicationContext context) throws BeansException { // Get the entityManagerFactory bean emf = (EntityManagerFactory) context.getBean("entityManagerFactory"); } public Integer execute() throws Exception { // Create an EntityManager.. EntityManager em = emf.createEntityManager(); // ... em.close(); return 0; } } Another option instead of using the ApplicationContextAware interface is to annotate your Task with the @AutowireTask annotation and annotate the EntityManagerFactory property with a @Resource annotation. For more information about GigaSpaces tasks refer to Task Execution over the Space. Dynamic Script ExecutionIn addition to Task execution, GigaSpaces JPA native query execution also offers the ability to execute dynamic scripts such as Groovy, JavaScript & JRuby over the space. <!-- The service exporter exposing the scripting service --> <os-remoting:service-exporter id="serviceExporter"> <os-remoting:service ref="scriptingExecutor"/> </os-remoting:service-exporter> The next step is using the exposed scripting service on the client side using JPA's native query API: // Dynamic Script execution Script script = new StaticScript("GroovyScript", "groovy", "println 'Dynamic Script Execution using JPA'; return 0"); Query query = em.createNativeQuery("execute ?"); // Special syntax for script execution (similar to task execution) query.setParameter(1, script); // We pass our script as a parameter to the query Integer result = (Integer) query.getSingleResult(); // Script execution always returns a single result For more information about dynamic script execution refer to Dynamic Language Tasks. GigaSpaces JPA LimitationsFor a list of unsupported JPA features and limitations please refer to GigaSpaces JPA Limitations. |
![]() |
GigaSpaces.com - Legal Notice - 3rd Party Licenses - Site Map - API Docs - Forum - Downloads - Blog - White Papers - Contact Tech Writing - Gen. by Atlassian Confluence |