/*
 *  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.runtime.model.type;

import java.io.IOException;
import java.util.Optional;
import java.util.stream.Stream;

import javax.xml.transform.TransformerException;

import org.apache.avalon.framework.configuration.Configuration;
import org.apache.avalon.framework.configuration.ConfigurationException;
import org.apache.commons.lang3.tuple.Triple;
import org.w3c.dom.Element;

import org.ametys.runtime.model.compare.DataChangeType;
import org.ametys.runtime.model.compare.DataChangeTypeDetail;
import org.ametys.runtime.model.exception.BadItemTypeException;

/**
 * Interface for element types
 * @param <T> Type of the element value
 */
public interface ElementType<T> extends ModelItemType
{
    /**
     * Cast the given value to an object of the corresponding type.<br>
     * It may be an untyped String value, or another Object, depending of what the type is actually compatible with.
     * @param value the value to cast
     * @return An object of the parameterized type representing the given value. Returns null if value cannot be cast
     * @throws BadItemTypeException if the String value can't be cast to the type
     */
    public T castValue(Object value) throws BadItemTypeException;
    
    /**
     * Cast a typed value to a String
     * @param value the value to cast
     * @return the String representation of the value
     */
    public String toString(T value);
    
    /**
     * Convert the given client side JSON object to the types value 
     * @param json the JSON object to convert
     * @return the typed value corresponding to the JSON object
     */
    public Object fromJSONForClient(Object json);
    
    /**
     * Convert the value into a JSON object to use client side
     * @param value the value to convert
     * @param context The context of the data to convert
     * @return The value as JSON
     */
    public Object valueToJSONForClient(Object value, DataContext context);
    
    /**
     * Parses the given configuration to get the typed value
     * @param configuration the configuration to parse
     * @return The typed value in the configuration
     * @throws ConfigurationException if an error occurs while parsing the configuration
     */
    public T parseConfiguration(Configuration configuration) throws ConfigurationException;
    
    /**
     * Parses the given DOM node to get the typed value
     * @param parent the DOM element containing the value
     * @param name the name of the item to read
     * @param additionalData additional data needed to get the typed value
     * @return the value
     * @throws TransformerException if an error occurs while parsing the DOM node
     * @throws IOException if an error occurs while parsing a value using the I/O API
     */
    public Object valueFromXML(Element parent, String name, Optional<Object> additionalData) throws TransformerException, IOException;
    
    /**
     * Compares the given values and retrieves the changes as a stream of {@link Triple}s. A {@link Triple} contains:
     * <ul>
     * <li>the general type of the change (added, modified or removed) as a {@link DataChangeType},</li>
     * <li>some details about this change if possible (after or before for a date, more or less for a number, ...) as a {@link DataChangeTypeDetail}</li>
     * <li>The data concerned by this change if not the element itself (or an empty String)</li>
     * </ul>
     * @param value1 the 1st value
     * @param value2 the 2nd value
     * @return the changes between the two given values as a stream of {@link Triple}. Retrieves an empty stream if there is no change
     * @throws IOException if an error occurs while comparing values using the I/O API
     */
    public Stream<Triple<DataChangeType, DataChangeTypeDetail, String>> compareValues(Object value1, Object value2) throws IOException;
    
    /**
     * Checks if the value is compatible with the element type 
     * @param value the value to check
     * @return <code>true</code> if the value matches the current type, <code>false</code> otherwise
     */
    public boolean isCompatible(Object value);
    
    /**
     * Determines if this type is simple or not.
     * A simple element type is a type of elements that can be edited in a grid
     * @return <code>true</code> if the type is simple, <code>false</code> otherwise
     */
    public boolean isSimple();
    
    /**
     * Get the class managed by the implementation
     * @return The class managed (T.class)
     */
    public Class<T> getManagedClass();

    /**
     * Get the class representing an array of managed class by the implementation
     * @return The class managed (T[].class)
     */
    public Class<T[]> getManagedClassArray();
}