001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package dev.metaschema.databind.model;
007
008import java.io.IOException;
009
010import dev.metaschema.core.model.IBoundObject;
011import dev.metaschema.core.qname.IEnhancedQName;
012import dev.metaschema.core.util.ObjectUtils;
013import dev.metaschema.databind.io.BindingException;
014import dev.metaschema.databind.model.info.IFeatureScalarItemValueHandler;
015import dev.metaschema.databind.model.info.IItemReadHandler;
016import dev.metaschema.databind.model.info.IItemWriteHandler;
017import edu.umd.cs.findbugs.annotations.NonNull;
018import edu.umd.cs.findbugs.annotations.Nullable;
019
020/**
021 * Represents the bound value of a field definition.
022 * <p>
023 * This interface provides access to the scalar value within a field, including
024 * support for JSON value key handling and default values.
025 */
026public interface IBoundFieldValue extends IFeatureScalarItemValueHandler, IBoundProperty<Object> {
027  @Override
028  @Nullable
029  Object getDefaultValue();
030
031  /**
032   * Get the field definition that contain's the field value.
033   *
034   * @return the parent field definition
035   */
036  @NonNull
037  IBoundDefinitionModelFieldComplex getParentFieldDefinition();
038
039  /**
040   * Get the name of the JSON value key flag.
041   * <p>
042   * Note: if a JSON value key flag is specified, then the JSON value key name is
043   * expected to be ignored.
044   *
045   * @return the flag name or {@code null} if no JSON value key flag is configured
046   * @see #getJsonValueKeyName()
047   */
048  @Nullable
049  String getJsonValueKeyFlagName();
050
051  /**
052   * Get the name of the JSON value key.
053   * <p>
054   * Note: if a JSON value key flag is specified, then this value is expected to
055   * be ignored.
056   *
057   * @return the name
058   * @see #getJsonValueKeyFlagName()
059   */
060  @NonNull
061  String getJsonValueKeyName();
062
063  @Override
064  default Object getEffectiveDefaultValue() {
065    return getDefaultValue();
066  }
067
068  @Override
069  default Object readItem(IBoundObject parent, IItemReadHandler handler) throws IOException {
070    return handler.readItemFieldValue(ObjectUtils.requireNonNull(parent, "parent"), this);
071  }
072
073  @Override
074  default void writeItem(Object item, IItemWriteHandler handler) throws IOException {
075    handler.writeItemFieldValue(item, this);
076  }
077
078  @Override
079  default void deepCopy(@NonNull IBoundObject fromInstance, @NonNull IBoundObject toInstance) throws BindingException {
080    Object value = getValue(fromInstance);
081    if (value != null) {
082      setValue(toInstance, value);
083    }
084  }
085
086  @Override
087  default boolean canHandleXmlQName(IEnhancedQName qname) {
088    // REFACTOR: Is this correct?
089    return getJavaTypeAdapter().canHandleQName(qname);
090  }
091
092}