Ebean ORM
-------------------
- LGPL Licence
- Uses JPA annotations for Mapping (@Entity, @OneToMany etc)
- Simple "sessionless" API (no merge,persist,flush etc)
- Supports "Partial Object" queries
- Automatic query tuning via "Autofetch"
Asynchronous Query execution
----------------------------
These queries are executed in a background thread and "Future" objects are returned. The "Future" objects returned extend java.util.concurrent.Future. This provides support for cancelling the query, checking if it is cancelled or done and getting the result with waiting and timeout support.
PagingList is used to make it easy to page through a query result. Paging through the results means that instead of all the results are not fetched in a single query Ebean will use SQL to limit the results (limit/offset, rownum, row_number() etc).
Instead of using PagingList you could just use setFirstRow() setMaxRows() on the query yourself. If you are building a stateless application (not holding the PagingList over multiple requests) then this approach is a good option.
For Stateful applications PagingList provides some benefits:
* Fetch ahead (background fetching of the next page via a FutureList query)
* Automatic propagation of the persistence context
* Automatically getting the total row count (via a FutureRowCount query)
So with PagingList when you use Page 2 it will automatically fetch Page 3 data in the background (using a FutureList query). The persistence context is automatically propagated meaning that all the paging queries use the same persistence context.
example
1. int pageSize = 10;
2.
3. PagingList pagingList =
4. Ebean.find(TOne.class)
5. .where().gt("name", "2")
6. .findPagingList(pageSize);
7.
8.
9. // get the row count in the background...
10. // ... otherwise it is fetched on demand
11. // ... when getTotalRowCount() or getTotalPageCount()
12. // ... is called
13. pagingList.getFutureRowCount();
14.
15. // get the first page
16. Page page = pagingList.getPage(0);
17.
18. // get the beans from the page as a list
19. List list = page.getList();
20.
21.
22. int totalRows = page.getTotalRowCount();
23.
24. if (page.hasNext()) {
25. Page nextPage = page.next();
26. ...
27. }
PagingList query
------------------------
PagingList is designed to make it easy to page through a query result. It includes support for 'fetch ahead' - fetching the next page via background query once the previous page is touched. It also automatically propagates the 'Persistence Context' so that all queries share the same persistence context and has built in support for getting the total row and page counts via FutureRowCount.
Asynchrous Query execution
Ebean has built in support for executing queries asynchronously. These queries are executed in a background thread and "Future" objects are returned. The "Future" objects returned extend java.util.concurrent.Future. This provides support for cancelling the query, checking if it is cancelled or done and getting the result with waiting and timeout support.
example
1. // Methods on Query for ansychronous execution
2.
3. public FutureList findFutureList();
4.
5. public FutureIds findFutureIds();
6.
7. public FutureRowCount findFutureRowCount();
// Methods on Query for ansychronous execution
public FutureList findFutureList();
public FutureIds findFutureIds();
public FutureRowCount findFutureRowCount();
An example showing the use of FutureList:
example
1. Query query = Ebean.find(Order.class);
2.
3. // find list using a background thread
4. FutureList futureList = query.findFutureList();
5.
6. // do something else ...
7.
8. if (!futureList.isDone()){
9. // you can cancel the query. If supported by the JDBC
10. // driver and database this will actually cancel the
11. // sql query execution on the database
12. futureList.cancel(true);
13. }
14. // wait for the query to finish ... no timeout
15. List list = futureList.get();
16.
17. // wait for the query to finish ... with a 30sec timeout
18. List list2 = futureList.get(30, TimeUnit.SECONDS);
Refactoring of the Cache
------------------------
Now when utilising the "L2" server cache you can specify you want 'readOnly' beans and then Ebean can return the instance from the cache rather than creating a new instance and copying the data (as a performance optimisation).
The instances from the cache are marked as 'shared instances' and are effectively immutable - calling a setter on a shared instance will throw an IllegalStateException.
The user guide documentation has been updated to reflect the changes to the cache, declaratively using the cache and discussion of 'persistence context' as the first level cache.
