AbstractQueryContainer (DellRoad Stuff Vaadin 7.x Classes 2.1.0 API)

java.lang.Object
- com.vaadin.data.util.AbstractContainer
- - org.dellroad.stuff.vaadin7.AbstractQueryContainer<T>

Type Parameters:

T - the type of the Java objects that back each Item in the container

All Implemented Interfaces:

Container, Container.Indexed, Container.ItemSetChangeNotifier, Container.Ordered, Container.PropertySetChangeNotifier, Serializable, Connectable, PropertyExtractor<T>

Direct Known Subclasses:

AbstractUnsizedContainer
```
public abstract class AbstractQueryContainer<T>
extends AbstractContainer
implements PropertyExtractor<T>, Container.Ordered, Container.Indexed, Container.PropertySetChangeNotifier, Container.ItemSetChangeNotifier, Connectable
```
Support superclass for read-only Container implementations where each Item in the container is backed by a Java object, and the Java objects are generated via a query that returns a QueryList containing only some portion of the total list of backing objects at any one time.
This Container's Propertys are defined via PropertyDefs, and a PropertyExtractor is used to actually extract the property values from each underlying object (alternately, subclasses can override getPropertyValue()). However, the easist way to configure the container Propertys is to pass a @ProvidesProperty-annotated Java class to the AbstractQueryContainer(Class) constructor.
This Container's item ID's are simply the indexes of the corresponding objects in the overall list. The QueryList interface is designed for scalability; at minimum, it is required to provide only the size of the total list (which may only be an estimate) and one backing object at a specified index.
This class will invoke query(long) as needed to (re)generate the QueryList; the QueryList is then cached. However, if any invocation of QueryList.get(long) throws an InvalidQueryListException, then the cached list is discarded and query(long) is invoked again to regenerate it. In this way, the QueryList is allowed to decide, on demand, when it is invalid or incapable of providing a specific list member. For example, when using JPA, a list may be considered invalid if the current EntityManager session has changed.
Note that the QueryList being invalid is an orthogonal concept from the contents of the list having changed. Invalid means "this list can no longer be used" while changed means "this list contains out-of-date information". Normally, the latter implies the former (but not vice-versa). The list becoming invalid does not in itself not cause any notifications to be sent, so no new query will be performed until e.g. the user interface explicitly requests more information.
Therefore, if the list size or content changes, first invoke invalidate() to discard the cached QueryList, and then AbstractContainer.fireItemSetChange() to notify listeners; for convenience, reload() will perform these two steps for you. The new size and content will be provided by the QueryList returned by the next invocation of query(long).
The subclass may forcibly invalidate the current QueryList via invalidate(); this merely discards it and will force a new invocation of query(long) on the next container access. In many situations, however, the use of invalidate() is never required.
For scalability reasons the QueryList may actually only contain a portion of the list, throwing InvalidQueryListExceptions when other list members are accessed. An "index hint" parameter provided to query(long) indicates which member of the container is of current interest. The returned QueryList is required to provide exception-free access only to the indicated member, so in the extreme case only a single list member could be kept. In practice, normally range of members near to the index hint would be kept; see for example WindowQueryList.

See Also:

QueryList, SimpleQueryList, WindowQueryList, AbstractUnsizedContainer, Serialized Form

Nested Class Summary
- Nested classes/interfaces inherited from class com.vaadin.data.util.AbstractContainer
  AbstractContainer.BaseItemSetChangeEvent, AbstractContainer.BasePropertySetChangeEvent
- Nested classes/interfaces inherited from interface com.vaadin.data.Container.Indexed
  Container.Indexed.ItemAddEvent, Container.Indexed.ItemRemoveEvent
- Nested classes/interfaces inherited from interface com.vaadin.data.Container
  Container.Editor, Container.Filter, Container.Filterable, Container.Hierarchical, Container.Indexed, Container.ItemSetChangeEvent, Container.ItemSetChangeListener, Container.ItemSetChangeNotifier, Container.Ordered, Container.PropertySetChangeEvent, Container.PropertySetChangeListener, Container.PropertySetChangeNotifier, Container.SimpleFilterable, Container.Sortable, Container.Viewer

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`AbstractQueryContainer()` Constructor.
`protected`	`AbstractQueryContainer(Class<? super T> type)` Constructor.
`protected`	`AbstractQueryContainer(Collection<? extends PropertyDef<?>> propertyDefs)` Constructor.
`protected`	`AbstractQueryContainer(PropertyExtractor<? super T> propertyExtractor)` Constructor.
`protected`	`AbstractQueryContainer(PropertyExtractor<? super T> propertyExtractor, Collection<? extends PropertyDef<?>> propertyDefs)` Constructor.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`addContainerProperty(Object propertyId, Class<?> type, Object defaultValue)`
`Item`	`addItem()`
`Item`	`addItem(Object itemId)`
`Item`	`addItemAfter(Object previousItemId)`
`Item`	`addItemAfter(Object previousItemId, Object newItemId)`
`Object`	`addItemAt(int index)`
`Item`	`addItemAt(int index, Object newItemId)`
`void`	`addItemSetChangeListener(Container.ItemSetChangeListener listener)`
`void`	`addListener(Container.ItemSetChangeListener listener)`
`void`	`addListener(Container.PropertySetChangeListener listener)`
`void`	`addPropertySetChangeListener(Container.PropertySetChangeListener listener)`
`void`	`connect()` Connect this instance to non-Vaadin resources.
`boolean`	`containsId(Object itemId)`
`protected BackedItem<T>`	`createBackedItem(T object, Collection<PropertyDef<?>> propertyDefs, PropertyExtractor<? super T> propertyExtractor)` Create a `BackedItem` for the given backing Java object.
`void`	`disconnect()` Disconnect this instance from non-Vaadin resources.
`protected long`	`ensureList(int hint)` Ensure we have a cached query list.
`Integer`	`firstItemId()`
`Property`	`getContainerProperty(Object itemId, Object propertyId)`
`Set<String>`	`getContainerPropertyIds()`
`Integer`	`getIdByIndex(int index)`
`BackedItem<T>`	`getItem(Object itemId)`
`Collection<Integer>`	`getItemIds()`
`List<Integer>`	`getItemIds(int startIndex, int numberOfItems)`
`protected T`	`getJavaObject(int index)` Get the Java backing object at the given index in the list.
`PropertyExtractor<? super T>`	`getPropertyExtractor()` Get the configured `PropertyExtractor` for this container.
`<V> V`	`getPropertyValue(T obj, PropertyDef<V> propertyDef)` Read the value of the property defined by `propertyDef` from the given object.
`Class<?>`	`getType(Object propertyId)`
`protected void`	`handleSizeChange()` Invoked when a new `QueryList` has returned a changed `size()` for the underlying list.
`int`	`indexOfId(Object itemId)`
`protected void`	`invalidate()` Discard the current cached `QueryList`, if any.
`boolean`	`isFirstId(Object itemId)`
`boolean`	`isLastId(Object itemId)`
`Integer`	`lastItemId()`
`Integer`	`nextItemId(Object itemId)`
`Integer`	`prevItemId(Object itemId)`
`protected abstract QueryList<? extends T>`	`query(long hint)` Perform a query to (re)generate the list of Java objects backing this container.
`void`	`reload()` Reload this container.
`boolean`	`removeAllItems()`
`boolean`	`removeContainerProperty(Object propertyId)`
`boolean`	`removeItem(Object itemId)`
`void`	`removeItemSetChangeListener(Container.ItemSetChangeListener listener)`
`void`	`removeListener(Container.ItemSetChangeListener listener)`
`void`	`removeListener(Container.PropertySetChangeListener listener)`
`void`	`removePropertySetChangeListener(Container.PropertySetChangeListener listener)`
`void`	`setProperties(Collection<? extends PropertyDef<?>> propertyDefs)` Change the configured properties of this container.
`void`	`setPropertyExtractor(PropertyExtractor<? super T> propertyExtractor)` Change the configured `PropertyExtractor` for this container.
`int`	`size()`

Methods inherited from class com.vaadin.data.util.AbstractContainer
fireContainerPropertySetChange, fireContainerPropertySetChange, fireItemSetChange, fireItemSetChange, getItemSetChangeListeners, getListeners, getPropertySetChangeListeners, setItemSetChangeListeners, setPropertySetChangeListeners

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - AbstractQueryContainer
```
protected AbstractQueryContainer()
```
    Constructor.
    After using this constructor, subsequent invocations of setPropertyExtractor() and setProperties() are required to define the properties of this container and how to extract them.
  - AbstractQueryContainer
```
protected AbstractQueryContainer(PropertyExtractor<? super T> propertyExtractor)
```
    Constructor.
    After using this constructor, a subsequent invocation of setProperties() is required to define the properties of this container.
    
    Parameters:
    
    propertyExtractor - used to extract properties from the underlying Java objects; may be null but then container is not usable until one is configured via setPropertyExtractor()
  - AbstractQueryContainer
```
protected AbstractQueryContainer(Collection<? extends PropertyDef<?>> propertyDefs)
```
    Constructor.
    After using this constructor, a subsequent invocation of setPropertyExtractor() is required to define how to extract the properties of this container; alternately, subclasses can override getPropertyValue().
    
    Parameters:
    
    propertyDefs - container property definitions; null is treated like the empty set
  - AbstractQueryContainer
```
protected AbstractQueryContainer(PropertyExtractor<? super T> propertyExtractor,
                                 Collection<? extends PropertyDef<?>> propertyDefs)
```
    Constructor.
    
    Parameters:
    
    propertyExtractor - used to extract properties from the underlying Java objects; may be null but then container is not usable until one is configured via setPropertyExtractor()
    
    propertyDefs - container property definitions; null is treated like the empty set
  - AbstractQueryContainer
```
protected AbstractQueryContainer(Class<? super T> type)
```
    Constructor.
    Properties will be determined by the @ProvidesProperty and @ProvidesPropertySort annotated methods in the given class.
    
    Parameters:
    
    type - class to introspect for annotated methods
    
    Throws:
    
    IllegalArgumentException - if type is null
    
    IllegalArgumentException - if type has two @ProvidesProperty or @ProvidesPropertySort annotated methods for the same property
    
    IllegalArgumentException - if a @ProvidesProperty-annotated method with no property name specified has a name which cannot be interpreted as a bean property "getter" method
    
    See Also:
    
    ProvidesProperty, ProvidesPropertySort, ProvidesPropertyScanner
- Method Detail
  - getPropertyExtractor
```
public PropertyExtractor<? super T> getPropertyExtractor()
```
    Get the configured PropertyExtractor for this container.
    
    Returns:
    
    the configured PropertyExtractor
  - setPropertyExtractor
```
public void setPropertyExtractor(PropertyExtractor<? super T> propertyExtractor)
```
    Change the configured PropertyExtractor for this container. Invoking this method does not result in any container notifications.
    
    Parameters:
    
    propertyExtractor - used to extract properties from the underlying Java objects; may be null but the container is not usable without one
  - getPropertyValue
```
public <V> V getPropertyValue(T obj,
                              PropertyDef<V> propertyDef)
```
    Read the value of the property defined by propertyDef from the given object.
    The implementation in AbstractQueryContainer just delegates to the configured PropertyExtractor; subclasses may override to customize property extraction.
    
    Specified by:
    
    getPropertyValue in interface PropertyExtractor<T>
    
    Type Parameters:
    
    V - value type
    
    Parameters:
    
    obj - Java object
    
    propertyDef - definition of which property to read
    
    Returns:
    
    property value
    
    Throws:
    
    NullPointerException - if either parameter is null
    
    IllegalStateException - if no PropertyExtractor is configured for this container
  - setProperties
```
public void setProperties(Collection<? extends PropertyDef<?>> propertyDefs)
```
    Change the configured properties of this container.
    
    Parameters:
    
    propertyDefs - container property definitions; null is treated like the empty set
    
    Throws:
    
    IllegalArgumentException - if propertyDefs contains a property with a duplicate name
  - reload
```
public void reload()
```
    Reload this container.
    This discards the current cached QueryList (if any) and fires an item set change event.
  - connect
```
public void connect()
```
    Connect this instance to non-Vaadin resources.
    The implementation in AbstractQueryContainer does nothing.
    
    Specified by:
    
    connect in interface Connectable
    
    Throws:
    
    IllegalStateException - if there is no VaadinSession associated with the current thread
  - disconnect
```
public void disconnect()
```
    Disconnect this instance from non-Vaadin resources.
    The implementation in AbstractQueryContainer does nothing.
    
    Specified by:
    
    disconnect in interface Connectable
    
    Throws:
    
    IllegalStateException - if there is no VaadinSession associated with the current thread
  - query
```
protected abstract QueryList<? extends T> query(long hint)
```
    Perform a query to (re)generate the list of Java objects backing this container.
    The particular position in the list we are interested in is given as a hint by the hint parameter. That is, an invocation of QueryList.get(long)(hint) is likely immediately after this method returns and if so it must complete without throwing an exception, unless hint is out of range.
    The hint can be used to implement a highly scalable query list containing external objects (such as from a database) where only a small "window" of objects is actually kept in memory at any one time. Of course, implementations are also free to ignore hint. However, the returned QueryList must at least tolerate one invocation of get(hint) without throwing an exception when hint is less that the size() of the returned QueryList.
    
    Parameters:
    
    hint - index of the list element we are interested in
    
    Returns:
    
    list of Java objects backing this container
  - invalidate
```
protected void invalidate()
```
    Discard the current cached QueryList, if any.
  - getJavaObject
```
protected T getJavaObject(int index)
```
    Get the Java backing object at the given index in the list.
    
    Parameters:
    
    index - list index
    
    Returns:
    
    backing object, or null if index is out of range
  - ensureList
```
protected long ensureList(int hint)
```
    Ensure we have a cached query list.
    
    Parameters:
    
    hint - index of the list element we are interested in, passed to query(long) if no query list is cached
    
    Returns:
    
    the size of the cached query list
  - handleSizeChange
```
protected void handleSizeChange()
```
    Invoked when a new QueryList has returned a changed size() for the underlying list.
    Normally, this implies an item set change notification will be generated elsewhere and so no additional action needs to be taken by this method. However, some implementations may lack such a mechanism, for example, when the container's size is only ever calculated when query(long) is invoked. In such cases, this method may trigger a notification.
    Note: to avoid re-entrancy problems, this method should not send out any notifications itself; instead, it may schedule notifications to be delivered later, e.g., via VaadinUtil.invokeLater(com.vaadin.server.VaadinSession, java.lang.Runnable).
    The implementation in AbstractQueryContainer does nothing, assuming the notification is handled elsewhere. Subclasses may override if needed.
  - createBackedItem
```
protected BackedItem<T> createBackedItem(T object,
                                         Collection<PropertyDef<?>> propertyDefs,
                                         PropertyExtractor<? super T> propertyExtractor)
```
    Create a BackedItem for the given backing Java object.
    The implementation in AbstractQueryContainer returns new SimpleItem<T>(object, propertyDefs, propertyExtractor).
    
    Parameters:
    
    object - underlying Java object
    
    propertyDefs - property definitions
    
    propertyExtractor - extracts the property value from object
    
    Returns:
    
    new BackedItem
    
    Throws:
    
    IllegalArgumentException - if any parameter is null
  - getItem
```
public BackedItem<T> getItem(Object itemId)
```
    Specified by:
    
    getItem in interface Container
  - getItemIds
```
public Collection<Integer> getItemIds()
```
    Specified by:
    
    getItemIds in interface Container
  - getContainerPropertyIds
```
public Set<String> getContainerPropertyIds()
```
    Specified by:
    
    getContainerPropertyIds in interface Container
  - getContainerProperty
```
public Property getContainerProperty(Object itemId,
                                     Object propertyId)
```
    Specified by:
    
    getContainerProperty in interface Container
  - getType
```
public Class<?> getType(Object propertyId)
```
    Specified by:
    
    getType in interface Container
  - size
```
public int size()
```
    Specified by:
    
    size in interface Container
  - containsId
```
public boolean containsId(Object itemId)
```
    Specified by:
    
    containsId in interface Container
  - addItem
```
public Item addItem(Object itemId)
```
    Specified by:
    
    addItem in interface Container
    
    Throws:
    
    UnsupportedOperationException - always
  - addItem
```
public Item addItem()
```
    Specified by:
    
    addItem in interface Container
    
    Throws:
    
    UnsupportedOperationException - always
  - removeItem
```
public boolean removeItem(Object itemId)
```
    Specified by:
    
    removeItem in interface Container
    
    Throws:
    
    UnsupportedOperationException - always
  - addContainerProperty
```
public boolean addContainerProperty(Object propertyId,
                                    Class<?> type,
                                    Object defaultValue)
```
    Specified by:
    
    addContainerProperty in interface Container
    
    Throws:
    
    UnsupportedOperationException - always
  - removeContainerProperty
```
public boolean removeContainerProperty(Object propertyId)
```
    Specified by:
    
    removeContainerProperty in interface Container
    
    Throws:
    
    UnsupportedOperationException - always
  - removeAllItems
```
public boolean removeAllItems()
```
    Specified by:
    
    removeAllItems in interface Container
    
    Throws:
    
    UnsupportedOperationException - always
  - addItemAt
```
public Object addItemAt(int index)
```
    Specified by:
    
    addItemAt in interface Container.Indexed
    
    Throws:
    
    UnsupportedOperationException - always
  - addItemAt
```
public Item addItemAt(int index,
                      Object newItemId)
```
    Specified by:
    
    addItemAt in interface Container.Indexed
    
    Throws:
    
    UnsupportedOperationException - always
  - getIdByIndex
```
public Integer getIdByIndex(int index)
```
    Specified by:
    
    getIdByIndex in interface Container.Indexed
  - getItemIds
```
public List<Integer> getItemIds(int startIndex,
                                int numberOfItems)
```
    Specified by:
    
    getItemIds in interface Container.Indexed
  - indexOfId
```
public int indexOfId(Object itemId)
```
    Specified by:
    
    indexOfId in interface Container.Indexed
  - nextItemId
```
public Integer nextItemId(Object itemId)
```
    Specified by:
    
    nextItemId in interface Container.Ordered
  - prevItemId
```
public Integer prevItemId(Object itemId)
```
    Specified by:
    
    prevItemId in interface Container.Ordered
  - firstItemId
```
public Integer firstItemId()
```
    Specified by:
    
    firstItemId in interface Container.Ordered
  - lastItemId
```
public Integer lastItemId()
```
    Specified by:
    
    lastItemId in interface Container.Ordered
  - isFirstId
```
public boolean isFirstId(Object itemId)
```
    Specified by:
    
    isFirstId in interface Container.Ordered
  - isLastId
```
public boolean isLastId(Object itemId)
```
    Specified by:
    
    isLastId in interface Container.Ordered
  - addItemAfter
```
public Item addItemAfter(Object previousItemId)
```
    Specified by:
    
    addItemAfter in interface Container.Ordered
    
    Throws:
    
    UnsupportedOperationException - always
  - addItemAfter
```
public Item addItemAfter(Object previousItemId,
                         Object newItemId)
```
    Specified by:
    
    addItemAfter in interface Container.Ordered
    
    Throws:
    
    UnsupportedOperationException - always
  - addListener
```
public void addListener(Container.PropertySetChangeListener listener)
```
    Specified by:
    
    addListener in interface Container.PropertySetChangeNotifier
    
    Overrides:
    
    addListener in class AbstractContainer
  - addPropertySetChangeListener
```
public void addPropertySetChangeListener(Container.PropertySetChangeListener listener)
```
    Specified by:
    
    addPropertySetChangeListener in interface Container.PropertySetChangeNotifier
    
    Overrides:
    
    addPropertySetChangeListener in class AbstractContainer
  - removeListener
```
public void removeListener(Container.PropertySetChangeListener listener)
```
    Specified by:
    
    removeListener in interface Container.PropertySetChangeNotifier
    
    Overrides:
    
    removeListener in class AbstractContainer
  - removePropertySetChangeListener
```
public void removePropertySetChangeListener(Container.PropertySetChangeListener listener)
```
    Specified by:
    
    removePropertySetChangeListener in interface Container.PropertySetChangeNotifier
    
    Overrides:
    
    removePropertySetChangeListener in class AbstractContainer
  - addListener
```
public void addListener(Container.ItemSetChangeListener listener)
```
    Specified by:
    
    addListener in interface Container.ItemSetChangeNotifier
    
    Overrides:
    
    addListener in class AbstractContainer
  - addItemSetChangeListener
```
public void addItemSetChangeListener(Container.ItemSetChangeListener listener)
```
    Specified by:
    
    addItemSetChangeListener in interface Container.ItemSetChangeNotifier
    
    Overrides:
    
    addItemSetChangeListener in class AbstractContainer
  - removeListener
```
public void removeListener(Container.ItemSetChangeListener listener)
```
    Specified by:
    
    removeListener in interface Container.ItemSetChangeNotifier
    
    Overrides:
    
    removeListener in class AbstractContainer
  - removeItemSetChangeListener
```
public void removeItemSetChangeListener(Container.ItemSetChangeListener listener)
```
    Specified by:
    
    removeItemSetChangeListener in interface Container.ItemSetChangeNotifier
    
    Overrides:
    
    removeItemSetChangeListener in class AbstractContainer

Class AbstractQueryContainer<T>

Nested Class Summary

Nested classes/interfaces inherited from class com.vaadin.data.util.AbstractContainer

Nested classes/interfaces inherited from interface com.vaadin.data.Container.Indexed

Nested classes/interfaces inherited from interface com.vaadin.data.Container

Constructor Summary

Method Summary

Methods inherited from class com.vaadin.data.util.AbstractContainer

Methods inherited from class java.lang.Object

Constructor Detail

AbstractQueryContainer

AbstractQueryContainer

AbstractQueryContainer

AbstractQueryContainer

AbstractQueryContainer

Method Detail

getPropertyExtractor

setPropertyExtractor

getPropertyValue

setProperties

reload

connect

disconnect

query

invalidate

getJavaObject

ensureList

handleSizeChange

createBackedItem

getItem

getItemIds

getContainerPropertyIds

getContainerProperty

getType

size

containsId

addItem

addItem

removeItem

addContainerProperty

removeContainerProperty

removeAllItems

addItemAt

addItemAt

getIdByIndex

getItemIds

indexOfId

nextItemId

prevItemId

firstItemId

lastItemId

isFirstId

isLastId

addItemAfter

addItemAfter

addListener

addPropertySetChangeListener

removeListener

removePropertySetChangeListener

addListener

addItemSetChangeListener

removeListener

removeItemSetChangeListener