/*
 *  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.Locale;

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

import org.ametys.plugins.repository.data.holder.group.Composite;
import org.ametys.plugins.repository.data.holder.group.Repeater;
import org.ametys.plugins.repository.data.holder.impl.DataHolderHelper;
import org.ametys.plugins.repository.metadata.MultilingualString;
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;

/**
 * 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
     * @throws IllegalArgumentException if the given composite path is null or empty
     * @throws BadItemTypeException if the value stored in the repository at the given path is not a composite
     */
    public Composite getComposite(String compositePath) throws IllegalArgumentException, BadItemTypeException;
    
    /**
     * Retrieves the repeater at the given path
     * @param repeaterPath path of the repeater to retrieve
     * @return the repeater or <code>null</code> if not exists
     * @throws IllegalArgumentException if the given repeater path is null or empty
     * @throws BadItemTypeException if the value stored in the repository at the given path is not a repeater
     */
    public Repeater getRepeater(String repeaterPath) throws IllegalArgumentException, BadItemTypeException;
    
    /**
     * Checks if there is a value for the data at the given path
     * @param dataPath path of the data
     * @throws IllegalArgumentException if the given data path is null or empty
     * @return <code>true</code> if there is value for the data, <code>false</code> otherwise
     */
    public boolean hasValue(String dataPath) throws IllegalArgumentException;
    
    /**
     * Retrieves the names of data contained by this data holder
     * @return the paths of all data contained by this data holder
     */
    public Collection<String> getDataNames();
    
    /**
     * Copies the current {@link DataHolder} to the given {@link ModifiableModelAwareDataHolder}.
     * @param dataHolder The destination dataHolder. Can not be null.
     * @throws UndefinedItemPathException if one of the copied data is not defined by the model of the destination {@link ModifiableModelAwareDataHolder}
     * @throws BadItemTypeException if the type defined by the model of the destination {@link ModifiableModelAwareDataHolder} doesn't match the copied value
     * @throws UnknownTypeException if there is no available type compatible with the copied value for the type extension point of the destination {@link ModifiableModelLessDataHolder}
     * @throws NotUniqueTypeException if there is more than one available types compatibles with the copied value for the type extension point of the destination {@link ModifiableModelLessDataHolder}
     */
    public default void copyTo(ModifiableDataHolder dataHolder) throws UndefinedItemPathException, BadItemTypeException, UnknownTypeException, NotUniqueTypeException
    {
        DataHolderHelper.copyDataHolder(this, dataHolder);
    }
    
    /**
     * Generates SAX events for current {@link DataHolder}
     * @param contentHandler the {@link ContentHandler} that will receive the SAX events
     * @throws SAXException if an error occurs during the SAX events generation
     */
    public default void toSAX(ContentHandler contentHandler) throws SAXException
    {
        toSAX(contentHandler, null);
    }
    
    /**
     * Generates SAX events for the current {@link DataHolder}
     * @param contentHandler the {@link ContentHandler} that will receive the SAX events
     * @param locale The locale to use for localized data, such as {@link MultilingualString}. Can be <code>null</code> to generate SAX events for all existing {@link Locale}s.
     * @throws SAXException if an error occurs during the SAX events generation
     */
    public default void toSAX(ContentHandler contentHandler, Locale locale) throws SAXException
    {
        DataHolderHelper.dataHolderToSAX(this, contentHandler, locale);
    }
    
    /**
     * 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
     */
    public default void dataToSAX(ContentHandler contentHandler, String dataPath) throws SAXException
    {
        dataToSAX(contentHandler, dataPath, null, null);
    }
    
    /**
     * 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 tagName the tag name of the SAX event to generate. If <code>null</code> the name of the data is used
     * @throws SAXException if an error occurs during the SAX events generation
     */
    public default void dataToSAX(ContentHandler contentHandler, String dataPath, String tagName) throws SAXException
    {
        dataToSAX(contentHandler, dataPath, tagName, null);
    }
    
    /**
     * 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 locale The locale to use for localized data, such as {@link MultilingualString}. Can be <code>null</code> to generate SAX events for all existing {@link Locale}s.
     * @throws SAXException if an error occurs during the SAX events generation
     */
    public default void dataToSAX(ContentHandler contentHandler, String dataPath, Locale locale) throws SAXException
    {
        dataToSAX(contentHandler, dataPath, null, locale);
    }
    
    /**
     * 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 tagName the tag name of the SAX event to generate. If <code>null</code> the name of the data is used
     * @param locale The locale to use for localized data, such as {@link MultilingualString}. Can be <code>null</code> to generate SAX events for all existing {@link Locale}s.
     * @throws SAXException if an error occurs during the SAX events generation
     */
    public default void dataToSAX(ContentHandler contentHandler, String dataPath, String tagName, Locale locale) throws SAXException
    {
        DataHolderHelper.dataHolderValueToSAX(this, contentHandler, dataPath, tagName, locale);
    }
}