001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package dev.metaschema.databind.model.info;
007
008import java.io.IOException;
009import java.util.List;
010import java.util.Map;
011
012import edu.umd.cs.findbugs.annotations.NonNull;
013import edu.umd.cs.findbugs.annotations.Nullable;
014
015/**
016 * Handler interface for reading model instance collections during
017 * deserialization.
018 * <p>
019 * This interface provides methods for accepting individual items read from a
020 * stream and combining them into a collection.
021 *
022 * @param <ITEM>
023 *          the Java type of items being read
024 */
025public interface IModelInstanceReadHandler<ITEM> {
026  /**
027   * Read a singleton item.
028   *
029   * @return the item read, or {@code null} if no item was present
030   * @throws IOException
031   *           if an error occurred while reading the input
032   */
033  @Nullable
034  default ITEM readSingleton() throws IOException {
035    return readItem();
036  }
037
038  /**
039   * Read items into a list collection.
040   *
041   * @return the list of items read
042   * @throws IOException
043   *           if an error occurred while reading the input
044   */
045  @NonNull
046  List<ITEM> readList() throws IOException;
047
048  /**
049   * Read items into a map collection, keyed by JSON key flag value.
050   *
051   * @return the map of items read, keyed by JSON key flag value
052   * @throws IOException
053   *           if an error occurred while reading the input
054   */
055  @NonNull
056  Map<String, ITEM> readMap() throws IOException;
057
058  /**
059   * Read the next item in the collection of items represented by the instance.
060   *
061   * @return the Java object representing the item, or {@code null} if no items
062   *         remain to be read
063   * @throws IOException
064   *           if an error occurred while parsing the input
065   */
066  @Nullable
067  ITEM readItem() throws IOException;
068
069  /**
070   * Get the name of the JSON key flag, if one is configured for this instance.
071   *
072   * @return the JSON key flag name, or {@code null} if no JSON key is configured
073   */
074  @Nullable
075  String getJsonKeyFlagName();
076}