/**
 *                                                                            
 * Copyright (c) 2011, 2016 - Loetz GmbH&Co.KG (69115 Heidelberg, Germany)
 *                                                                            
 * All rights reserved. This program and the accompanying materials           
 * are made available under the terms of the Eclipse Public License 2.0        
 * which accompanies this distribution, and is available at                  
 * https://www.eclipse.org/legal/epl-2.0/                                 
 *                                 
 * SPDX-License-Identifier: EPL-2.0                                 
 *                                                                            
 * Contributors:   
 * Christophe Loetz (Loetz GmbH&Co.KG) - initial implementation 
 */
 package org.eclipse.osbp.infogrid.api;

import java.util.Locale;
import java.util.Map;

import org.eclipse.osbp.runtime.common.dispose.IDisposable;
import org.eclipse.osbp.infogrid.model.gridsource.CxGridSource;

/**
 * Subclasses know how to deal with a special kind of CxGridSource. They are
 * linking the consumer with the created Vaadin-Grid. They also need to handle
 * input values and changing locales.
 * 
 * @Scope(prototype)
 */
public interface IGridSourceDescriptor extends IDisposable {

	/**
	 * The kind-property is part of the CxGridSource model. Its default value is
	 * ecview. And it may be used to define several kinds of descriptors.
	 */
	public static final String PROP_KIND = "kind";

	public static final String KIND_ECVIEW = "ecview";
	public static final String KIND_VAADIN_NATIVE = "vaadin";

	/**
	 * Info grid shows 0-n-relations for a given input type.
	 */
	public static final String TAG__INFO_GRID = "infoGrid";

	/**
	 * Single grid can be seen as a table. It may also contain editable fields.
	 */
	public static final String TAG__SINGLE_GRID = "singleGrid";

	/**
	 * Returns the id of the grid source.
	 * 
	 * @return
	 */
	String getId();

	/**
	 * Returns a translated label of the source.
	 * 
	 * @return
	 */
	String getLabel();

	/**
	 * Returns the input type this descriptor accepts.
	 * 
	 * @return
	 */
	Class<?> getInputType();

	/**
	 * Returns the grid source itself.
	 * 
	 * @return
	 */
	CxGridSource getSource();

	/**
	 * Returns an UI component with a rendered instance of a grid component.
	 * 
	 * @return
	 */
	Object getComponent();

	/**
	 * Sets the input value for the UI component.
	 * 
	 * @param value
	 */
	void setInput(Object value);

	/**
	 * Sets the locale for the UI component.
	 * 
	 * @param value
	 */
	void setLocale(Locale locale);

	/**
	 * A callback to get required properties for the descriptor.
	 */
	interface ConfigCallback {

		/**
		 * Is called after the descriptor was created. So parties may configure
		 * the created descriptor properly.
		 * 
		 * @param descriptor
		 */
		Map<String, Object> getProperties(IGridSourceDescriptor descriptor);

	}

	/**
	 * Internal API. Needs a downcast.
	 */
	interface Internal {

		/**
		 * Sets the properties of the descriptor.
		 * 
		 * @param properties
		 */
		void setProperties(Map<String, Object> properties);
	}
}