com.vaadin.ui

Class AbstractListing<T>

java.lang.Object

com.vaadin.server.AbstractClientConnector

com.vaadin.ui.AbstractComponent

com.vaadin.ui.AbstractListing<T>

Type Parameters:

T - the item data type

All Implemented Interfaces:

HasItems<T>, ContextClickEvent.ContextClickNotifier, MethodEventSource, ClientConnector, Sizeable, Connector, Component, Component.Focusable, Serializable

Direct Known Subclasses:

AbstractMultiSelect, AbstractSingleSelect, Grid

public abstract class AbstractListing<T>
extends AbstractComponent
implements Component.Focusable, HasItems<T>

A base class for listing components. Provides common handling for fetching backend data items, selection logic, and server-client communication.

Note: concrete component implementations should implement the HasDataProvider or HasFilterableDataProvider interface.

Since:

8.0

Author:

Vaadin Ltd.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AbstractListing.AbstractListingExtension<T> A helper base class for creating extensions for Listing components.

Nested classes/interfaces inherited from interface com.vaadin.ui.Component

Component.ErrorEvent, Component.Event, Component.Focusable, Component.Listener

Nested classes/interfaces inherited from interface com.vaadin.server.ClientConnector

ClientConnector.AttachEvent, ClientConnector.AttachListener, ClientConnector.ConnectorErrorEvent, ClientConnector.DetachEvent, ClientConnector.DetachListener

Nested classes/interfaces inherited from interface com.vaadin.server.Sizeable

Sizeable.Unit

Field Summary

Fields inherited from class com.vaadin.ui.AbstractComponent

DESIGN_ATTR_PLAIN_TEXT

Fields inherited from interface com.vaadin.server.Sizeable

SIZE_UNDEFINED, UNITS_CM, UNITS_EM, UNITS_EX, UNITS_INCH, UNITS_MM, UNITS_PERCENTAGE, UNITS_PICAS, UNITS_PIXELS, UNITS_POINTS

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractListing() Creates a new AbstractListing with a default data communicator.
protected	AbstractListing(DataCommunicator<T> dataCommunicator) Creates a new AbstractListing with the given custom data communicator.

Method Summary

Modifier and Type	Method and Description
protected void	addDataGenerator(DataGenerator<T> generator) Adds the given data generator to this listing.
protected T	deserializeDeclarativeRepresentation(String item) Deserializes a string to a data item.
protected void	doReadDesign(org.jsoup.nodes.Element design, DesignContext context) Reads the listing specific state from the given design.
protected void	doWriteDesign(org.jsoup.nodes.Element design, DesignContext designContext) Writes listing specific state into the given design.
void	focus() Sets the focus for this component if the component is Focusable.
DataCommunicator<T>	getDataCommunicator() Returns the data communicator of this listing.
protected ItemCaptionGenerator<T>	getItemCaptionGenerator() Gets the item caption generator that is used to produce the strings shown in the combo box for each item.
protected IconGenerator<T>	getItemIconGenerator() Gets the currently used item icon generator.
protected AbstractListingState	getState() Returns the shared state bean with information to be sent from the server to the client.
protected AbstractListingState	getState(boolean markAsDirty) Returns the shared state for this connector.
int	getTabIndex() Gets the tabulator index of the Focusable component.
protected DataProvider<T,?>	internalGetDataProvider()
protected void	internalSetDataProvider(DataProvider<T,?> dataProvider)
protected <F> SerializableConsumer<F>	internalSetDataProvider(DataProvider<T,F> dataProvider, F initialFilter)
void	readDesign(org.jsoup.nodes.Element design, DesignContext context) Reads the component state from the given design.
protected T	readItem(org.jsoup.nodes.Element child, DesignContext context) Reads an Item from a design and inserts it into the data source.
protected abstract void	readItems(org.jsoup.nodes.Element design, DesignContext context) Reads the data source items from the design.
protected void	removeDataGenerator(DataGenerator<T> generator) Removes the given data generator from this listing.
protected String	serializeDeclarativeRepresentation(T item) Serializes an item to a string for saving declarative format.
protected void	setItemCaptionGenerator(ItemCaptionGenerator<T> itemCaptionGenerator) Sets the item caption generator that is used to produce the strings shown in the combo box for each item.
protected void	setItemIconGenerator(IconGenerator<T> itemIconGenerator) Sets the item icon generator that is used to produce custom icons for shown items.
void	setTabIndex(int tabIndex) Sets the tabulator index of the Focusable component.
void	writeDesign(org.jsoup.nodes.Element design, DesignContext designContext) Writes the component state to the given design.
protected org.jsoup.nodes.Element	writeItem(org.jsoup.nodes.Element design, T item, DesignContext context) Writes a data source Item to a design.
protected void	writeItems(org.jsoup.nodes.Element design, DesignContext context) Writes the data source items to a design.

Methods inherited from class com.vaadin.ui.AbstractComponent

addContextClickListener, addListener, addShortcutListener, addStyleName, attach, beforeClientResponse, detach, findAncestor, fireComponentErrorEvent, fireComponentEvent, getActionManager, getCaption, getComponentError, getCustomAttributes, getData, getDebugId, getDescription, getErrorMessage, getHeight, getHeightUnits, getIcon, getId, getLocale, getParent, getPrimaryStyleName, getStyleName, getWidth, getWidthUnits, isCaptionAsHtml, isConnectorEnabled, isEnabled, isOrHasAncestor, isReadOnly, isRequiredIndicatorVisible, isResponsive, isVisible, removeContextClickListener, removeListener, removeShortcutListener, removeStyleName, setCaption, setCaptionAsHtml, setComponentError, setData, setDebugId, setDescription, setDescription, setEnabled, setHeight, setHeight, setHeightUndefined, setIcon, setId, setLocale, setParent, setPrimaryStyleName, setReadOnly, setRequiredIndicatorVisible, setResponsive, setSizeFull, setSizeUndefined, setStyleName, setVisible, setWidth, setWidth, setWidthUndefined

Methods inherited from class com.vaadin.server.AbstractClientConnector

addAttachListener, addDetachListener, addExtension, addListener, addListener, addListener, addMethodInvocationToQueue, createState, encodeState, equals, fireEvent, getAllChildrenIterable, getConnectorId, getErrorHandler, getExtensions, getListeners, getResource, getRpcManager, getRpcProxy, getSession, getStateType, getUI, handleConnectorRequest, hashCode, hasListeners, isAttached, isThis, markAsDirty, markAsDirtyRecursive, registerRpc, registerRpc, removeAttachListener, removeDetachListener, removeExtension, removeListener, removeListener, removeListener, removeListener, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler, setResource, updateDiffstate

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.vaadin.data.HasItems

getDataProvider, setItems, setItems, setItems

Methods inherited from interface com.vaadin.ui.Component

addListener, addStyleName, addStyleNames, attach, getCaption, getDescription, getIcon, getId, getLocale, getParent, getPrimaryStyleName, getStyleName, getUI, isEnabled, isVisible, removeListener, removeStyleName, removeStyleNames, setCaption, setEnabled, setIcon, setId, setParent, setPrimaryStyleName, setStyleName, setStyleName, setVisible

Methods inherited from interface com.vaadin.server.ClientConnector

addAttachListener, addDetachListener, beforeClientResponse, detach, encodeState, getErrorHandler, getExtensions, getRpcManager, getStateType, handleConnectorRequest, isAttached, isConnectorEnabled, markAsDirty, markAsDirtyRecursive, removeAttachListener, removeDetachListener, removeExtension, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler

Methods inherited from interface com.vaadin.shared.Connector

getConnectorId

Methods inherited from interface com.vaadin.server.Sizeable

getHeight, getHeightUnits, getWidth, getWidthUnits, setHeight, setHeight, setHeightUndefined, setSizeFull, setSizeUndefined, setWidth, setWidth, setWidthUndefined

Constructor Detail

AbstractListing

protected AbstractListing()

Creates a new AbstractListing with a default data communicator.

AbstractListing

protected AbstractListing(DataCommunicator<T> dataCommunicator)

Creates a new AbstractListing with the given custom data communicator.

Note: This method is for creating an AbstractListing with a custom communicator. In the common case AbstractListing() should be used.

Parameters:

dataCommunicator - the data communicator to use, not null

Method Detail

internalSetDataProvider

protected void internalSetDataProvider(DataProvider<T,?> dataProvider)

internalSetDataProvider

protected <F> SerializableConsumer<F> internalSetDataProvider(DataProvider<T,F> dataProvider,
                                                              F initialFilter)

internalGetDataProvider

protected DataProvider<T,?> internalGetDataProvider()

getItemCaptionGenerator

protected ItemCaptionGenerator<T> getItemCaptionGenerator()

Gets the item caption generator that is used to produce the strings shown in the combo box for each item.

Returns:

the item caption generator used, not null

setItemCaptionGenerator

protected void setItemCaptionGenerator(ItemCaptionGenerator<T> itemCaptionGenerator)

Sets the item caption generator that is used to produce the strings shown in the combo box for each item. By default, String.valueOf(Object) is used.

Parameters:

itemCaptionGenerator - the item caption provider to use, not null

setItemIconGenerator

protected void setItemIconGenerator(IconGenerator<T> itemIconGenerator)

Sets the item icon generator that is used to produce custom icons for shown items. The generator can return null for items with no icon.

Implementations that support item icons make this method public.

Parameters:

itemIconGenerator - the item icon generator to set, not null

Throws:

NullPointerException - if itemIconGenerator is null

See Also:

IconGenerator

getItemIconGenerator

protected IconGenerator<T> getItemIconGenerator()

Gets the currently used item icon generator. The default item icon provider returns null for all items, resulting in no icons being used.

Implementations that support item icons make this method public.

Returns:

the currently used item icon generator, not null

See Also:

IconGenerator, setItemIconGenerator(IconGenerator)

addDataGenerator

protected void addDataGenerator(DataGenerator<T> generator)

Adds the given data generator to this listing. If the generator was already added, does nothing.

Parameters:

generator - the data generator to add, not null

removeDataGenerator

protected void removeDataGenerator(DataGenerator<T> generator)

Removes the given data generator from this listing. If this listing does not have the generator, does nothing.

Parameters:

generator - the data generator to remove, not null

getDataCommunicator

public DataCommunicator<T> getDataCommunicator()

Returns the data communicator of this listing.

Returns:

the data communicator, not null

writeDesign

public void writeDesign(org.jsoup.nodes.Element design,
                        DesignContext designContext)

Description copied from interface: Component

Writes the component state to the given design.

The component is responsible not only for writing its own state but also for ensuring that its children write their state to the design.

This method must not modify the component state.

Specified by:

writeDesign in interface Component

Overrides:

writeDesign in class AbstractComponent

Parameters:

design - The element to write the component state to. Any previous attributes or child nodes are not cleared.

designContext - The DesignContext instance used for writing the design

doWriteDesign

protected void doWriteDesign(org.jsoup.nodes.Element design,
                             DesignContext designContext)

Writes listing specific state into the given design.

This method is separated from writeDesign(Element, DesignContext) to be overridable in subclasses that need to replace this, but still must be able to call super.writeDesign(...).

Parameters:

design - The element to write the component state to. Any previous attributes or child nodes are not cleared.

designContext - The DesignContext instance used for writing the design

See Also:

doReadDesign(Element, DesignContext)

writeItems

protected void writeItems(org.jsoup.nodes.Element design,
                          DesignContext context)

Writes the data source items to a design. Hierarchical select components should override this method to only write the root items.

Parameters:

design - the element into which to insert the items

context - the DesignContext instance used in writing

writeItem

protected org.jsoup.nodes.Element writeItem(org.jsoup.nodes.Element design,
                                            T item,
                                            DesignContext context)

Writes a data source Item to a design. Hierarchical select components should override this method to recursively write any child items as well.

Parameters:

design - the element into which to insert the item

item - the item to write

context - the DesignContext instance used in writing

Returns:

a JSOUP element representing the item

readDesign

public void readDesign(org.jsoup.nodes.Element design,
                       DesignContext context)

Description copied from interface: Component

Reads the component state from the given design.

The component is responsible not only for updating its own state but also for ensuring that its children update their state based on the design.

It is assumed that the component is in its default state when this method is called. Reading should only take into consideration attributes specified in the design and not reset any unspecified attributes to their defaults.

This method must not modify the design.

Specified by:

readDesign in interface Component

Overrides:

readDesign in class AbstractComponent

Parameters:

design - The element to obtain the state from

context - The DesignContext instance used for parsing the design

doReadDesign

protected void doReadDesign(org.jsoup.nodes.Element design,
                            DesignContext context)

Reads the listing specific state from the given design.

This method is separated from readDesign(Element, DesignContext) to be overridable in subclasses that need to replace this, but still must be able to call super.readDesign(...).

Parameters:

design - The element to obtain the state from

context - The DesignContext instance used for parsing the design

See Also:

doWriteDesign(Element, DesignContext)

readItems

protected abstract void readItems(org.jsoup.nodes.Element design,
                                  DesignContext context)

Reads the data source items from the design.

Parameters:

design - The element to obtain the state from

context - The DesignContext instance used for parsing the design

readItem

protected T readItem(org.jsoup.nodes.Element child,
                     DesignContext context)

Reads an Item from a design and inserts it into the data source.

Doesn't care about selection/value (if any).

Parameters:

child - a child element representing the item

context - the DesignContext instance used in parsing

Returns:

the item id of the new item

Throws:

DesignException - if the tag name of the child element is not option.

deserializeDeclarativeRepresentation

protected T deserializeDeclarativeRepresentation(String item)

Deserializes a string to a data item.

Default implementation is able to handle only String as an item type. There will be a ClassCastException if T is not a String.

Parameters:

item - string to deserialize

Returns:

deserialized item

Throws:

ClassCastException - if type T is not a String

See Also:

serializeDeclarativeRepresentation(Object)

serializeDeclarativeRepresentation

protected String serializeDeclarativeRepresentation(T item)

Serializes an item to a string for saving declarative format.

Default implementation delegates a call to item.toString().

Parameters:

item - a data item

Returns:

string representation of the item.

See Also:

deserializeDeclarativeRepresentation(String)

getState

protected AbstractListingState getState()

Description copied from class: AbstractComponent

Returns the shared state bean with information to be sent from the server to the client. Subclasses should override this method and set any relevant fields of the state returned by super.getState().

Overrides:

getState in class AbstractComponent

Returns:

updated component shared state

getState

protected AbstractListingState getState(boolean markAsDirty)

Description copied from class: AbstractClientConnector

Returns the shared state for this connector.

Overrides:

getState in class AbstractComponent

Parameters:

markAsDirty - true if the connector should automatically be marked dirty, false otherwise

Returns:

The shared state for this connector. Never null.

See Also:

AbstractClientConnector.getState()

focus

public void focus()

Description copied from class: AbstractComponent

Sets the focus for this component if the component is Focusable.

Specified by:

focus in interface Component.Focusable

Overrides:

focus in class AbstractComponent

See Also:

FieldEvents, FieldEvents.FocusEvent, FieldEvents.FocusListener, FieldEvents.BlurEvent, FieldEvents.BlurListener

getTabIndex

public int getTabIndex()

Description copied from interface: Component.Focusable

Gets the tabulator index of the Focusable component.

Specified by:

getTabIndex in interface Component.Focusable

Returns:

tab index set for the Focusable component

See Also:

Component.Focusable.setTabIndex(int)

setTabIndex

public void setTabIndex(int tabIndex)

Description copied from interface: Component.Focusable

Sets the tabulator index of the Focusable component. The tab index property is used to specify the order in which the fields are focused when the user presses the Tab key. Components with a defined tab index are focused sequentially first, and then the components with no tab index.

 Form loginBox = new Form();
 loginBox.setCaption("Login");
 layout.addComponent(loginBox);

 // Create the first field which will be focused
 TextField username = new TextField("User name");
 loginBox.addField("username", username);

 // Set focus to the user name
 username.focus();

 TextField password = new TextField("Password");
 loginBox.addField("password", password);

 Button login = new Button("Login");
 loginBox.getFooter().addComponent(login);

 // An additional component which natural focus order would
 // be after the button.
 CheckBox remember = new CheckBox("Remember me");
 loginBox.getFooter().addComponent(remember);

 username.setTabIndex(1);
 password.setTabIndex(2);
 remember.setTabIndex(3); // Different than natural place
 login.setTabIndex(4);
 

After all focusable user interface components are done, the browser can begin again from the component with the smallest tab index, or it can take the focus out of the page, for example, to the location bar.

If the tab index is not set (is set to zero), the default tab order is used. The order is somewhat browser-dependent, but generally follows the HTML structure of the page.

A negative value means that the component is completely removed from the tabulation order and can not be reached by pressing the Tab key at all.

Specified by:

setTabIndex in interface Component.Focusable

Parameters:

tabIndex - the tab order of this component. Indexes usually start from 1. Zero means that default tab order should be used. A negative value means that the field should not be included in the tabbing sequence.

See Also:

Component.Focusable.getTabIndex()