/*
 * SPDX-FileCopyrightText: none
 * SPDX-License-Identifier: CC0-1.0
 */

package dev.metaschema.databind.model.info;

import java.io.IOException;
import java.lang.reflect.Field;
import java.lang.reflect.ParameterizedType;
import java.lang.reflect.Type;
import java.util.Collection;
import java.util.List;
import java.util.Map;

import dev.metaschema.core.model.IBoundObject;
import dev.metaschema.core.model.JsonGroupAsBehavior;
import dev.metaschema.databind.io.BindingException;
import dev.metaschema.databind.model.IBoundInstanceModel;
import edu.umd.cs.findbugs.annotations.NonNull;
import edu.umd.cs.findbugs.annotations.Nullable;

// REFACTOR: parameterize the item type?
/**
 * Provides information about the collection type for a model instance.
 * <p>
 * This interface abstracts the differences between singleton, list, and map
 * collection types for model instances.
 *
 * @param <ITEM>
 *          the Java type of items in the collection
 */
public interface IModelInstanceCollectionInfo<ITEM> {

  /**
   * Create a new collection info instance for the provided model instance.
   * <p>
   * The appropriate collection info type is determined based on the instance's
   * maximum occurrence and JSON group-as behavior.
   *
   * @param <T>
   *          the Java type of items in the collection
   * @param instance
   *          the model instance to create collection info for
   * @return the new collection info instance
   */
  @NonNull
  static <T> IModelInstanceCollectionInfo<T> of(
      @NonNull IBoundInstanceModel<T> instance) {

    // create the collection info
    Type type = instance.getType();
    Field field = instance.getField();

    IModelInstanceCollectionInfo<T> retval;
    if (instance.getMaxOccurs() == -1 || instance.getMaxOccurs() > 1) {
      // collection case
      JsonGroupAsBehavior jsonGroupAs = instance.getJsonGroupAsBehavior();

      // expect a ParameterizedType
      if (!(type instanceof ParameterizedType)) {
        switch (jsonGroupAs) {
        case KEYED:
          throw new IllegalStateException(
              String.format("The field '%s' on class '%s' has data type of '%s'," + " but should have a type of '%s'.",
                  field.getName(),
                  field.getDeclaringClass().getName(),
                  field.getType().getName(), Map.class.getName()));
        case LIST:
        case SINGLETON_OR_LIST:
          throw new IllegalStateException(
              String.format("The field '%s' on class '%s' has data type of '%s'," + " but should have a type of '%s'.",
                  field.getName(),
                  field.getDeclaringClass().getName(),
                  field.getType().getName(), List.class.getName()));
        default:
          // this should not occur
          throw new IllegalStateException(jsonGroupAs.name());
        }
      }

      Class<?> rawType = (Class<?>) ((ParameterizedType) type).getRawType();
      if (JsonGroupAsBehavior.KEYED.equals(jsonGroupAs)) {
        if (!Map.class.isAssignableFrom(rawType)) {
          throw new IllegalArgumentException(String.format(
              "The field '%s' on class '%s' has data type '%s', which is not the expected '%s' derived data type.",
              field.getName(),
              field.getDeclaringClass().getName(),
              field.getType().getName(),
              Map.class.getName()));
        }
        retval = new MapCollectionInfo<>(instance);
      } else {
        if (!List.class.isAssignableFrom(rawType)) {
          throw new IllegalArgumentException(String.format(
              "The field '%s' on class '%s' has data type '%s', which is not the expected '%s' derived data type.",
              field.getName(),
              field.getDeclaringClass().getName(),
              field.getType().getName(),
              List.class.getName()));
        }
        retval = new ListCollectionInfo<>(instance);
      }
    } else {
      // single value case
      if (type instanceof ParameterizedType) {
        throw new IllegalStateException(String.format(
            "The field '%s' on class '%s' has a data parmeterized type of '%s',"
                + " but the occurance is not multi-valued.",
            field.getName(),
            field.getDeclaringClass().getName(),
            field.getType().getName()));
      }
      retval = new SingletonCollectionInfo<>(instance);
    }
    return retval;
  }

  /**
   * Get the associated instance binding for which this info is for.
   *
   * @return the instance binding
   */
  @NonNull
  IBoundInstanceModel<ITEM> getInstance();

  /**
   * Get the number of items associated with the value.
   *
   * @param value
   *          the value to identify items for
   * @return the number of items, which will be {@code 0} if value is {@code null}
   */
  int size(@Nullable Object value);

  /**
   * Determine if the value is empty.
   *
   * @param value
   *          the value representing a collection
   * @return {@code true} if the value represents a collection with no items or
   *         {@code false} otherwise
   */
  boolean isEmpty(@Nullable Object value);

  /**
   * Get the type of the bound object.
   *
   * @return the raw type of the bound object
   */
  @NonNull
  Class<? extends ITEM> getItemType();

  /**
   * Get the items from a parent instance's property value.
   *
   * @param parentInstance
   *          the parent instance to get items from
   * @return a collection of items, which may be empty but never {@code null}
   */
  @NonNull
  default Collection<? extends ITEM> getItemsFromParentInstance(@NonNull Object parentInstance) {
    Object value = getInstance().getValue(parentInstance);
    return getItemsFromValue(value);
  }

  /**
   * Get the items from a raw value object.
   *
   * @param value
   *          the value object to extract items from
   * @return a collection of items, which may be empty but never {@code null}
   */
  @NonNull
  Collection<? extends ITEM> getItemsFromValue(Object value);

  /**
   * Get an empty value appropriate for this collection type.
   *
   * @return an empty collection value, or {@code null} for singleton types
   */
  Object emptyValue();

  /**
   * Create a deep copy of items from one object to another.
   *
   * @param fromObject
   *          the source object to copy items from
   * @param toObject
   *          the target object to copy items to
   * @return the copied value
   * @throws BindingException
   *           if an error occurs during the deep copy
   */
  Object deepCopyItems(@NonNull IBoundObject fromObject, @NonNull IBoundObject toObject) throws BindingException;

  /**
   * Read the value data for the model instance.
   * <p>
   * This method will return a value based on the instance's value type.
   *
   * @param handler
   *          the item parsing handler
   * @return the item collection object or {@code null} if the instance is not
   *         defined
   * @throws IOException
   *           if there was an error when reading the data
   */
  @Nullable
  Object readItems(@NonNull IModelInstanceReadHandler<ITEM> handler) throws IOException;

  /**
   * Write the items represented by the given value.
   *
   * @param handler
   *          the item writing handler
   * @param value
   *          the value containing items to write
   * @throws IOException
   *           if there was an error when writing the data
   */
  void writeItems(
      @NonNull IModelInstanceWriteHandler<ITEM> handler,
      @NonNull Object value) throws IOException;
}