/*
 *  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.io.IOException;
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.impl.ModelLessComposite;
import org.ametys.plugins.repository.data.type.RepositoryModelItemType;
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.UnknownTypeException;
import org.ametys.runtime.model.type.DataContext;

/**
 * Interface for data containers without models
 */
public interface ModelLessDataHolder extends DataHolder
{
    /**
     * {@inheritDoc}
     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
     */
    @Override
    public ModelLessComposite getComposite(String compositePath) throws IllegalArgumentException, BadItemTypeException, BadDataPathCardinalityException;
    
    /**
     * {@inheritDoc}
     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
     */
    @Override
    public boolean hasValue(String dataPath) throws IllegalArgumentException, BadDataPathCardinalityException;
    
    /**
     * {@inheritDoc}
     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
     */
    @Override
    public boolean hasNonEmptyValue(String dataPath) throws IllegalArgumentException, BadDataPathCardinalityException;
    
    /**
     * Retrieves the value of the data at the given path
     * 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 <T> type of the value to retrieve. Should match the given data type
     * @param dataPath path of the data
     * @return the value of the data or <code>null</code> if not exists or is empty. The object returned may be of a generic class defined by the storage. For example, an url may be returned as a String. Use the 2 arguments version to ensure to get the right kind of Object.
     * @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 BadDataPathCardinalityException if the value 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, BadDataPathCardinalityException;
    
    /**
     * Retrieves the value of the data at the given path if exists and is not empty, or the default value
     * @param <T> type of the value to retrieve. Should match the given data type
     * @param dataPath path of the data
     * @param defaultValue default value
     * @return the value of the data, <code>null</code> if the data exists but is empty, or the given default value
     * @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 BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
     */
    public <T> T getValue(String dataPath, T defaultValue) throws IllegalArgumentException, UnknownTypeException, NotUniqueTypeException, 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
     * @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 BadDataPathCardinalityException if the value 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, BadDataPathCardinalityException;
    
    /**
     * Retrieves the value of the data at the given path if exists and is not empty, or the 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, <code>null</code> if the data exists but is empty, or the given default value
     * @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 BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
     */
    public <T> T getValueOfType(String dataPath, String dataTypeId, T defaultValue) throws IllegalArgumentException, UnknownTypeException, BadItemTypeException, 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 NotUniqueTypeException if there are many compatible types (there is no way to determine which type is the good one)
     * @throws BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
     */
    public boolean isMultiple(String dataPath) throws IllegalArgumentException, UnknownDataException, NotUniqueTypeException, BadDataPathCardinalityException;
    
    /**
     * Retrieves the type of the data at the given path
     * @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 BadDataPathCardinalityException if the value of a part of the data path is multiple. Only the last part can be multiple
     */
    public RepositoryModelItemType getType(String dataPath) throws IllegalArgumentException, UnknownDataException, UnknownTypeException, NotUniqueTypeException, BadDataPathCardinalityException;
    
    /**
     * 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 IOException if an error occurs while reading a value using the I/O API
     * @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
     */
    public default void dataToSAX(ContentHandler contentHandler) throws SAXException, IOException, UnknownTypeException, NotUniqueTypeException
    {
        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 IOException if an error occurs while reading a value using the I/O API
     * @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
     */
    public void dataToSAX(ContentHandler contentHandler, DataContext context) throws SAXException, IOException, UnknownTypeException, NotUniqueTypeException;
    
    @Override
    public Optional<? extends ModelLessDataHolder> getParentDataHolder();
    
    @Override
    public ModelLessDataHolder getRootDataHolder();
}