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

package dev.metaschema.databind.io.json;

import com.fasterxml.jackson.core.JsonLocation;
import com.fasterxml.jackson.core.JsonParser;
import com.fasterxml.jackson.core.JsonToken;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.node.JsonNodeFactory;
import com.fasterxml.jackson.databind.node.ObjectNode;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.eclipse.jdt.annotation.NotOwning;

import java.io.IOException;
import java.net.URI;
import java.util.Collection;
import java.util.Deque;
import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;

import dev.metaschema.core.model.IAnyInstance;
import dev.metaschema.core.model.IBoundObject;
import dev.metaschema.core.model.IResourceLocation;
import dev.metaschema.core.model.SimpleResourceLocation;
import dev.metaschema.core.model.util.JsonUtil;
import dev.metaschema.core.util.ObjectUtils;
import dev.metaschema.databind.io.BindingException;
import dev.metaschema.databind.io.Format;
import dev.metaschema.databind.io.PathTracker;
import dev.metaschema.databind.io.ValidationContext;
import dev.metaschema.databind.model.IBoundDefinitionModelAssembly;
import dev.metaschema.databind.model.IBoundDefinitionModelComplex;
import dev.metaschema.databind.model.IBoundDefinitionModelFieldComplex;
import dev.metaschema.databind.model.IBoundFieldValue;
import dev.metaschema.databind.model.IBoundInstance;
import dev.metaschema.databind.model.IBoundInstanceFlag;
import dev.metaschema.databind.model.IBoundInstanceModel;
import dev.metaschema.databind.model.IBoundInstanceModelAny;
import dev.metaschema.databind.model.IBoundInstanceModelAssembly;
import dev.metaschema.databind.model.IBoundInstanceModelChoiceGroup;
import dev.metaschema.databind.model.IBoundInstanceModelFieldComplex;
import dev.metaschema.databind.model.IBoundInstanceModelFieldScalar;
import dev.metaschema.databind.model.IBoundInstanceModelGroupedAssembly;
import dev.metaschema.databind.model.IBoundInstanceModelGroupedField;
import dev.metaschema.databind.model.IBoundInstanceModelGroupedNamed;
import dev.metaschema.databind.model.IBoundProperty;
import dev.metaschema.databind.model.info.AbstractModelInstanceReadHandler;
import dev.metaschema.databind.model.info.IFeatureScalarItemValueHandler;
import dev.metaschema.databind.model.info.IItemReadHandler;
import dev.metaschema.databind.model.info.IModelInstanceCollectionInfo;
import edu.umd.cs.findbugs.annotations.NonNull;
import edu.umd.cs.findbugs.annotations.Nullable;
import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;

/**
 * Supports reading JSON-based Metaschema module instances.
 */
@SuppressWarnings({
    "PMD.CouplingBetweenObjects",
    "PMD.GodClass"
})
public class MetaschemaJsonReader
    implements IJsonParsingContext, IItemReadHandler {
  private static final Logger LOGGER = LogManager.getLogger(MetaschemaJsonReader.class);

  @NonNull
  private final Deque<JsonParser> parserStack = new LinkedList<>();
  // @NonNull
  // private final InstanceReader instanceReader = new InstanceReader();
  @NonNull
  private final URI source;
  @NonNull
  private final IJsonProblemHandler problemHandler;
  /**
   * Tracks the current parsing path for context-aware error reporting.
   */
  @NonNull
  private final PathTracker pathTracker = new PathTracker();

  /**
   * Construct a new Module-aware JSON parser using the default problem handler.
   *
   * @param parser
   *          the JSON parser to parse with
   * @param source
   *          the resource being parsed
   * @throws IOException
   *           if an error occurred while reading the JSON
   * @see DefaultJsonProblemHandler
   */
  @SuppressFBWarnings(value = "CT_CONSTRUCTOR_THROW", justification = "Use of final fields")
  public MetaschemaJsonReader(
      @NonNull JsonParser parser,
      @NonNull URI source) throws IOException {
    this(parser, source, new DefaultJsonProblemHandler());
  }

  /**
   * Construct a new Module-aware JSON parser.
   *
   * @param parser
   *          the JSON parser to parse with
   * @param source
   *          the resource being parsed
   * @param problemHandler
   *          the problem handler implementation to use
   * @throws IOException
   *           if an error occurred while reading the JSON
   */
  @SuppressFBWarnings(value = "CT_CONSTRUCTOR_THROW", justification = "Use of final fields")
  public MetaschemaJsonReader(
      @NonNull JsonParser parser,
      @NonNull URI source,
      @NonNull IJsonProblemHandler problemHandler) throws IOException {
    this.source = source;
    this.problemHandler = problemHandler;
    push(parser);
  }

  @SuppressWarnings("resource")
  @NotOwning
  @Override
  public JsonParser getReader() {
    return ObjectUtils.notNull(parserStack.peek());
  }

  @Override
  public URI getSource() {
    return source;
  }
  // protected void analyzeParserStack(@NonNull String action) throws IOException
  // {
  // StringBuilder builder = new StringBuilder()
  // .append("------\n");
  //
  // for (JsonParser parser : parserStack) {
  // JsonToken token = parser.getCurrentToken();
  // if (token == null) {
  // LOGGER.info(String.format("Advancing parser: %s", parser.hashCode()));
  // token = parser.nextToken();
  // }
  //
  // String name = parser.currentName();
  // builder.append(String.format("%s: %d: %s(%s)%s\n",
  // action,
  // parser.hashCode(),
  // token.name(),
  // name == null ? "" : name,
  // JsonUtil.generateLocationMessage(parser)));
  // }
  // LOGGER.info(builder.toString());
  // }

  @SuppressWarnings("resource")
  private void push(@NonNull JsonParser parser) throws IOException {
    assert !parser.equals(parserStack.peek());
    if (parser.getCurrentToken() == null) {
      parser.nextToken();
    }
    parserStack.push(parser);
  }

  @SuppressWarnings({ "resource", "PMD.CloseResource" })
  @NonNull
  private JsonParser pop(@NonNull JsonParser parser) {
    JsonParser old = parserStack.pop();
    assert parser.equals(old);
    return ObjectUtils.notNull(parserStack.peek());
  }

  @Override
  public IJsonProblemHandler getProblemHandler() {
    return problemHandler;
  }

  /**
   * Build a validation context from the current parser state.
   *
   * @return a new validation context with current location and path
   */
  @NonNull
  private ValidationContext buildValidationContext() {
    JsonParser parser = getReader();
    JsonLocation location = parser.currentLocation();
    IResourceLocation resourceLocation = JsonLocation.NA.equals(location)
        ? SimpleResourceLocation.UNKNOWN
        : SimpleResourceLocation.fromJsonLocation(location);
    return ValidationContext.of(source, resourceLocation, pathTracker.getCurrentPath(), Format.JSON);
  }

  /**
   * Read a JSON object value based on the provided definition.
   *
   * @param <T>
   *          the Java type of the bound object produced by this parser
   * @param definition
   *          the Metaschema module definition that describes the node to parse
   * @return the resulting parsed bound object
   * @throws IOException
   *           if an error occurred while parsing the content
   */
  @SuppressWarnings("unchecked")
  @NonNull
  public <T> T readObject(@NonNull IBoundDefinitionModelComplex definition) throws IOException {
    T value = (T) definition.readItem(null, this);
    if (value == null) {
      throw new IOException(String.format("Failed to read object '%s'%s.",
          definition.getDefinitionQName(),
          JsonUtil.generateLocationMessage(getReader(), getSource())));
    }
    return value;
  }

  /**
   * Read a JSON property based on the provided definition.
   *
   * @param <T>
   *          the Java type of the bound object produced by this parser
   * @param definition
   *          the Metaschema module definition that describes the node to parse
   * @param expectedFieldName
   *          the name of the JSON field to parse
   * @return the resulting parsed bound object
   * @throws IOException
   *           if an error occurred while parsing the content
   */
  @SuppressWarnings({
      "unchecked",
      "PMD.CyclomaticComplexity"
  })
  @NonNull
  public <T> T readObjectRoot(
      @NonNull IBoundDefinitionModelComplex definition,
      @NonNull String expectedFieldName) throws IOException {
    @SuppressWarnings("PMD.CloseResource")
    JsonParser parser = getReader();
    URI resource = getSource();

    boolean hasStartObject = JsonToken.START_OBJECT.equals(parser.currentToken());
    if (hasStartObject) {
      // advance past the start object
      JsonUtil.assertAndAdvance(parser, resource, JsonToken.START_OBJECT);
    }

    T retval = null;
    JsonToken token;
    while (!JsonToken.END_OBJECT.equals(token = parser.currentToken()) && token != null) {
      if (!JsonToken.FIELD_NAME.equals(token)) {
        throw new IOException(String.format("Expected FIELD_NAME token, found '%s'", token.toString()));
      }

      String propertyName = ObjectUtils.notNull(parser.currentName());
      if (expectedFieldName.equals(propertyName)) {
        // process the object value, bound to the requested class
        JsonUtil.assertAndAdvance(parser, resource, JsonToken.FIELD_NAME);

        // stop now, since we found the field
        retval = (T) definition.readItem(null, this);
        break;
      }

      if (!getProblemHandler().handleUnknownProperty(
          definition,
          null,
          propertyName,
          this)) {
        if (LOGGER.isWarnEnabled()) {
          LOGGER.warn("Skipping unhandled JSON field '{}'{}.", propertyName, JsonUtil.toString(parser, resource));
        }
        JsonUtil.skipNextValue(parser, resource);
      }
    }

    if (hasStartObject) {
      // advance past the end object
      JsonUtil.assertAndAdvance(parser, resource, JsonToken.END_OBJECT);
    }

    if (retval == null) {
      throw new IOException(String.format("Failed to find property with name '%s'%s.",
          expectedFieldName,
          JsonUtil.generateLocationMessage(parser, resource)));
    }
    return retval;
  }

  // ================
  // Instance readers
  // ================

  @Nullable
  private Object readInstance(
      @NonNull IBoundProperty<?> instance,
      @NonNull IBoundObject parent) throws IOException {
    return instance.readItem(parent, this);
  }

  @Nullable
  private <T> Object readModelInstance(
      @NonNull IBoundInstanceModel<T> instance,
      @NonNull IBoundObject parent) throws IOException {
    IModelInstanceCollectionInfo<T> collectionInfo = instance.getCollectionInfo();
    return collectionInfo.readItems(new ModelInstanceReadHandler<>(instance, parent));
  }

  private Object readFieldValue(
      @NonNull IBoundFieldValue instance,
      @NonNull IBoundObject parent) throws IOException {
    // handle the value key name case
    return instance.readItem(parent, this);
  }

  @Nullable
  private Object readObjectProperty(
      @NonNull IBoundObject parent,
      @NonNull IBoundProperty<?> property) throws IOException {
    Object retval;
    if (property instanceof IBoundInstanceModel) {
      retval = readModelInstance((IBoundInstanceModel<?>) property, parent);
    } else if (property instanceof IBoundInstance) {
      retval = readInstance(property, parent);
    } else { // IBoundFieldValue
      retval = readFieldValue((IBoundFieldValue) property, parent);
    }
    return retval;
  }

  @Override
  public Object readItemFlag(IBoundObject parentItem, IBoundInstanceFlag instance) throws IOException {
    return readScalarItem(instance);
  }

  @Override
  public Object readItemField(IBoundObject parentItem, IBoundInstanceModelFieldScalar instance) throws IOException {
    return readScalarItem(instance);
  }

  @Override
  public IBoundObject readItemField(IBoundObject parentItem, IBoundInstanceModelFieldComplex instance)
      throws IOException {
    return readFieldObject(
        parentItem,
        instance.getDefinition(),
        instance.getJsonProperties(),
        instance.getEffectiveJsonKey(),
        getProblemHandler());
  }

  @Override
  public IBoundObject readItemField(IBoundObject parentItem, IBoundInstanceModelGroupedField instance)
      throws IOException {
    IJsonProblemHandler problemHandler = new GroupedInstanceProblemHandler(instance, getProblemHandler());
    IBoundDefinitionModelFieldComplex definition = instance.getDefinition();
    IBoundInstanceFlag jsonValueKeyFlag = definition.getJsonValueKeyFlagInstance();

    IJsonProblemHandler actualProblemHandler = jsonValueKeyFlag == null
        ? problemHandler
        : new JsomValueKeyProblemHandler(problemHandler, jsonValueKeyFlag);

    return readComplexDefinitionObject(
        parentItem,
        definition,
        instance.getEffectiveJsonKey(),
        new PropertyBodyHandler(instance.getJsonProperties()),
        actualProblemHandler);
  }

  @Override
  public IBoundObject readItemField(IBoundObject parentItem, IBoundDefinitionModelFieldComplex definition)
      throws IOException {
    return readFieldObject(
        parentItem,
        definition,
        definition.getJsonProperties(),
        null,
        getProblemHandler());
  }

  @Override
  public Object readItemFieldValue(IBoundObject parentItem, IBoundFieldValue fieldValue) throws IOException {
    // read the field value's value
    return checkMissingFieldValue(readScalarItem(fieldValue));
  }

  @Nullable
  private Object checkMissingFieldValue(Object value) {
    if (value == null && LOGGER.isWarnEnabled()) {
      LOGGER.atWarn().log("Missing property value{}",
          JsonUtil.generateLocationMessage(getReader(), getSource()));
    }
    return value;
  }

  @Override
  public IBoundObject readItemAssembly(IBoundObject parentItem, IBoundInstanceModelAssembly instance)
      throws IOException {
    IBoundInstanceFlag jsonKey = instance.getJsonKey();
    IBoundDefinitionModelComplex definition = instance.getDefinition();
    return readComplexDefinitionObject(
        parentItem,
        definition,
        jsonKey,
        new PropertyBodyHandler(instance.getJsonProperties()),
        getProblemHandler());
  }

  @Override
  public IBoundObject readItemAssembly(IBoundObject parentItem, IBoundInstanceModelGroupedAssembly instance)
      throws IOException {
    return readComplexDefinitionObject(
        parentItem,
        instance.getDefinition(),
        instance.getEffectiveJsonKey(),
        new PropertyBodyHandler(instance.getJsonProperties()),
        new GroupedInstanceProblemHandler(instance, getProblemHandler()));
  }

  @Override
  public IBoundObject readItemAssembly(IBoundObject parentItem, IBoundDefinitionModelAssembly definition)
      throws IOException {
    return readComplexDefinitionObject(
        parentItem,
        definition,
        null,
        new PropertyBodyHandler(definition.getJsonProperties()),
        getProblemHandler());
  }

  @NonNull
  private Object readScalarItem(@NonNull IFeatureScalarItemValueHandler handler)
      throws IOException {
    return handler.getJavaTypeAdapter().parse(getReader(), getSource());
  }

  @NonNull
  private IBoundObject readFieldObject(
      @Nullable IBoundObject parentItem,
      @NonNull IBoundDefinitionModelFieldComplex definition,
      @NonNull Map<String, IBoundProperty<?>> jsonProperties,
      @Nullable IBoundInstanceFlag jsonKey,
      @NonNull IJsonProblemHandler problemHandler) throws IOException {
    IBoundInstanceFlag jsonValueKey = definition.getJsonValueKeyFlagInstance();
    IJsonProblemHandler actualProblemHandler = jsonValueKey == null
        ? problemHandler
        : new JsomValueKeyProblemHandler(problemHandler, jsonValueKey);

    IBoundObject retval;
    if (jsonProperties.isEmpty() && jsonValueKey == null) {
      retval = readComplexDefinitionObject(
          parentItem,
          definition,
          jsonKey,
          (def, parent, problem) -> {
            IBoundFieldValue fieldValue = definition.getFieldValue();
            Object item = readItemFieldValue(parent, fieldValue);
            if (item != null) {
              fieldValue.setValue(parent, item);
            }
          },
          actualProblemHandler);

    } else {
      retval = readComplexDefinitionObject(
          parentItem,
          definition,
          jsonKey,
          new PropertyBodyHandler(jsonProperties),
          actualProblemHandler);
    }
    return retval;
  }

  @NonNull
  private IBoundObject readComplexDefinitionObject(
      @Nullable IBoundObject parentItem,
      @NonNull IBoundDefinitionModelComplex definition,
      @Nullable IBoundInstanceFlag jsonKey,
      @NonNull DefinitionBodyHandler<IBoundDefinitionModelComplex> bodyHandler,
      @NonNull IJsonProblemHandler problemHandler) throws IOException {
    DefinitionBodyHandler<IBoundDefinitionModelComplex> actualBodyHandler = jsonKey == null
        ? bodyHandler
        : new JsonKeyBodyHandler(jsonKey, bodyHandler);

    JsonLocation location = getReader().currentLocation();

    // construct the item
    IBoundObject item = definition.newInstance(
        JsonLocation.NA.equals(location)
            ? null
            : () -> SimpleResourceLocation.fromJsonLocation(ObjectUtils.requireNonNull(location)));

    try {
      // call pre-parse initialization hook
      definition.callBeforeDeserialize(item, parentItem);

      // read the property values
      actualBodyHandler.accept(definition, item, problemHandler);

      // call post-parse initialization hook
      definition.callAfterDeserialize(item, parentItem);
    } catch (BindingException ex) {
      throw new IOException(ex);
    }

    return item;
  }

  @SuppressWarnings("resource")
  @Override
  public IBoundObject readChoiceGroupItem(IBoundObject parentItem, IBoundInstanceModelChoiceGroup instance)
      throws IOException {
    @SuppressWarnings("PMD.CloseResource")
    JsonParser parser = getReader();
    ObjectNode node = parser.readValueAsTree();

    String discriminatorProperty = instance.getJsonDiscriminatorProperty();
    JsonNode discriminatorNode = node.get(discriminatorProperty);
    if (discriminatorNode == null) {
      throw new IllegalArgumentException(String.format(
          "Unable to find discriminator property '%s' for object at '%s'.",
          discriminatorProperty,
          JsonUtil.toString(parser, getSource())));
    }
    String discriminator = ObjectUtils.requireNonNull(discriminatorNode.asText());

    IBoundInstanceModelGroupedNamed actualInstance = instance.getGroupedModelInstance(discriminator);
    assert actualInstance != null;

    IBoundObject retval;
    try (JsonParser newParser = node.traverse(parser.getCodec())) {
      assert newParser != null;
      push(newParser);

      // get initial token
      retval = actualInstance.readItem(parentItem, this);
      assert newParser.currentToken() == null;
      pop(newParser);
    }

    // advance the original parser to the next token
    parser.nextToken();

    return retval;
  }

  private final class JsonKeyBodyHandler implements DefinitionBodyHandler<IBoundDefinitionModelComplex> {
    @NonNull
    private final IBoundInstanceFlag jsonKey;
    @NonNull
    private final DefinitionBodyHandler<IBoundDefinitionModelComplex> bodyHandler;

    private JsonKeyBodyHandler(
        @NonNull IBoundInstanceFlag jsonKey,
        @NonNull DefinitionBodyHandler<IBoundDefinitionModelComplex> bodyHandler) {
      this.jsonKey = jsonKey;
      this.bodyHandler = bodyHandler;
    }

    @Override
    public void accept(
        IBoundDefinitionModelComplex definition,
        IBoundObject parent,
        IJsonProblemHandler problemHandler)
        throws IOException {
      @SuppressWarnings("PMD.CloseResource")
      JsonParser parser = getReader();
      URI resource = getSource();
      JsonUtil.assertCurrent(parser, resource, JsonToken.FIELD_NAME);

      // the field will be the JSON key
      String key = ObjectUtils.notNull(parser.currentName());
      try {
        Object value = jsonKey.getDefinition().getJavaTypeAdapter().parse(key);
        jsonKey.setValue(parent, ObjectUtils.notNull(value.toString()));
      } catch (IllegalArgumentException ex) {
        throw new IOException(
            String.format("Malformed data '%s'%s. %s",
                key,
                JsonUtil.generateLocationMessage(parser, resource),
                ex.getLocalizedMessage()),
            ex);
      }

      // skip to the next token
      parser.nextToken();
      // JsonUtil.assertCurrent(parser, JsonToken.START_OBJECT);

      // // advance past the JSON key's start object
      // JsonUtil.assertAndAdvance(parser, JsonToken.START_OBJECT);

      // read the property values
      bodyHandler.accept(definition, parent, problemHandler);

      // // advance past the JSON key's end object
      // JsonUtil.assertAndAdvance(parser, JsonToken.END_OBJECT);
    }
  }

  /**
   * Capture the next JSON property value as a {@link JsonNode} tree and advance
   * the parser past it. This method handles the parser being positioned at either
   * a {@link JsonToken#FIELD_NAME} or a value token. After this method returns,
   * the parser is positioned at the token immediately following the captured
   * value.
   *
   * @param parser
   *          the JSON parser
   * @param resource
   *          the resource being parsed
   * @return the captured value as a {@link JsonNode}
   * @throws IOException
   *           if an error occurred while reading
   */
  @SuppressWarnings({
      "resource", // parser not owned
      "PMD.CyclomaticComplexity" // acceptable
  })
  @NonNull
  private static JsonNode capturePropertyValue(
      @NonNull JsonParser parser,
      @NonNull URI resource) throws IOException {

    // skip the field name if present
    if (parser.currentToken() == JsonToken.FIELD_NAME) {
      parser.nextToken();
    }

    JsonNode retval = buildJsonValue(parser);
    // advance past the current value token (or past END_OBJECT/END_ARRAY
    // for containers which are left at the closing token by buildJsonValue)
    parser.nextToken();
    return retval;
  }

  /**
   * Recursively build a {@link JsonNode} from the current parser position. For
   * scalar values, reads the current token's value. For containers (objects and
   * arrays), recursively reads all nested content. After this method returns for
   * a container, the parser is positioned at the container's closing token
   * ({@code END_OBJECT} or {@code END_ARRAY}).
   *
   * @param parser
   *          the parser positioned at a value token
   * @return the value as a JsonNode
   * @throws IOException
   *           if an error occurred while reading
   */
  @SuppressWarnings("PMD.CyclomaticComplexity") // token type switch
  @NonNull
  private static JsonNode buildJsonValue(@NonNull JsonParser parser) throws IOException {
    JsonNodeFactory nodeFactory = JsonNodeFactory.instance;
    JsonToken token = parser.currentToken();

    switch (token) {
    case START_OBJECT: {
      ObjectNode obj = nodeFactory.objectNode();
      while (parser.nextToken() != JsonToken.END_OBJECT) {
        String fieldName = ObjectUtils.requireNonNull(parser.currentName());
        parser.nextToken(); // advance to value
        obj.set(fieldName, buildJsonValue(parser));
      }
      // parser is now at END_OBJECT
      return obj;
    }
    case START_ARRAY: {
      com.fasterxml.jackson.databind.node.ArrayNode arr = nodeFactory.arrayNode();
      while (parser.nextToken() != JsonToken.END_ARRAY) {
        arr.add(buildJsonValue(parser));
      }
      // parser is now at END_ARRAY
      return arr;
    }
    case VALUE_STRING:
      return nodeFactory.textNode(ObjectUtils.requireNonNull(parser.getText()));
    case VALUE_NUMBER_INT:
      return nodeFactory.numberNode(parser.getBigIntegerValue());
    case VALUE_NUMBER_FLOAT:
      return nodeFactory.numberNode(parser.getDecimalValue());
    case VALUE_TRUE:
      return nodeFactory.booleanNode(true);
    case VALUE_FALSE:
      return nodeFactory.booleanNode(false);
    case VALUE_NULL:
      return nodeFactory.nullNode();
    default:
      throw new IOException(
          String.format("Unexpected token '%s' when capturing JSON value.", token));
    }
  }

  private final class PropertyBodyHandler implements DefinitionBodyHandler<IBoundDefinitionModelComplex> {
    @NonNull
    private final Map<String, IBoundProperty<?>> jsonProperties;

    private PropertyBodyHandler(@NonNull Map<String, IBoundProperty<?>> jsonProperties) {
      this.jsonProperties = jsonProperties;
    }

    @Override
    public void accept(
        IBoundDefinitionModelComplex definition,
        IBoundObject parent,
        IJsonProblemHandler problemHandler)
        throws IOException {
      @SuppressWarnings("PMD.CloseResource")
      JsonParser parser = getReader();
      URI resource = getSource();

      // Track path for error messages
      pathTracker.push(definition.getEffectiveName());

      try {
        // advance past the start object
        JsonUtil.assertAndAdvance(parser, resource, JsonToken.START_OBJECT);

        // make a copy, since we use the remaining values to initialize default values
        Map<String, IBoundProperty<?>> remainingInstances = new HashMap<>(jsonProperties); // NOPMD not concurrent

        // Determine if this definition supports any content capture
        IBoundInstanceModelAny boundAny = resolveAnyInstance(definition);

        // Accumulator for unmodeled properties when any instance is present
        ObjectNode anyAccumulator = null;

        // handle each property
        while (JsonToken.FIELD_NAME.equals(parser.currentToken())) {

          // the parser's current token should be the JSON field name
          String propertyName = ObjectUtils.notNull(parser.currentName());
          if (LOGGER.isTraceEnabled()) {
            LOGGER.trace("reading property {}", propertyName);
          }

          IBoundProperty<?> property = remainingInstances.get(propertyName);

          boolean handled = false;
          if (property != null) {
            // advance past the field name
            parser.nextToken();

            Object value = readObjectProperty(parent, property);
            if (value != null) {
              property.setValue(parent, value);
            }

            // mark handled
            remainingInstances.remove(propertyName);
            handled = true;
          }

          if (!handled && !problemHandler.handleUnknownProperty(
              definition,
              parent,
              propertyName,
              MetaschemaJsonReader.this)) {
            if (boundAny != null) {
              // Capture the unmodeled property value into the any accumulator.
              // Advance past the field name to the value, then skip the value
              // using the same pattern as skipNextValue, but capture it.
              JsonNode value = capturePropertyValue(parser, resource);
              if (anyAccumulator == null) {
                anyAccumulator = new ObjectNode(JsonNodeFactory.instance);
              }
              anyAccumulator.set(propertyName, value);
            } else {
              if (LOGGER.isWarnEnabled()) {
                LOGGER.warn("Skipping unhandled JSON field '{}' {}.",
                    propertyName, JsonUtil.toString(parser, resource));
              }
              JsonUtil.assertAndAdvance(parser, resource, JsonToken.FIELD_NAME);
              JsonUtil.skipNextValue(parser, resource);
            }
          }

          // the current token will be either the next instance field name or the end of
          // the parent object
          JsonUtil.assertCurrent(parser, resource, JsonToken.FIELD_NAME, JsonToken.END_OBJECT);
        }

        // Set any captured content on the parent object
        if (boundAny != null && anyAccumulator != null && !anyAccumulator.isEmpty()) {
          boundAny.setAnyContent(parent, new JsonAnyContent(anyAccumulator));
        }

        // Build validation context with current location and path
        ValidationContext context = buildValidationContext();
        problemHandler.handleMissingInstances(
            definition,
            parent,
            ObjectUtils.notNull(remainingInstances.values()),
            context);

        // advance past the end object
        JsonUtil.assertAndAdvance(parser, resource, JsonToken.END_OBJECT);
      } finally {
        pathTracker.pop();
      }
    }

    /**
     * Resolve the bound any instance from the given definition, if available.
     *
     * @param definition
     *          the complex definition to check
     * @return the bound any instance, or {@code null} if the definition does not
     *         support any content
     */
    @Nullable
    private IBoundInstanceModelAny resolveAnyInstance(
        @NonNull IBoundDefinitionModelComplex definition) {
      if (definition instanceof IBoundDefinitionModelAssembly) {
        IAnyInstance anyInstance
            = ((IBoundDefinitionModelAssembly) definition).getModelContainer().getAnyInstance();
        if (anyInstance instanceof IBoundInstanceModelAny) {
          return (IBoundInstanceModelAny) anyInstance;
        }
      }
      return null;
    }
  }

  private static final class GroupedInstanceProblemHandler implements IJsonProblemHandler {
    @NonNull
    private final IBoundInstanceModelGroupedNamed instance;
    @NonNull
    private final IJsonProblemHandler delegate;

    private GroupedInstanceProblemHandler(
        @NonNull IBoundInstanceModelGroupedNamed instance,
        @NonNull IJsonProblemHandler delegate) {
      this.instance = instance;
      this.delegate = delegate;
    }

    @Override
    public void handleMissingInstances(
        IBoundDefinitionModelComplex parentDefinition,
        IBoundObject targetObject,
        Collection<? extends IBoundProperty<?>> unhandledInstances) throws IOException {
      delegate.handleMissingInstances(parentDefinition, targetObject, unhandledInstances);
    }

    @Override
    public void handleMissingInstances(
        IBoundDefinitionModelComplex parentDefinition,
        IBoundObject targetObject,
        Collection<? extends IBoundProperty<?>> unhandledInstances,
        ValidationContext context) throws IOException {
      delegate.handleMissingInstances(parentDefinition, targetObject, unhandledInstances, context);
    }

    @Override
    public boolean handleUnknownProperty(
        IBoundDefinitionModelComplex definition,
        IBoundObject parentItem,
        String fieldName,
        IJsonParsingContext parsingContext) throws IOException {
      boolean retval;
      if (instance.getParentContainer().getJsonDiscriminatorProperty().equals(fieldName)) {
        JsonUtil.skipNextValue(parsingContext.getReader(), parsingContext.getSource());
        retval = true;
      } else {
        retval = delegate.handleUnknownProperty(definition, parentItem, fieldName, parsingContext);
      }
      return retval;
    }
  }

  private final class JsomValueKeyProblemHandler implements IJsonProblemHandler {
    @NonNull
    private final IJsonProblemHandler delegate;
    @NonNull
    private final IBoundInstanceFlag jsonValueKeyFlag;
    private boolean foundJsonValueKey; // false

    private JsomValueKeyProblemHandler(
        @NonNull IJsonProblemHandler delegate,
        @NonNull IBoundInstanceFlag jsonValueKeyFlag) {
      this.delegate = delegate;
      this.jsonValueKeyFlag = jsonValueKeyFlag;
    }

    @Override
    public void handleMissingInstances(
        IBoundDefinitionModelComplex parentDefinition,
        IBoundObject targetObject,
        Collection<? extends IBoundProperty<?>> unhandledInstances) throws IOException {
      delegate.handleMissingInstances(parentDefinition, targetObject, unhandledInstances);
    }

    @Override
    public void handleMissingInstances(
        IBoundDefinitionModelComplex parentDefinition,
        IBoundObject targetObject,
        Collection<? extends IBoundProperty<?>> unhandledInstances,
        ValidationContext context) throws IOException {
      delegate.handleMissingInstances(parentDefinition, targetObject, unhandledInstances, context);
    }

    @Override
    public boolean handleUnknownProperty(
        IBoundDefinitionModelComplex definition,
        IBoundObject parentItem,
        String fieldName,
        IJsonParsingContext parsingContext) throws IOException {
      boolean retval;
      if (foundJsonValueKey) {
        retval = delegate.handleUnknownProperty(definition, parentItem, fieldName, parsingContext);
      } else {
        @SuppressWarnings("PMD.CloseResource")
        JsonParser parser = parsingContext.getReader();
        URI resource = parsingContext.getSource();

        // handle JSON value key
        String key = ObjectUtils.notNull(parser.currentName());
        try {
          Object keyValue = jsonValueKeyFlag.getJavaTypeAdapter().parse(key);
          jsonValueKeyFlag.setValue(ObjectUtils.notNull(parentItem), keyValue);
        } catch (IllegalArgumentException ex) {
          throw new IOException(
              String.format("Malformed data '%s'%s. %s",
                  key,
                  JsonUtil.generateLocationMessage(parser, resource),
                  ex.getLocalizedMessage()),
              ex);
        }
        // advance past the field name
        JsonUtil.assertAndAdvance(parser, resource, JsonToken.FIELD_NAME);

        IBoundFieldValue fieldValue = ((IBoundDefinitionModelFieldComplex) definition).getFieldValue();
        Object value = readItemFieldValue(ObjectUtils.notNull(parentItem), fieldValue);
        if (value != null) {
          fieldValue.setValue(ObjectUtils.notNull(parentItem), value);
        }

        retval = foundJsonValueKey = true;
      }
      return retval;
    }
  }

  private class ModelInstanceReadHandler<ITEM>
      extends AbstractModelInstanceReadHandler<ITEM> {

    protected ModelInstanceReadHandler(
        @NonNull IBoundInstanceModel<ITEM> instance,
        @NonNull IBoundObject parentItem) {
      super(instance, parentItem);
    }

    @Override
    public List<ITEM> readList() throws IOException {
      @SuppressWarnings("PMD.CloseResource")
      JsonParser parser = getReader();
      URI resource = getSource();

      List<ITEM> items = new LinkedList<>();
      switch (parser.currentToken()) {
      case START_ARRAY:
        // this is an array, we need to parse the array wrapper then each item
        JsonUtil.assertAndAdvance(parser, resource, JsonToken.START_ARRAY);

        // parse items
        while (!JsonToken.END_ARRAY.equals(parser.currentToken())) {
          items.add(readItem());
        }

        // this is the other side of the array wrapper, advance past it
        JsonUtil.assertAndAdvance(parser, resource, JsonToken.END_ARRAY);
        break;
      case VALUE_NULL:
        JsonUtil.assertAndAdvance(parser, resource, JsonToken.VALUE_NULL);
        break;
      default:
        // this is a singleton, just parse the value as a single item
        items.add(readItem());
        break;
      }
      return items;
    }

    @Override
    public Map<String, ITEM> readMap() throws IOException {
      @SuppressWarnings("PMD.CloseResource")
      JsonParser parser = getReader();
      URI resource = getSource();

      IBoundInstanceModel<?> instance = getCollectionInfo().getInstance();

      @SuppressWarnings("PMD.UseConcurrentHashMap")
      Map<String, ITEM> items = new LinkedHashMap<>();

      // A map value is always wrapped in a START_OBJECT, since fields are used for
      // the keys
      JsonUtil.assertAndAdvance(parser, resource, JsonToken.START_OBJECT);

      // process all map items
      while (!JsonToken.END_OBJECT.equals(parser.currentToken())) {

        // a map item will always start with a FIELD_NAME, since this represents the key
        JsonUtil.assertCurrent(parser, resource, JsonToken.FIELD_NAME);

        // get the object, since it must have a JSON key
        ITEM item = readItem();
        if (item == null) {
          throw new IOException(String.format("Null object encountered'%s.",
              JsonUtil.generateLocationMessage(parser, resource)));
        }

        // lookup the key
        IBoundInstanceFlag jsonKey = instance.getItemJsonKey(item);
        assert jsonKey != null;

        Object keyValue = jsonKey.getValue(item);
        if (keyValue == null) {
          throw new IOException(String.format("Null value for json-key for definition '%s'",
              jsonKey.getContainingDefinition().toCoordinates()));
        }
        String key;
        try {
          key = jsonKey.getJavaTypeAdapter().asString(keyValue);
        } catch (IllegalArgumentException ex) {
          throw new IOException(
              String.format("Malformed data '%s'%s. %s",
                  keyValue,
                  JsonUtil.generateLocationMessage(parser, resource),
                  ex.getLocalizedMessage()),
              ex);
        }
        items.put(key, item);

        // the next item will be a FIELD_NAME, or we will encounter an END_OBJECT if all
        // items have been
        // read
        JsonUtil.assertCurrent(parser, resource, JsonToken.FIELD_NAME, JsonToken.END_OBJECT);
      }

      // A map value will always end with an end object, which needs to be consumed
      JsonUtil.assertAndAdvance(parser, resource, JsonToken.END_OBJECT);

      return items;
    }

    @Override
    public ITEM readItem() throws IOException {
      IBoundInstanceModel<ITEM> instance = getCollectionInfo().getInstance();
      return instance.readItem(getParentObject(), MetaschemaJsonReader.this);
    }
  }

  @FunctionalInterface
  private interface DefinitionBodyHandler<DEF extends IBoundDefinitionModelComplex> {
    void accept(
        @NonNull DEF definition,
        @NonNull IBoundObject parent,
        @NonNull IJsonProblemHandler problemHandler) throws IOException;
  }
}