com.helger.json.IJsonObject Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ph-json Show documentation
JSON reader and writer libary
The newest version!
/*
 * Copyright (C) 2014-2024 Philip Helger (www.helger.com)
 * philip[at]helger[dot]com
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *         http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.helger.json;

import java.util.Map;
import java.util.function.BiConsumer;
import java.util.function.Function;
import java.util.function.Predicate;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;

import com.helger.commons.annotation.ReturnsMutableCopy;
import com.helger.commons.collection.impl.ICommonsIterable;
import com.helger.commons.collection.impl.ICommonsList;
import com.helger.commons.collection.impl.ICommonsMap;
import com.helger.commons.collection.impl.ICommonsOrderedMap;
import com.helger.commons.collection.impl.ICommonsOrderedSet;
import com.helger.commons.state.EChange;
import com.helger.commons.string.StringHelper;
import com.helger.commons.traits.IGetterByKeyTrait;
import com.helger.json.convert.JsonConverter;

/**
 * Base interface for a JSON object that is a map from String to IJson
 *
 * @author Philip Helger
 */
public interface IJsonObject extends
                             IJsonCollection,
                             ICommonsIterable >,
                             IGetterByKeyTrait 
{
  /**
   * Add a new child JSON with the given name to this object.
   *
   * @param sName
   *        The name of the field. May not be null.
   * @param aValue
   *        The JSON object to be added. May not be null.
   * @return this for chaining
   */
  @Nonnull
  IJsonObject addJson (@Nonnull String sName, @Nonnull IJson aValue);

  @Nonnull
  default IJsonObject addJsonIf (@Nonnull final String sName,
                                 @Nonnull final IJson aValue,
                                 @Nonnull final Predicate  aFilter)
  {
    if (aFilter.test (aValue))
      addJson (sName, aValue);
    return this;
  }

  @Nonnull
  default IJsonObject addJsonIfNotNull (@Nonnull final String sName, @Nullable final IJson aValue)
  {
    if (aValue != null)
      addJson (sName, aValue);
    return this;
  }

  /**
   * Add at the specified value using the JSON converter
   *
   * @param sName
   *        The name of the item. May not be null.
   * @param aValue
   *        The value to be added. May be null.
   * @return this
   */
  @Nonnull
  default IJsonObject add (@Nonnull final String sName, @Nullable final Object aValue)
  {
    final IJson aJson = JsonConverter.convertToJson (aValue);
    return addJson (sName, aJson);
  }

  @Nonnull
  default  IJsonObject addIf (@Nonnull final String sName,
                                 @Nullable final T aValue,
                                 @Nonnull final Predicate  aFilter)
  {
    if (aFilter.test (aValue))
      add (sName, aValue);
    return this;
  }

  @Nonnull
  default IJsonObject addIfNotNull (@Nonnull final String sName, @Nullable final Object aValue)
  {
    if (aValue != null)
      add (sName, aValue);
    return this;
  }

  @Nonnull
  default IJsonObject addIfNotEmpty (@Nonnull final String sName, @Nullable final String sValue)
  {
    if (StringHelper.hasText (sValue))
      add (sName, sValue);
    return this;
  }

  @Nonnull
  default IJsonObject add (@Nonnull final Map.Entry  aEntry)
  {
    return add (aEntry.getKey (), aEntry.getValue ());
  }

  @Nonnull
  default IJsonObject add (@Nonnull final String sName, final boolean bValue)
  {
    return addJson (sName, JsonValue.create (bValue));
  }

  @Nonnull
  default IJsonObject add (@Nonnull final String sName, final char cValue)
  {
    return addJson (sName, JsonValue.create (cValue));
  }

  @Nonnull
  default IJsonObject add (@Nonnull final String sName, final double dValue)
  {
    return addJson (sName, JsonValue.create (dValue));
  }

  @Nonnull
  default IJsonObject add (@Nonnull final String sName, final int nValue)
  {
    return addJson (sName, JsonValue.create (nValue));
  }

  @Nonnull
  default IJsonObject add (@Nonnull final String sName, final long nValue)
  {
    return addJson (sName, JsonValue.create (nValue));
  }

  @Nonnull
  default IJsonObject addAll (@Nullable final Map  aMap)
  {
    if (aMap != null)
      for (final Map.Entry  aEntry : aMap.entrySet ())
        add (aEntry);
    return this;
  }

  /**
   * Add all entries of the passed object to this object. So this is a
   * "flattening add all".
   *
   * @param aObject
   *        The object to add from. May be null.
   * @return this for chaining
   */
  @Nonnull
  default IJsonObject addAll (@Nullable final IJsonObject aObject)
  {
    if (aObject != null)
      for (final Map.Entry  aEntry : aObject)
        add (aEntry);
    return this;
  }

  @Nonnull
  default  IJsonObject addAllMapped (@Nullable final Map  aMap,
                                                @Nonnull final Function  aValueMapper)
  {
    if (aMap != null)
      for (final Map.Entry  aEntry : aMap.entrySet ())
        addJson (aEntry.getKey (), aValueMapper.apply (aEntry.getValue ()));
    return this;
  }

  @Nonnull
  default  IJsonObject addAllMapped (@Nullable final Map  aMap,
                                                         @Nonnull final Function  aKeyMapper,
                                                         @Nonnull final Function  aValueMapper)
  {
    if (aMap != null)
      for (final Map.Entry  aEntry : aMap.entrySet ())
        addJson (aKeyMapper.apply (aEntry.getKey ()), aValueMapper.apply (aEntry.getValue ()));
    return this;
  }

  @Nullable
  IJson removeKeyAndReturnValue (@Nullable String sName);

  @Nonnull
  EChange removeKey (@Nullable String sName);

  boolean containsKey (@Nullable String sName);

  @Nonnull
  @ReturnsMutableCopy
  ICommonsOrderedSet  keySet ();

  @Nonnull
  @ReturnsMutableCopy
  ICommonsList  values ();

  /**
   * Get the element with the specified key.
   *
   * @param sName
   *        The name of the value to retrieve. May be null.
   * @return null if no value for the name exists.
   */
  @Nullable
  IJson get (@Nullable String sName);

  /**
   * Get the element with the specified key. This is the {@link IJsonValue}
   * specific version of {@link #get(String)}.
   *
   * @param sName
   *        The name of the value to retrieve. May be null.
   * @return null if no value for the name exists or if the value
   *         is not a {@link IJsonValue}.
   */
  @Nullable
  default Object getValue (@Nullable final String sName)
  {
    final IJson aJson = get (sName);
    if (aJson != null)
    {
      final IJsonValue aValue = aJson.getAsValue ();
      if (aValue != null)
        return aValue.getValue ();
    }
    return null;
  }

  /**
   * Get the element with the specified key. This is the {@link IJsonValue}
   * specific version of {@link #get(String)}.
   *
   * @param sName
   *        The name of the value to retrieve. May be null.
   * @return null if no value for the name exists or if the value
   *         is not a {@link IJsonValue}.
   */
  @Nullable
  default IJsonValue getAsValue (@Nullable final String sName)
  {
    final IJson aJson = get (sName);
    return aJson != null ? aJson.getAsValue () : null;
  }

  /**
   * Get the element with the specified key. This is the {@link IJsonArray}
   * specific version of {@link #get(String)}.
   *
   * @param sName
   *        The name of the value to retrieve. May be null.
   * @return null if no value for the name exists or if the value
   *         is not a {@link IJsonArray}.
   */
  @Nullable
  default IJsonArray getAsArray (@Nullable final String sName)
  {
    final IJson aJson = get (sName);
    return aJson != null ? aJson.getAsArray () : null;
  }

  /**
   * Get the element with the specified key. This is the {@link IJsonObject}
   * specific version of {@link #get(String)}.
   *
   * @param sName
   *        The name of the value to retrieve. May be null.
   * @return null if no value for the name exists or if the value
   *         is not a {@link IJsonObject}.
   */
  @Nullable
  default IJsonObject getAsObject (@Nullable final String sName)
  {
    final IJson aJson = get (sName);
    return aJson != null ? aJson.getAsObject () : null;
  }

  /**
   * @return A copy of all contained items. Never null but maybe
   *         empty.
   */
  @Nonnull
  @ReturnsMutableCopy
  ICommonsMap  getAll ();

  /**
   * Invoke the passed consumer on all entries of this object.
   *
   * @param aConsumer
   *        Consumer with the first param being the key and second param being
   *        the value.
   */
  void forEach (@Nonnull BiConsumer  aConsumer);

  /**
   * Check if the passed value is directly contained in the object or not.
   *
   * @param aValue
   *        The value to be checked for containment. May be null.
   * @return true if the value is contained, false if
   *         not.
   */
  boolean containsValue (@Nullable IJson aValue);

  /**
   * Check if the passed value is directly contained in the object or not.
   *
   * @param aValue
   *        The value to be checked for containment. May be null.
   * @return true if the value is contained, false if
   *         not.
   */
  default boolean containsValue (@Nullable final Object aValue)
  {
    return containsValue (JsonValue.create (aValue));
  }

  /**
   * Check if the passed value is directly contained in the object or not.
   *
   * @param bValue
   *        The value to be checked for containment.
   * @return true if the value is contained, false if
   *         not.
   */
  default boolean containsValue (final boolean bValue)
  {
    return containsValue (JsonValue.create (bValue));
  }

  /**
   * Check if the passed value is directly contained in the object or not.
   *
   * @param cValue
   *        The value to be checked for containment.
   * @return true if the value is contained, false if
   *         not.
   */
  default boolean containsValue (final char cValue)
  {
    return containsValue (JsonValue.create (cValue));
  }

  /**
   * Check if the passed value is directly contained in the object or not.
   *
   * @param dValue
   *        The value to be checked for containment.
   * @return true if the value is contained, false if
   *         not.
   */
  default boolean containsValue (final double dValue)
  {
    return containsValue (JsonValue.create (dValue));
  }

  /**
   * Check if the passed value is directly contained in the object or not.
   *
   * @param nValue
   *        The value to be checked for containment.
   * @return true if the value is contained, false if
   *         not.
   */
  default boolean containsValue (final int nValue)
  {
    return containsValue (JsonValue.create (nValue));
  }

  /**
   * Check if the passed value is directly contained in the object or not.
   *
   * @param nValue
   *        The value to be checked for containment.
   * @return true if the value is contained, false if
   *         not.
   */
  default boolean containsValue (final long nValue)
  {
    return containsValue (JsonValue.create (nValue));
  }

  /**
   * Compute a JSON value if it is not present.
   *
   * @param sName
   *        The name of the property. May not be null.
   * @param aValueProvider
   *        The value provider of the property. May not be null. Is
   *        only invoked, if the property is not present.
   * @return Either the existing property value, or the newly calculated
   *         property value.
   * @since 8.6.4
   */
  @Nullable
  default IJson computeIfAbsent (@Nonnull final String sName,
                                 @Nonnull final Function  aValueProvider)
  {
    IJson ret = get (sName);
    if (ret == null)
    {
      ret = aValueProvider.apply (sName);
      if (ret != null)
        addJson (sName, ret);
    }
    return ret;
  }

  /**
   * @return A map of all cloned values contained in this object in the same
   *         order. Never null.
   */
  @Nonnull
  @ReturnsMutableCopy
  ICommonsOrderedMap  getClonedValues ();

  @Nonnull
  IJsonObject getClone ();
}