com.holonplatform.vaadin7.data.container.ItemDataSourceContainer Maven / Gradle / Ivy

/*
 * Copyright 2016-2017 Axioma srl.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.holonplatform.vaadin7.data.container;

import com.holonplatform.core.query.QueryConfigurationProvider;
import com.holonplatform.core.query.QueryFilter;
import com.holonplatform.core.query.QuerySort;
import com.holonplatform.vaadin7.Registration;
import com.holonplatform.vaadin7.data.ItemDataProvider;
import com.holonplatform.vaadin7.data.ItemDataSource;
import com.holonplatform.vaadin7.data.container.ItemDataSourceContainerBuilder.BaseItemDataSourceContainerBuilder;
import com.holonplatform.vaadin7.internal.data.container.DefaultItemDataSourceContainerBuilder;
import com.vaadin.data.Buffered;
import com.vaadin.data.Container;
import com.vaadin.data.Container.Filterable;
import com.vaadin.data.Container.Indexed;
import com.vaadin.data.Container.ItemSetChangeNotifier;
import com.vaadin.data.Container.PropertySetChangeNotifier;
import com.vaadin.data.Container.Sortable;

/**
 * An indexed {@link Container} using an {@link ItemDataProvider} to load items on demand.
 * 
 * @param  Item property type
 * @param  Item type
 * 
 * @since 3.5.0
 */
public interface ItemDataSourceContainer extends ItemDataSource, Indexed, Buffered,
		Filterable, Sortable, ItemSetChangeNotifier, PropertySetChangeNotifier {

	/**
	 * Default batch (page) size for items loading using {@link ItemDataProvider}
	 */
	public static final int DEFAULT_BATCH_SIZE = 20;

	/**
	 * Set if auto-refresh is enabled for this container, i.e. items are loaded when one of the Container method which
	 * involve operations on item set is called.
	 * 
	 * If auto-refresh is not enabled, {@link #refresh()} method must be called to load items before using this
	 * Container.
	 * 
	 * @param autoRefresh true to enable auto-refresh
	 */
	void setAutoRefresh(boolean autoRefresh);

	/**
	 * Set max items cache size
	 * @param maxCacheSize Max cache size to set
	 */
	void setMaxCacheSize(int maxCacheSize);

	/**
	 * Adds an Item property to this container
	 * @param  Property type
	 * @param propertyId Property id
	 * @param type Property value type
	 * @param readOnly Whether property is read-only
	 * @param sortable Whether property is sortable
	 * @param defaultValue Property default value
	 * @return true if property was successfully added
	 */
	 boolean addContainerProperty(PROPERTY propertyId, Class type, boolean readOnly, boolean sortable,
			T defaultValue);

	/**
	 * Adds an Item property to this container
	 * @param propertyId Property id
	 * @param type Property value type
	 * @param readOnly Whether property is read-only
	 * @param sortable Whether property is sortable
	 * @return true if property was successfully added
	 */
	default boolean addContainerProperty(PROPERTY propertyId, Class type, boolean readOnly, boolean sortable) {
		return addContainerProperty(propertyId, type, readOnly, sortable, null);
	}

	/**
	 * Set whether the given propertyId can partecipate in container sorting
	 * @param propertyId Property id
	 * @param sortable Whether the property is sortable or not
	 */
	void setPropertySortable(PROPERTY propertyId, boolean sortable);

	/**
	 * Set whether the given propertyId is read-only
	 * @param propertyId Property id
	 * @param readOnly Whether the property is read-only
	 */
	void setPropertyReadOnly(PROPERTY propertyId, boolean readOnly);

	/**
	 * Set a default value to initialize the given propertyId
	 * @param propertyId Property id
	 * @param defaultValue Property default value
	 */
	void setPropertyDefaultValue(PROPERTY propertyId, Object defaultValue);

	/**
	 * Add an external {@link QueryConfigurationProvider} for additional query configuration
	 * @param queryConfigurationProvider QueryConfigurationProvider to add
	 * @return the configuration provider {@link Registration}
	 */
	Registration addQueryConfigurationProvider(QueryConfigurationProvider queryConfigurationProvider);

	/**
	 * Set query fixed filter (always added to query predicates)
	 * @param filter Query fixed filter, or null for none
	 */
	void setFixedFilter(QueryFilter filter);

	/**
	 * Set query default sort. If not null and no other sort is available, this one will be used
	 * @param sort Default query sort
	 */
	void setDefaultSort(QuerySort sort);

	/**
	 * Set query fixed sort (always added to query sorts)
	 * @param sort Query fixed sort, or null for none
	 */
	void setFixedSort(QuerySort sort);

	/**
	 * Add a query parameter
	 * @param name Parameter name
	 * @param value Parameter value
	 */
	void addQueryParameter(String name, Object value);

	/**
	 * Remove a query parameter
	 * @param name Parameter name to remove
	 */
	void removeQueryParameter(String name);

	/**
	 * Set a {@link PropertySortGenerator} to generate {@link QuerySort}s for given property
	 * @param property Property (not null)
	 * @param propertySortGenerator PropertySortGenerator (not null)
	 */
	void setPropertySortGenerator(PROPERTY property, PropertySortGenerator propertySortGenerator);

	/**
	 * Handler to manage items and item set modifications.
	 * @param commitHandler Item set commit handler
	 */
	void setCommitHandler(CommitHandler commitHandler);

	/**
	 * Refresh given the item identified by given itemId in data source
	 * @param itemId Id of the item to refresh (not null)
	 * @throws UnsupportedOperationException If the refresh operation is not supported by concrete data store
	 */
	void refreshItem(Object itemId);

	// Builders

	/**
	 * Get a builder to create an {@link ItemDataSourceContainer}.
	 * @param  Item property type
	 * @param  Item type
	 * @return {@link ItemDataSourceContainer} builder
	 */
	static  BaseItemDataSourceContainerBuilder builder() {
		return new DefaultItemDataSourceContainerBuilder<>();
	}

}