/*
 *  Copyright 2018 Anyware Services
 *
 *  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 org.ametys.plugins.repository.data.holder;

import java.util.Collection;
import java.util.Map;
import java.util.Optional;

import org.xml.sax.ContentHandler;
import org.xml.sax.SAXException;

import org.ametys.plugins.repository.data.UnknownDataException;
import org.ametys.plugins.repository.data.holder.group.Composite;
import org.ametys.plugins.repository.data.holder.impl.DataHolderHelper;
import org.ametys.plugins.repository.data.repositorydata.RepositoryData;
import org.ametys.plugins.repository.data.type.ModelItemTypeExtensionPoint;
import org.ametys.runtime.model.exception.BadDataPathCardinalityException;
import org.ametys.runtime.model.exception.BadItemTypeException;
import org.ametys.runtime.model.exception.NotUniqueTypeException;
import org.ametys.runtime.model.exception.UndefinedItemPathException;
import org.ametys.runtime.model.exception.UnknownTypeException;
import org.ametys.runtime.model.type.DataContext;
import org.ametys.runtime.model.type.ModelItemType;

/**
 * Interface for data containers
 */
public interface DataHolder
{
    /**
     * Retrieves the composite at the given path
     * @param compositePath path of the composite to retrieve
     * @return the composite or <code>null</code> if not exists or is empty
     * @throws IllegalArgumentException if the given composite path is null or empty
     * @throws UnknownTypeException if the type composite is not available for this data holder
     * @throws BadItemTypeException if the stored value at the given path is not a composite
     * @throws UndefinedItemPathException if the data holder has a model and the given composite path is not defined by this model
     * @throws BadDataPathCardinalityException if the data holder has a model and the definition of a part of the data path is multiple. Only the last part can be multiple
     */
    public Composite getComposite(String compositePath) throws IllegalArgumentException, UnknownTypeException, BadItemTypeException, UndefinedItemPathException, BadDataPathCardinalityException;
    
    /**
     * Checks if there is a non empty value for the data at the given path
     * @param dataPath path of the data
     * @return <code>true</code> if there is a non empty value for the data. If the data holder has a model and the data at the given path is defined by the model and the type of this value matches the type of the definition. <code>false</code> otherwise
     * @throws IllegalArgumentException if the given data path is null or empty
     * @throws BadDataPathCardinalityException if the data holder has a model and the definition of a part of the data path is multiple. Only the last part can be multiple
     * 
     * 
     */
    public boolean hasValue(String dataPath) throws IllegalArgumentException, BadDataPathCardinalityException;
    
    /**
     * Checks if there is a non empty value for the data at the given path
     * @param dataPath path of the data
     * @param dataTypeId type identifier of the data
     * @return <code>true</code> if there is a non empty value for the data. If the data holder has a model and the data at the given path is defined by the model and the type of this value matches the type of the definition. <code>false</code> otherwise
     * @throws IllegalArgumentException if the given data path is null or empty
     * @throws UnknownTypeException if the given type isn't available for this data holder's type extension point
     * @throws BadDataPathCardinalityException if the data holder has a model and the definition of a part of the data path is multiple. Only the last part can be multiple
     * 
     */
    public boolean hasValue(String dataPath, String dataTypeId) throws IllegalArgumentException, UnknownTypeException, BadDataPathCardinalityException;
    
    /**
     * Checks if there is a value, even empty, for the data at the given path
     * @param dataPath path of the data
     * @return <code>true</code> if there is value, even empty, for the data. If the data holder has a model and the data at the given path is defined by the model and the type of this value matches the type of the definition. <code>false</code> otherwise
     * @throws IllegalArgumentException if the given data path is null or empty
     * @throws BadDataPathCardinalityException if the data holder has a model and the definition of a part of the data path is multiple. Only the last part can be multiple
     * 
     */
    public boolean hasValueOrEmpty(String dataPath) throws IllegalArgumentException, BadDataPathCardinalityException;
    
    /**
     * Retrieves the names of data contained by this data holder
     * Retrieves only the data at first level, does not check composite data 
     * @return the names of all data contained by this data holder
     */
    public Collection<String> getDataNames();
    
    /**
     * Retrieves the value of the data at the given path
     * @param <T> type of the value to retrieve. If the data holder has a model, the type of the value is defined by this model. Otherwise, the type of the value will be deduced from the stored data. In some cases, the type can be wrong. For example, it is impossible to know if a stored date is a date or a date time
     * @param dataPath path of the data
     * @return the value of the data or <code>null</code> if not exists or is empty. A typed array is returned for multiple empty data, and an empty string is returned for single empty string data
     * @throws IllegalArgumentException if the given data path is null or empty
     * @throws UnknownTypeException if there is no compatible type with the data at the given data path
     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one)
     * @throws BadItemTypeException if the data holder has a model and the type defined by the model doesn't match the type of the stored value, or if value at the sub data path of the given one is not a composite
     * @throws UndefinedItemPathException if the data holder has a model and the given data path is not defined by this model
     * @throws BadDataPathCardinalityException if the data holder has a model and the definition of a part of the data path is multiple. Only the last part can be multiple
     */
    public <T> T getValue(String dataPath) throws IllegalArgumentException, UnknownTypeException, NotUniqueTypeException, BadItemTypeException, UndefinedItemPathException, BadDataPathCardinalityException;
    
    /**
     * Retrieves the value of the data at the given path if exists and is not empty, or the given default value
     * @param <T> type of the value to retrieve. If the data holder has a model, the type of the value is defined by this model. Otherwise, the type of the value will be deduced from the stored data. In some cases, the type can be wrong. For example, it is impossible to know if a stored date is a date or a date time
     * @param dataPath path of the data
     * @param defaultValue default value
     * @return the value of the data, or the given default value if the value does not exist or is empty
     * @throws IllegalArgumentException if the given data path is null or empty
     * @throws UnknownTypeException if there is no compatible type with the data at the given data path
     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one)
     * @throws BadItemTypeException if value at the sub data path of the given one is not a composite
     * @throws UndefinedItemPathException if the data holder has a model and the given data path is not defined by this model
     * @throws BadDataPathCardinalityException if the data holder has a model and the definition of a part of the data path is multiple. Only the last part can be multiple
     */
    public <T> T getValueOrDefault(String dataPath, T defaultValue) throws IllegalArgumentException, UnknownTypeException, NotUniqueTypeException, BadItemTypeException, UndefinedItemPathException, BadDataPathCardinalityException;
    
    /**
     * Retrieves the value of the data at the given path
     * @param <T> type of the value to retrieve. Should match the given data type
     * @param dataPath path of the data
     * @param dataTypeId type identifier of the data
     * @return the value of the data or <code>null</code> if not exists or is empty. A typed array is returned for multiple empty data, and an empty string is returned for single empty string data
     * @throws IllegalArgumentException if the given data path is null or empty
     * @throws UnknownTypeException if the given type isn't available for this data holder's type extension point
     * @throws BadItemTypeException if the given type doesn't match the type of the stored value at the given path
     * @throws UndefinedItemPathException if the data holder has a model and the given data path is not defined by this model
     * @throws BadDataPathCardinalityException if the data holder has a model and the definition of a part of the data path is multiple. Only the last part can be multiple
     */
    public <T> T getValueOfType(String dataPath, String dataTypeId) throws IllegalArgumentException, UnknownTypeException, BadItemTypeException, UndefinedItemPathException, BadDataPathCardinalityException;
    
    /**
     * Retrieves the value of the data at the given path if exists and is not empty, or the given default value
     * @param <T> type of the value to retrieve. Should match the given data type
     * @param dataPath path of the data
     * @param dataTypeId type identifier of the data
     * @param defaultValue default value
     * @return the value of the data, or the given default value if the value does not exist or is empty
     * @throws IllegalArgumentException if the given data path is null or empty
     * @throws UnknownTypeException if the given type isn't available for this data holder's type extension point
     * @throws BadItemTypeException if the given type doesn't match the type of the stored value at the given path
     * @throws UndefinedItemPathException if the data holder has a model and the given data path is not defined by this model
     * @throws BadDataPathCardinalityException if the data holder has a model and the definition of a part of the data path is multiple. Only the last part can be multiple
     */
    public <T> T getValueOfTypeOrDefault(String dataPath, String dataTypeId, T defaultValue) throws IllegalArgumentException, UnknownTypeException, BadItemTypeException, UndefinedItemPathException, BadDataPathCardinalityException;
    
    /**
     * Checks if the value of the data at the given path is multiple
     * @param dataPath path of the data to check
     * @return <code>true</code> if the value of the data is multiple, <code>false</code> otherwise
     * @throws IllegalArgumentException if the given data path is null or empty
     * @throws UnknownDataException the data at the given path does not exist
     * @throws UnknownTypeException if there is no compatible type with the data at the given data path
     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one)
     * @throws BadItemTypeException if value at the sub data path of the given one is not a composite
     * @throws UndefinedItemPathException if the data holder has a model and the given data path is not defined by this model
     */
    public boolean isMultiple(String dataPath) throws IllegalArgumentException, UnknownDataException, UnknownTypeException, NotUniqueTypeException, BadItemTypeException, UndefinedItemPathException;
    
    /**
     * Checks if the value of the data at the given path is multiple
     * @param dataPath path of the data to check
     * @param dataTypeId type identifier of the data
     * @return <code>true</code> if the value of the data is multiple, <code>false</code> otherwise
     * @throws IllegalArgumentException if the given data path is null or empty
     * @throws UnknownDataException the data at the given path does not exist
     * @throws UnknownTypeException if there is no compatible type with the data at the given data path
     * @throws BadItemTypeException if value at the sub data path of the given one is not a composite
     * @throws UndefinedItemPathException if the data holder has a model and the given data path is not defined by this model
     */
    public boolean isMultiple(String dataPath, String dataTypeId) throws IllegalArgumentException, UnknownDataException, UnknownTypeException, BadItemTypeException, UndefinedItemPathException;
    
    /**
     * Retrieves the type of the data at the given path
     * @param <X> type of the item type
     * @param dataPath path of the data
     * @return the type of the data
     * @throws IllegalArgumentException if the given data path is null or empty
     * @throws UnknownDataException if there is no data stored at the given path
     * @throws UnknownTypeException if there is no compatible type with the data at the given data path or if the data is a repeater entry but the composite type is not available
     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one)
     * @throws UndefinedItemPathException if the data holder has a model and the given data path is not defined by this model
     */
    public <X extends ModelItemType> X getType(String dataPath) throws IllegalArgumentException, UnknownDataException, UnknownTypeException, NotUniqueTypeException, UndefinedItemPathException;
    
    /**
     * Provide the ModelItemTypeExtensionPoint linked with the DataHolder
     * @return the extension point
     */
    public ModelItemTypeExtensionPoint getModelItemTypeExtensionPoint();
    
    /**
     * Copies the current {@link DataHolder} to the given {@link ModifiableDataHolder}.
     * @param dataHolder The destination dataHolder. Can not be null.
     * @throws UnknownTypeException if there is no available type compatible with the copied value for the type extension point of the destination {@link ModifiableDataHolder}
     * @throws NotUniqueTypeException if there is more than one available types compatibles with the copied value for the type extension point of the destination {@link ModifiableDataHolder}
     * @throws BadItemTypeException if type of a data to copy doesn't match the data with same path in the destination {@link ModifiableDataHolder}
     * @throws UndefinedItemPathException if the data holder has a model and the given data path is not defined by this model
     */
    public default void copyTo(ModifiableDataHolder dataHolder) throws UnknownTypeException, NotUniqueTypeException, BadItemTypeException, UndefinedItemPathException
    {
        copyTo(dataHolder, DataContext.newInstance());
    }
    
    /**
     * Copies the current {@link DataHolder} to the given {@link ModifiableDataHolder}.
     * @param dataHolder The destination dataHolder. Can not be null.
     * @param context The context of the data to copy
     * @throws UnknownTypeException if there is no available type compatible with the copied value for the type extension point of the destination {@link ModifiableDataHolder}
     * @throws NotUniqueTypeException if there is more than one available types compatibles with the copied value for the type extension point of the destination {@link ModifiableDataHolder}
     * @throws BadItemTypeException if type of a data to copy doesn't match the data with same path in the destination {@link ModifiableDataHolder}
     * @throws UndefinedItemPathException if the data holder has a model and the given data path is not defined by this model
     */
    public default void copyTo(ModifiableDataHolder dataHolder, DataContext context) throws UnknownTypeException, NotUniqueTypeException, BadItemTypeException, UndefinedItemPathException
    {
        DataHolderHelper.copyTo(this, dataHolder, context);
    }
    
    /**
     * Generates SAX events for data contained in this {@link DataHolder}
     * @param contentHandler the {@link ContentHandler} that will receive the SAX events
     * @throws SAXException if an error occurs during the SAX events generation
     * @throws UnknownTypeException if there is no compatible type with the saxed value
     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one) with the saxed value
     * @throws BadItemTypeException if the saxed value's type does not matches the stored data
     */
    public default void dataToSAX(ContentHandler contentHandler) throws SAXException, UnknownTypeException, NotUniqueTypeException, BadItemTypeException
    {
        dataToSAX(contentHandler, DataContext.newInstance());
    }
    
    /**
     * Generates SAX events for data contained in this {@link DataHolder}
     * @param contentHandler the {@link ContentHandler} that will receive the SAX events
     * @param context The context of the data to SAX
     * @throws SAXException if an error occurs during the SAX events generation
     * @throws UnknownTypeException if there is no compatible type with the saxed value
     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one) with the saxed value
     * @throws BadItemTypeException if the saxed value's type does not matches the stored data
     */
    public void dataToSAX(ContentHandler contentHandler, DataContext context) throws SAXException, UnknownTypeException, NotUniqueTypeException, BadItemTypeException;
    
    /**
     * Generates SAX events for the data at the given data path in the current {@link DataHolder}
     * Do not generate any event if there is no values at the given path
     * @param contentHandler the {@link ContentHandler} that will receive the SAX events
     * @param dataPath the path of the data to SAX
     * @throws SAXException if an error occurs during the SAX events generation
     * @throws UnknownTypeException if there is no compatible type with the saxed value
     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one) with the saxed value
     * @throws BadItemTypeException if the saxed value's type does not matches the stored data
     * @throws UndefinedItemPathException if the data holder has a model and the given data path is not defined by this model
     */
    public default void dataToSAX(ContentHandler contentHandler, String dataPath) throws SAXException, UnknownTypeException, NotUniqueTypeException, BadItemTypeException, UndefinedItemPathException
    {
        dataToSAX(contentHandler, dataPath, DataContext.newInstance());
    }
    
    /**
     * Generates SAX events for the data at the given data path in the current {@link DataHolder}
     * Do not generate any event if there is no values at the given path
     * @param contentHandler the {@link ContentHandler} that will receive the SAX events
     * @param dataPath the path of the data to SAX
     * @param context The context of the data to SAX
     * @throws SAXException if an error occurs during the SAX events generation
     * @throws UnknownTypeException if there is no compatible type with the saxed value
     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one) with the saxed value
     * @throws BadItemTypeException if the saxed value's type does not matches the stored data
     * @throws UndefinedItemPathException if the data holder has a model and the given data path is not defined by this model
     */
    public void dataToSAX(ContentHandler contentHandler, String dataPath, DataContext context) throws SAXException, UnknownTypeException, NotUniqueTypeException, BadItemTypeException, UndefinedItemPathException;
    
    /**
     * Convert the data contained in this {@link DataHolder}
     * @return The data of the current {@link DataHolder} as JSON
     * @throws UnknownTypeException if there is no compatible type with the value to convert
     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one) with the value to convert
     * @throws BadItemTypeException if the value's type does not matches the stored data
     */
    public default Map<String, Object> dataToJSON() throws UnknownTypeException, NotUniqueTypeException, BadItemTypeException
    {
        return dataToJSON(DataContext.newInstance());
    }
    
    /**
     * Convert the data contained in this {@link DataHolder}
     * @param context The context of the data to convert
     * @return The data of the current {@link DataHolder} as JSON
     * @throws UnknownTypeException if there is no compatible type with the value to convert
     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one) with the value to convert
     * @throws BadItemTypeException if the value's type does not matches the stored data
     */
    public Map<String, Object> dataToJSON(DataContext context) throws UnknownTypeException, NotUniqueTypeException, BadItemTypeException;
    
    /**
     * Convert the data at the given path into a JSON object
     * @param dataPath the path of the data to convert
     * @return The value as JSON
     * @throws UnknownTypeException if there is no compatible type with the value to convert
     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one) with the value to convert
     * @throws BadItemTypeException if the value's type does not matches the stored data
     * @throws UndefinedItemPathException if the data holder has a model and the given data path is not defined by this model
     */
    public default Object dataToJSON(String dataPath) throws UnknownTypeException, NotUniqueTypeException, BadItemTypeException, UndefinedItemPathException
    {
        return dataToJSON(dataPath, DataContext.newInstance());
    }
    
    /**
     * Convert the data at the given path into a JSON object
     * @param dataPath the path of the data to convert
     * @param context The context of the data to convert
     * @return The value as JSON
     * @throws UnknownTypeException if there is no compatible type with the value to convert
     * @throws NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one) with the value to convert
     * @throws BadItemTypeException if the value's type does not matches the stored data
     * @throws UndefinedItemPathException if the data holder has a model and the given data path is not defined by this model
     */
    public Object dataToJSON(String dataPath, DataContext context) throws UnknownTypeException, NotUniqueTypeException, BadItemTypeException, UndefinedItemPathException;
    
    /**
     * Check if there are differences between the given values and the current ones
     * @param values the values to check
     * @return <code>true</code> if there are differences, <code>false</code> otherwise
     * @throws UnknownTypeException if there is no available type compatible with a given value for this data holder's type extension point
     * @throws NotUniqueTypeException if there is more than one available types compatibles with the a value for this data holder's type extension point
     * @throws BadItemTypeException if value doesn't match the data at corresponding path
     */
    public boolean hasDifferences(Map<String, Object> values) throws UnknownTypeException, NotUniqueTypeException, BadItemTypeException;
    
    /**
     * Retrieves the repository data used by this {@link DataHolder}
     * @return the repository data used by this {@link DataHolder}
     */
    public RepositoryData getRepositoryData();
    
    /**
     * Retrieves the optional parent of the current {@link DataHolder}
     * There can be no parent if the current {@link DataHolder} is the root
     * @return the parent of the current {@link DataHolder}
     */
    public Optional<? extends DataHolder> getParentDataHolder();
    
    /**
     * Retrieves the {@link DataHolder} that is the root of the current one
     * @return the root {@link DataHolder}
     */
    public DataHolder getRootDataHolder();
}