001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package gov.nist.secauto.metaschema.databind.model.info;
007
008import gov.nist.secauto.metaschema.core.model.IBoundObject;
009import gov.nist.secauto.metaschema.databind.io.BindingException;
010
011import java.io.IOException;
012
013import edu.umd.cs.findbugs.annotations.NonNull;
014import edu.umd.cs.findbugs.annotations.Nullable;
015
016/**
017 * A feature interface for handling read, writing, and copying item objects,
018 * which are the data building blocks of a Metaschema module instance.
019 *
020 * @param <TYPE>
021 *          the Java type of the item
022 */
023public interface IItemValueHandler<TYPE> {
024  /**
025   * Parse and return an item.
026   *
027   * @param parent
028   *          the parent Java object to use for serialization callbacks, or
029   *          {@code null} if there is no parent
030   * @param handler
031   *          the item parsing handler
032   * @return the Java object representing the parsed item
033   * @throws IOException
034   *           if an error occurred while parsing
035   */
036  @Nullable
037  TYPE readItem(
038      @Nullable IBoundObject parent,
039      @NonNull IItemReadHandler handler) throws IOException;
040
041  /**
042   * Write the provided item.
043   *
044   * @param item
045   *          the data to write
046   * @param handler
047   *          the item writing handler
048   * @throws IOException
049   *           if an error occurred while writing
050   */
051  void writeItem(
052      @NonNull TYPE item,
053      @NonNull IItemWriteHandler handler) throws IOException;
054
055  /**
056   * Create and return a deep copy of the provided item.
057   *
058   * @param item
059   *          the item to copy
060   * @param parentInstance
061   *          an optional parent object to use for serialization callbacks
062   * @return the new deep copy
063   * @throws BindingException
064   *           if an error occurred while analyzing the bound objects
065   */
066  @NonNull
067  TYPE deepCopyItem(@NonNull TYPE item, @Nullable IBoundObject parentInstance) throws BindingException;
068}