1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package dev.metaschema.databind.model.info;
7   
8   import java.io.IOException;
9   
10  import dev.metaschema.core.model.IBoundObject;
11  import dev.metaschema.databind.io.BindingException;
12  import edu.umd.cs.findbugs.annotations.NonNull;
13  import edu.umd.cs.findbugs.annotations.Nullable;
14  
15  /**
16   * A feature interface for handling read, writing, and copying item objects,
17   * which are the data building blocks of a Metaschema module instance.
18   *
19   * @param <TYPE>
20   *          the Java type of the item
21   */
22  /**
23   * Handler interface for processing bound item values.
24   * <p>
25   * This interface provides methods for reading and writing items, as well as
26   * deep copying items during binding operations.
27   *
28   * @param <TYPE>
29   *          the Java type of the handled item value
30   */
31  public interface IItemValueHandler<TYPE> {
32    /**
33     * Parse and return an item.
34     *
35     * @param parent
36     *          the parent Java object to use for serialization callbacks, or
37     *          {@code null} if there is no parent
38     * @param handler
39     *          the item parsing handler
40     * @return the Java object representing the parsed item
41     * @throws IOException
42     *           if an error occurred while parsing
43     */
44    @Nullable
45    TYPE readItem(
46        @Nullable IBoundObject parent,
47        @NonNull IItemReadHandler handler) throws IOException;
48  
49    /**
50     * Write the provided item.
51     *
52     * @param item
53     *          the data to write
54     * @param handler
55     *          the item writing handler
56     * @throws IOException
57     *           if an error occurred while writing
58     */
59    void writeItem(
60        @NonNull TYPE item,
61        @NonNull IItemWriteHandler handler) throws IOException;
62  
63    /**
64     * Create and return a deep copy of the provided item.
65     *
66     * @param item
67     *          the item to copy
68     * @param parentInstance
69     *          an optional parent object to use for serialization callbacks
70     * @return the new deep copy
71     * @throws BindingException
72     *           if an error occurred while analyzing the bound objects
73     */
74    @NonNull
75    TYPE deepCopyItem(@NonNull TYPE item, @Nullable IBoundObject parentInstance) throws BindingException;
76  }