h1. Play/Siena Pagination tutorial

This tutorial shows the usage of the new Siena v1.x pagination mechanism within a Play.
You should see that this reduces a lot the code size and seems quite natural.

h2. <a>Siena Pagination Functions</a>

h3. <a>Create a Pagination Query</a>

p. You can create a query by calling the @all()@ function.

bc.. int PAGE_SIZE = 100;
Query<Employee> q = Employee.all().paginate(PAGE_SIZE);

p. 

h3. <a>Fetch current page</a>

p. You can get current page by call the @fetch()@ function.

bc. List<Employee> page1 = q.fetch();
 
h3. <a>Go to next page</a>

p. You can go to the next page by calling the @nextPage()@ function.

bc.. List<Employee> page2 = q.nextPage().fetch();
List<Employee> page3 = q.nextPage().fetch();

p(note). **Note** If you reach the last page and call nextPage again, it returns an empty list (size 0).

h3. <a>Go to previous page</a>

p. You can go to the previous page by calling the @previousPage()@ function

bc.. page2 = q.previousPage().fetch();
page1 = q.previousPage().fetch();

p(note). **Note** If you reach the first page and call previousPage again, it returns an empty list (size 0).


h2. <a>Siena Pagination Modes</a>

h3. <a>Default Stateless Mode</a>

p. By default, the query is **stateless** (which is generally what you need in the stateless architecture of Play!).
It means that no DB resource is kept alive between calls to this query (for SQL, connection/statement/resultset is released after each call).
Yet, to be able to paginate, it can't be fully stateless and the query keeps at least a marker of current page. 
__In stateless mode, for GAE and SQL, the marker is simply the offset of the first entity in the current page.__


h3. <a>Advanced Stateful Mode</a>

p. You can also use the brand new @stateful()@ feature by writing:

bc.. Query<Employee> q = Employee.all().stateful();

p. Other operations are exactly the same as the stateless query. The difference is not here.

So, what does **stateful** mean?
It means allocated DB resources are kept alive between calls to this query:
* **For __SQL__**, connection/statement/resultset are kept opened and the pagination is managed with offsets as for stateless mode.
The connection is kept opened between calls so when you want to release it, you can call the @release()@ function.

bc. q.release()
 
p(note). **note** If for any reason, the connection or statement have been closed, Siena cares for re-creating them.

* **For __GAE__**, the main difference is that the pagination is managed with **__GAE cursors__**. 
Siena deals with GAE cursors for you and allows to go forward and backward in pagination (whereas simple GAE cursors can only go forward). 
This feature is quite interesting as GAE offsets have some performance issues whereas GAE cursors don't.

h2. <a>Play/Siena pagination</a>

So, in order to paginate in a transparent way, the idea is to reuse the same query several times.
It means the query must be stored somewhere. The first tool that comes in mind is the Play Cache. A Siena query is Java serializable so Cache can store it in a clean way.

The steps to integrate Siena pagination into Play are quite trivial:
* Find an existing query in the Cache and if not found, create a new query
* Get a page of entities
* Store the query in the Cache
* Render the page of entities


h3. <a>Create the Controller</a>

bc.. public class Application extends Controller {
	static Query<Employee> q;

	@Before
	public static void loadQuery() {
		q = (Query<Employee>) Cache.get("q");
		if (q == null) {
			// stateful is just meant to use GAE cursors instead of offsets
			q = Employee.all().stateful().paginate(100);
		}
	}

	@After
	public static void saveQuery() {
		Cache.set("q", q);
	}

	public static void index() {
		List<Employee> emps = q.fetch();

		renderTemplate("Application/list.html", emps);
	}

	public static void nextPage() {
		List<Employee> emps = q.nextPage().fetch();

		renderTemplate("Application/list.html", emps);
	}

	public static void previousPage() {
		List<Employee> emps = q.previousPage().fetch();

		renderTemplate("Application/list.html", emps);
	}

}

p(note). **note** The @Before is in charge of retrieving/creating the Query from Cache

p(note). **note** The @After is in charge of storing the Query into Cache

p(note). **note** Functions nextPage/previousPage are simple actions you can use in your templates

p(note). **note** The query is stored with a single identifier __"q"__ which is not good if you have several users connected at the same time. So, you should diversify this id with a userID for ex.

h3. <a>A dumb template sample</a>

bc.. #{set title:'nextPage' /}

<h1>Employees (${emps.size()})</h1>
<p>
   <a href="@{Application.nextPage()}">Next Page</a>
   <a href="@{Application.previousPage()}">Previous Page</a>
</p>

<ul>
    #{list items:emps, as:'emp' }
        <li>${emp?.id}: ${emp}</li>
    #{/list}
</ul>

p. 
