This documentation is for an old version of fiftyfive-wicket (2.0.9).


fiftyfive.wicket.data
Class DtoDataProvider<R,E>

java.lang.Object
  extended by fiftyfive.wicket.data.DtoDataProvider<R,E>
All Implemented Interfaces:
Serializable, IClusterable, IDataProvider<E>, IDetachable

public abstract class DtoDataProvider<R,E>
extends Object
implements IDataProvider<E>

An IDataProvider that implements the DTO pattern. Suitable for full-text search results and other result sets where size and data are returned in a single DTO.

This is a drop-in replacement for IDataProvider, allowing you to use Wicket's existing components like DataGridView, DataView, PagingNavigator, etc. in a DTO-style efficient manner without any customization. (However see the cautionary note below.)

The main advantage of using this class is that it implements IDataProvider.size() and IDataProvider.iterator() with a single backend query. This is accomplished by maintaining a reference to a pageable view, so that page size and offset can be determined when size() is called. The size is also cached to prevent extra backend calls when paging links are clicked.

In other words, rather than having to issue two calls to the backend, once to determine the size of the result, and then again to determine the actual rows of data in the result, you can instead implement a single load() method that returns a DTO containing both the size and the data. Often times this is much more efficient, especially when dealing with web service and full-text search implementations.

Be sure to call flushSizeCache() or construct a new DtoDataProvider when you know your result size will change, for example if the user changes her search criteria.

Generic types:

Note that since DtoDataProvider needs a reference back to the pageable view that is displaying its data, the object construction process takes a few steps:

 // Let's say this is our concrete implementation.
 public class UserResultProvider extends DtoDataProvider<UserSearchResult,User>
 {
     // implement iterator(UserSearchResult), size(UserSearchResult) and load(int,int)
 }
 
 // To use our provider to drive a DataView, first we construct our provider.
 UserResultProvider provider = new UserResultProvider();
 
 // Then construct the DataView, passing in our provider.
 DataView<User> dataView = new DataView<User>("users", provider) {
     // implement populateItem()
 };
 
 // Finally, wire up our provider back to the view
 provider.setPageableView(dataView);

Caution: This class should be considered experimental. By implementing size() and iterator() with a single backend query, this class goes against the Wicket developers' original intentions for the IDataProvider interface. We accomplish this feat by using the Java reflection API to access private and protected data within AbstractPageableView.

Since:
2.0
See Also:
Serialized Form

Constructor Summary
DtoDataProvider()
          Constructs an empty provider.
DtoDataProvider(AbstractPageableView pageableView)
          Constructs a provider that will use size and offset information from the specified AbstractPageableView when loading data.
 
Method Summary
 void detach()
          Discards the cached view offset, rows per page, and result DTO objects.
 void flushSizeCache()
          Flush the cached size information that is normally held between requests.
protected  int getPageableRowsPerPage()
          Obtains the maximum rows per page needed by the pageable view by using the Java reflection API to call the protected internalGetRowsPerPage() method.
 AbstractPageableView getPageableView()
          Returns the pageable view associated with this provider.
protected  int getPageableViewOffset()
          Obtains the current view offset using the Java reflection API to get the currentPage private field from the pageable view and multiplying it by the rows per page.
 R getResult()
          Loads and returns the result DTO from the backend, or returns the cached copy if it has already been loaded.
 Iterator<? extends E> iterator(int offset, int amount)
          Loads the result DTO from the backend if necessary, then delegates to the implementation of iterator(R).
protected abstract  Iterator<? extends E> iterator(R result)
          Returns an iterator of the items contained in the given result object.
protected  R load()
          Loads the result DTO from the backend, using the current view offset and rows per page information from the pageable view associated with this provider.
protected abstract  R load(int offset, int amount)
          Loads the result object from the backend.
 IModel<E> model(E object)
          This implementation assumes the object is Serializable and simply calls Model.of().
 void setPageableView(AbstractPageableView pageableView)
          Sets the AbstractPageableView for which this object will be used as data provider.
 int size()
          Returns a cached value if possible.
protected abstract  int size(R result)
          Returns the total number of items in the entire result, as represented by the given result object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DtoDataProvider

public DtoDataProvider()
Constructs an empty provider. You must call setPageableView() before the provider can be used.


DtoDataProvider

public DtoDataProvider(AbstractPageableView pageableView)
Constructs a provider that will use size and offset information from the specified AbstractPageableView when loading data.

Method Detail

flushSizeCache

public void flushSizeCache()
Flush the cached size information that is normally held between requests. This method should be called for example when your search criteria changes, meaning that the result data could completely change.

You shouldn't need to use this method, since new search criteria would normally mean constructing a completely new DtoDataProvider.


getPageableView

public AbstractPageableView getPageableView()
Returns the pageable view associated with this provider.


setPageableView

public void setPageableView(AbstractPageableView pageableView)
Sets the AbstractPageableView for which this object will be used as data provider. The pageable view is consulted whenever the result object is loaded from the backend, in order to get the current page offset and page size. This property must not be null.


load

protected abstract R load(int offset,
                          int amount)
Loads the result object from the backend. The object will be cached for the remainder of the current request, or until detach() is called.

Parameters:
offset - A zero-based offset of the first result desired, based on the current page number and page size.
amount - The number of results desired (i.e. the page size).

iterator

protected abstract Iterator<? extends E> iterator(R result)
Returns an iterator of the items contained in the given result object.


size

protected abstract int size(R result)
Returns the total number of items in the entire result, as represented by the given result object.


iterator

public Iterator<? extends E> iterator(int offset,
                                      int amount)
Loads the result DTO from the backend if necessary, then delegates to the implementation of iterator(R).

Specified by:
iterator in interface IDataProvider<E>

model

public IModel<E> model(E object)
This implementation assumes the object is Serializable and simply calls Model.of(). You may wish to override with a custom model.

Specified by:
model in interface IDataProvider<E>

size

public int size()
Returns a cached value if possible. Otherwise loads the result DTO from the backend and delegates to the implementation of size(R).

Specified by:
size in interface IDataProvider<E>

getResult

public R getResult()
Loads and returns the result DTO from the backend, or returns the cached copy if it has already been loaded. The cache is discarded when detach() is called.


load

protected R load()
Loads the result DTO from the backend, using the current view offset and rows per page information from the pageable view associated with this provider.


detach

public void detach()
Discards the cached view offset, rows per page, and result DTO objects. Note that the result size remains cached.

Specified by:
detach in interface IDetachable

getPageableViewOffset

protected int getPageableViewOffset()
Obtains the current view offset using the Java reflection API to get the currentPage private field from the pageable view and multiplying it by the rows per page.


getPageableRowsPerPage

protected int getPageableRowsPerPage()
Obtains the maximum rows per page needed by the pageable view by using the Java reflection API to call the protected internalGetRowsPerPage() method.



Copyright © 2011 55 Minutes. All Rights Reserved.