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


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 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.
 R getCachedResultOrLoad()
          Loads and returns the result DTO from the backend, or returns the cached copy if it has already been loaded.
 R getCachedResultOrLoad(int offset, int amount)
          Loads and returns the result DTO from the backend, or returns the cached copy if it has already been loaded.
protected  int getPageableRowsPerPage()
          Obtains the maximum rows per page needed by the pageable view by calling the getItemsPerPage() 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.
 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 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()
          Loads the result DTO from the back-end based on the current state of the page.
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()
Loads the result DTO from the back-end based on the current state of the page. A cached version of the DTO will be used if possible to reduce extra back-end calls.

Delegates to the implementation of size(R), which subclasses must implement.

This result will be cached, and the cache used if possible.

Specified by:
size in interface IDataProvider<E>

getCachedResultOrLoad

public R getCachedResultOrLoad()
Loads and returns the result DTO from the backend, or returns the cached copy if it has already been loaded. The cache is discarded automatically if the cache is out of date (i.e. the offset and amount to load have changed). The cache is also discarded when detach() is called.

This no-argument version infers the offset and amount to load based on the pageable view that is being used with this data provider.

Since:
4.0

getCachedResultOrLoad

public R getCachedResultOrLoad(int offset,
                               int amount)
Loads and returns the result DTO from the backend, or returns the cached copy if it has already been loaded. The cache is discarded automatically if the cache is out of date (i.e. the offset and amount to load have changed). The cache is also discarded when detach() is called.

The explicit offset and amount parameters indicate the items to be loaded. If the cache was for a different set of parameters, it will be discarded.

Since:
4.0

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 calling the getItemsPerPage() method.



Copyright © 2012 55 Minutes. All Rights Reserved.