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;
009
010import dev.metaschema.core.model.IBoundObject;
011import dev.metaschema.databind.io.BindingException;
012import edu.umd.cs.findbugs.annotations.NonNull;
013import edu.umd.cs.findbugs.annotations.Nullable;
014
015/**
016 * A feature interface for handling read, writing, and copying item objects,
017 * which are the data building blocks of a Metaschema module instance.
018 *
019 * @param <TYPE>
020 *          the Java type of the item
021 */
022/**
023 * Handler interface for processing bound item values.
024 * <p>
025 * This interface provides methods for reading and writing items, as well as
026 * deep copying items during binding operations.
027 *
028 * @param <TYPE>
029 *          the Java type of the handled item value
030 */
031public interface IItemValueHandler<TYPE> {
032  /**
033   * Parse and return an item.
034   *
035   * @param parent
036   *          the parent Java object to use for serialization callbacks, or
037   *          {@code null} if there is no parent
038   * @param handler
039   *          the item parsing handler
040   * @return the Java object representing the parsed item
041   * @throws IOException
042   *           if an error occurred while parsing
043   */
044  @Nullable
045  TYPE readItem(
046      @Nullable IBoundObject parent,
047      @NonNull IItemReadHandler handler) throws IOException;
048
049  /**
050   * Write the provided item.
051   *
052   * @param item
053   *          the data to write
054   * @param handler
055   *          the item writing handler
056   * @throws IOException
057   *           if an error occurred while writing
058   */
059  void writeItem(
060      @NonNull TYPE item,
061      @NonNull IItemWriteHandler handler) throws IOException;
062
063  /**
064   * Create and return a deep copy of the provided item.
065   *
066   * @param item
067   *          the item to copy
068   * @param parentInstance
069   *          an optional parent object to use for serialization callbacks
070   * @return the new deep copy
071   * @throws BindingException
072   *           if an error occurred while analyzing the bound objects
073   */
074  @NonNull
075  TYPE deepCopyItem(@NonNull TYPE item, @Nullable IBoundObject parentInstance) throws BindingException;
076}